

Tcl/Tk Documentation
====================

  [Tcl/Tk Applications](usercmd/contents.htm)
The interpreters which implement Tcl and Tk. [Tcl Commands](tclcmd/contents.htm "version 8.6.6")
The commands which the **tclsh** interpreter implements. [Tk Commands](tkcmd/contents.htm "version 8.6.6")
The additional commands which the **wish** interpreter implements. [[incr Tcl] Package Commands](itclcmd/contents.htm "version 4.0.5")
The additional commands provided by the [incr Tcl] package. [SQLite3 Package Commands](sqlitecmd/contents.htm "version 3.13.0")
The additional commands provided by the SQLite3 package. [TDBC Package Commands](tdbccmd/contents.htm "version 1.0.4")
The additional commands provided by the TDBC package. [tdbc::mysql Package Commands](tdbcmysqlcmd/contents.htm "version 1.0.4")
The additional commands provided by the tdbc::mysql package. [tdbc::odbc Package Commands](tdbcodbccmd/contents.htm "version 1.0.4")
The additional commands provided by the tdbc::odbc package. [tdbc::postgres Package Commands](tdbcpostgrescmd/contents.htm "version 1.0.4")
The additional commands provided by the tdbc::postgres package. [tdbc::sqlite3 Package Commands](tdbcsqlitecmd/contents.htm "version 1.0.4")
The additional commands provided by the tdbc::sqlite3 package. [Thread Package Commands](threadcmd/contents.htm "version 2.8.0")
The additional commands provided by the Thread package. [Tcl C API](https://www.tcl.tk/man/tcl/TclLib/contents.htm "version 8.6.6")
The C functions which a Tcl extended C program may use. [Tk C API](https://www.tcl.tk/man/tcl/TkLib/contents.htm "version 8.6.6")
The additional C functions which a Tk extended C program may use. [[incr Tcl] Package C API](https://www.tcl.tk/man/tcl/ItclLib/contents.htm "version 4.0.5")
The additional C functions provided by the [incr Tcl] package. [TDBC Package C API](https://www.tcl.tk/man/tcl/TdbcLib/contents.htm "version 1.0.4")
The additional C functions provided by the TDBC package. [Keywords](https://www.tcl.tk/man/tcl/Keywords/contents.htm)
The keywords from the Tcl/Tk man pages. 
 Copyright © 1989-1994 The Regents of the University of California  
 Copyright © 1992-1999 Karl Lehenbauer & Mark Diekhans  
 Copyright © 1992-1999 Karl Lehenbauer and Mark Diekhans  
 Copyright © 1993-1997 Bell Labs Innovations for Lucent Technologies  
 Copyright © 1993-1998 Lucent Technologies, Inc  
 Copyright © 1994 The Australian National University  
 Copyright © 1994-2000 Sun Microsystems, Inc  
 Copyright © 1997-2000 Ajuba Solutions  
 Copyright © 1997-2000 Scriptics Corporation  
 Copyright © 1998 Mark Harrison  
 Copyright © 2000 Jeffrey Hobbs  
 Copyright © 2001 ActiveState Tool Corp  
 Copyright © 2001 Vincent Darley  
 Copyright © 2001-2004 ActiveState Corporation  
 Copyright © 2001-2005 Kevin B. Kenny <kennykb(at)acm.org>  
 Copyright © 2001-2012 Donal K. Fellows  
 Copyright © 2002-2010 Andreas Kupries <andreas\_kupries(at)users.sourceforge.net>  
 Copyright © 2003 George Petasis <petasis(at)iit.demokritos.gr>  
 Copyright © 2003 Simon Geard  
 Copyright © 2003-2006 Joe English  
 Copyright © 2006 Miguel Sofer  
 Copyright © 2006-2008 ActiveState Software Inc  
 Copyright © 2006-2008 Daniel A. Steffen <das(at)users.sourceforge.net>  
 Copyright © 2006-2008 Joe Mistachkin  
 Copyright © 2008 Arnulf Wiedemann  
 Copyright © 2008 Jos Decoster  
 Copyright © 2008 Pat Thoyts  
 Copyright © 2008 Peter Spjuth <pspjuth(at)users.sourceforge.net>  
 Copyright © 2008-2010 Kevin B. Kenny  
 Copyright © 2011 Kevin Walzer  
 Copyright © 2012 Trevor Davel 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/contents.htm>

UserCmd
=======

 

|  |  |
| --- | --- |
| [tclsh](tclsh.htm "Simple shell containing Tcl interpreter") | [wish](wish.htm "Simple windowing shell") |

 Copyright © 1991-1994 The Regents of the University of California  
 Copyright © 1994-1996 Sun Microsystems, Inc 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/UserCmd/contents.htm>

tclsh
=====

  
[NAME](tclsh.htm#M2) tclsh — Simple shell containing Tcl interpreter 
[SYNOPSIS](tclsh.htm#M3) 
[DESCRIPTION](tclsh.htm#M4) 
[SCRIPT FILES](tclsh.htm#M5) 
[VARIABLES](tclsh.htm#M6)  
[**argc**](tclsh.htm#M7) 
[**argv**](tclsh.htm#M8) 
[**argv0**](tclsh.htm#M9) 
[**tcl\_interactive**](tclsh.htm#M10) 



 
[PROMPTS](tclsh.htm#M11) 
[STANDARD CHANNELS](tclsh.htm#M12) 
[SEE ALSO](tclsh.htm#M13) 
[KEYWORDS](tclsh.htm#M14) 








 Name
----

 tclsh — Simple shell containing Tcl interpreter Synopsis
--------

 **tclsh** ?**-encoding** *name*? ?*fileName arg arg ...*?  
 Description
-----------

 **Tclsh** is a shell-like application that reads Tcl commands from its standard input or from a file and evaluates them. If invoked with no arguments then it runs interactively, reading Tcl commands from standard input and printing command results and error messages to standard output. It runs until the **[exit](../tclcmd/exit.htm)** command is invoked or until it reaches end-of-file on its standard input. If there exists a file **.tclshrc** (or **tclshrc.tcl** on the Windows platforms) in the home directory of the user, interactive **tclsh** evaluates the file as a Tcl script just before reading the first command from standard input. Script files
------------

 If **tclsh** is invoked with arguments then the first few arguments specify the name of a script file, and, optionally, the encoding of the text data stored in that script file. Any additional arguments are made available to the script as variables (see below). Instead of reading commands from standard input **tclsh** will read Tcl commands from the named file; **tclsh** will exit when it reaches the end of the file. The end of the file may be marked either by the physical end of the medium, or by the character, “\032” (“\u001a”, control-Z). If this character is present in the file, the **tclsh** application will read text up to but not including the character. An application that requires this character in the file may safely encode it as “\032”, “\x1a”, or “\u001a”; or may generate it by use of commands such as **[format](../tclcmd/format.htm)** or **[binary](../tclcmd/binary.htm)**. There is no automatic evaluation of **.tclshrc** when the name of a script file is presented on the **tclsh** command line, but the script file can always **[source](../tclcmd/source.htm)** it if desired.  If you create a Tcl script in a file whose first line is 



```
**#!/usr/local/bin/tclsh**
```
  then you can invoke the script file directly from your shell if you mark the file as executable. This assumes that **tclsh** has been installed in the default location in /usr/local/bin; if it is installed somewhere else then you will have to modify the above line to match. Many UNIX systems do not allow the **#!** line to exceed about 30 characters in length, so be sure that the **tclsh** executable can be accessed with a short file name. 


 An even better approach is to start your script files with the following three lines: 



```
**#!/bin/sh
# the next line restarts using tclsh \
exec tclsh "$0" ${1+"$@"}**
```
  This approach has three advantages over the approach in the previous paragraph. First, the location of the **tclsh** binary does not have to be hard-wired into the script: it can be anywhere in your shell search path. Second, it gets around the 30-character file name limit in the previous approach. Third, this approach will work even if **tclsh** is itself a shell script (this is done on some systems in order to handle multiple architectures or operating systems: the **tclsh** script selects one of several binaries to run). The three lines cause both **sh** and **tclsh** to process the script, but the **[exec](../tclcmd/exec.htm)** is only executed by **sh**. **sh** processes the script first; it treats the second line as a comment and executes the third line. The **[exec](../tclcmd/exec.htm)** statement cause the shell to stop processing and instead to start up **tclsh** to reprocess the entire script. When **tclsh** starts up, it treats all three lines as comments, since the backslash at the end of the second line causes the third line to be treated as part of the comment on the second line. 


 You should note that it is also common practice to install tclsh with its version number as part of the name. This has the advantage of allowing multiple versions of Tcl to exist on the same system at once, but also the disadvantage of making it harder to write scripts that start up uniformly across different versions of Tcl. 


Variables
---------

 **Tclsh** sets the following global Tcl variables in addition to those created by the Tcl library itself (such as **[env](../tclcmd/tclvars.htm)**, which maps environment variables such as **PATH** into Tcl): 
 **argc**
 Contains a count of the number of *arg* arguments (0 if none), not including the name of the script file. 

**argv**
 Contains a Tcl list whose elements are the *arg* arguments, in order, or an empty string if there are no *arg* arguments. 

**argv0**
 Contains *fileName* if it was specified. Otherwise, contains the name by which **tclsh** was invoked. 

**tcl\_interactive**
 Contains 1 if **tclsh** is running interactively (no *fileName* was specified and standard input is a terminal-like device), 0 otherwise. 

 Prompts
-------

 When **tclsh** is invoked interactively it normally prompts for each command with “**%** ”. You can change the prompt by setting the global variables **tcl\_prompt1** and **tcl\_prompt2**. If variable **tcl\_prompt1** exists then it must consist of a Tcl script to output a prompt; instead of outputting a prompt **tclsh** will evaluate the script in **tcl\_prompt1**. The variable **tcl\_prompt2** is used in a similar way when a newline is typed but the current command is not yet complete; if **tcl\_prompt2** is not set then no prompt is output for incomplete commands. Standard channels
-----------------

 See **[Tcl\_StandardChannels](https://www.tcl.tk/man/tcl/TclLib/StdChannels.htm)** for more explanations. See also
--------

 **[auto\_path](../tclcmd/tclvars.htm)**, **[encoding](../tclcmd/encoding.htm)**, **[env](../tclcmd/tclvars.htm)**, **[fconfigure](../tclcmd/fconfigure.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/UserCmd/tclsh.htm>

ItclCmd
=======

 

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| [itcl](itcl.htm "Object-oriented extensions to Tcl") | [itcl::code](code.htm "Capture the namespace context for a code fragment") | [itcl::delegation](itcldelegate.htm "Delegate methods, procs or options to other objects") | [itcl::extendedclass](itclextendedclass.htm "Create a extendedclass of objects") | [itcl::local](local.htm "Create an object local to a procedure") | [itcl::widget](itclwidget.htm "Create a widget class of objects") |
| [itcl::body](body.htm "Change the body for a class method/proc") | [itcl::component](itclcomponent.htm "Define components for extendedclass, widget or widgetadaptor") | [itcl::delete](delete.htm "Delete things in the interpreter") | [itcl::find](find.htm "Search for classes and objects") | [itcl::option](itcloption.htm "Define options for extendedclass, widget or widgetadaptor") | [itclvars](itclvars.htm "Variables used by [incr Tcl]") |
| [itcl::class](class.htm "Create a class of objects") | [itcl::configbody](configbody.htm "Change the \"config\" code for a public variable") | [itcl::ensemble](ensemble.htm "Create or modify a composite command") | [itcl::is](is.htm "Test argument to see if it is a class or an object") | [itcl::scope](scope.htm "Capture the namespace context for a variable") |

 Copyright © 1993-1998 Lucent Technologies, Inc  
 Copyright © 2008 Arnulf Wiedemann 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/contents.htm>

SqliteCmd
=========

 

|  |
| --- |
| [sqlite3](sqlite3.htm "An interface to the SQLite3 database engine") |

 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/SqliteCmd/contents.htm>

TdbcCmd
=======

 

|  |  |  |
| --- | --- | --- |
| [tdbc](tdbc.htm "Tcl Database Connectivity") | [tdbc::mapSqlState](tdbc_mapsqlstate.htm "Map SQLSTATE to error class") | [tdbc::statement](tdbc_statement.htm "TDBC statement object") |
| [tdbc::connection](tdbc_connection.htm "TDBC connection object") | [tdbc::resultset](tdbc_resultset.htm "TDBC result set object") | [tdbc::tokenize](tdbc_tokenize.htm "TDBC SQL tokenizer") |

 Copyright © 2008-2009 Kevin B. Kenny 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcCmd/contents.htm>

TdbcmysqlCmd
============

 

|  |
| --- |
| [tdbc::mysql](tdbc_mysql.htm "TDBC-MYSQL bridge") |

 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcmysqlCmd/contents.htm>

TdbcodbcCmd
===========

 

|  |
| --- |
| [tdbc::odbc](tdbc_odbc.htm "TDBC-ODBC bridge") |

 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcodbcCmd/contents.htm>

TdbcpostgresCmd
===============

 

|  |
| --- |
| [tdbc::postgres](tdbc_postgres.htm "TDBC-POSTGRES bridge") |

 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcpostgresCmd/contents.htm>

TdbcsqliteCmd
=============

 

|  |
| --- |
| [tdbc::sqlite3](tdbc_sqlite3.htm "TDBC driver for the SQLite3 database manager") |

 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcsqliteCmd/contents.htm>

ThreadCmd
=========

 

|  |  |  |  |
| --- | --- | --- | --- |
| [thread](thread.htm "Extension for script access to Tcl threading") | [tpool](tpool.htm "Part of the Tcl threading extension implementing pools of worker threads	.") | [tsv](tsv.htm "Part of the Tcl threading extension allowing script level manipulation of data shared between threads	.") | [ttrace](ttrace.htm "Trace-based interpreter initialization") |

 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ThreadCmd/contents.htm>

exit
====

 Name
----

 exit — End the application Synopsis
--------

 **exit** ?*returnCode*?  
 Description
-----------

 Terminate the process, returning *returnCode* to the system as the exit status. If *returnCode* is not specified then it defaults to 0. Example
-------

 Since non-zero exit codes are usually interpreted as error cases by the calling process, the **exit** command is an important part of signaling that something fatal has gone wrong. This code fragment is useful in scripts to act as a general problem trap: 

```
proc main {} {
    # ... put the real main code in here ...
}

if {[catch {main} msg options]} {
    puts stderr "unexpected script error: $msg"
    if {[info exists env(DEBUG)]} {
        puts stderr "---- BEGIN TRACE ----"
        puts stderr [dict get $options -errorinfo]
        puts stderr "---- END TRACE ----"
    }

    # Reserve code 1 for "expected" error exits...
    **exit** 2
}
```
 See also
--------

 **[exec](exec.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/exit.htm>

local
=====

 Name
----

 itcl::local — create an object local to a procedure Synopsis
--------

 **itcl::local** *className objName* ?*arg arg ...*?  
 Description
-----------

 The **local** command creates an **[incr Tcl]** object that is local to the current call frame. When the call frame goes away, the object is automatically deleted. This command is useful for creating objects that are local to a procedure.  As a side effect, this command creates a variable named "**itcl-local-***xxx*", where *xxx* is the name of the object that is created. This variable detects when the call frame is destroyed and automatically deletes the associated object. 


Example
-------

 In the following example, a simple "counter" object is used within the procedure "test". The counter is created as a local object, so it is automatically deleted each time the procedure exits. The **[puts](../tclcmd/puts.htm)** statements included in the constructor/destructor show the object coming and going as the procedure is called. 

```
itcl::class counter {
    private variable count 0
    constructor {} {
        puts "created: $this"
    }
    destructor {
        puts "deleted: $this"
    }

    method bump {{by 1}} {
        incr count $by
    }
    method get {} {
        return $count
    }
}

proc test {val} {
    local counter x
    for {set i 0} {$i < $val} {incr i} {
        x bump
    }
    return [x get]
}

set result [test 5]
puts "test: $result"

set result [test 10]
puts "test: $result"

puts "objects: [itcl::find objects *]"
```
 Copyright © 1993-1998 Lucent Technologies, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/local.htm>

itclcomponent
=============

 Name
----

 itcl::component — define components for extendedclass, widget or widgetadaptor  Parts of this description are "borrowed" from Tcl extension [snit], as the functionality is mostly identical. 


Warning!
--------

 This is new functionality in [incr Tcl] where the API can still change!! Synopsis
--------

 **public component** *comp* ?**-inherit**?  
 **protected component** *comp* ?**-inherit**?  
 **private component** *comp* ?**-inherit**?  
 Description
-----------

 The **component** command is used inside an **[incr Tcl]** extendedclass/widget/widgetadaptor definition to define components.  Explicitly declares a component called comp, and automatically defines the component's instance variable. 


 If the *-inherit* option is specified then all unknown methods and options will be delegated to this component. The name -inherit implies that instances of this new type inherit, in a sense, the methods and options of the component. That is, -inherit yes is equivalent to: 



```
component mycomp
delegate option * to mycomp
delegate method * to mycomp
```
 Copyright © 2008 Arnulf Wiedemann 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/itclcomponent.htm>

delete
======

 Name
----

 itcl::delete — delete things in the interpreter Synopsis
--------

 **[itcl::delete](delete.htm)** *option* ?*arg arg ...*?  
 Description
-----------

 The **delete** command is used to delete things in the interpreter. It is implemented as an ensemble, so extensions can add their own options and extend the behavior of this command. By default, the **delete** command handles the destruction of namespaces.  The *option* argument determines what action is carried out by the command. The legal *options* (which may be abbreviated) are: 


 
**delete class** *name* ?*name...*?
 Deletes one or more **[incr Tcl]** classes called *name*. This deletes all objects in the class, and all derived classes as well.  If an error is encountered while destructing an object, it will prevent the destruction of the class and any remaining objects. To destroy the entire class without regard for errors, use the "**delete namespace**" command. 




**delete object** *name* ?*name...*?
 Deletes one or more **[incr Tcl]** objects called *name*. An object is deleted by invoking all destructors in its class hierarchy, in order from most- to least-specific. If all destructors are successful, data associated with the object is deleted and the *name* is removed as a command from the interpreter.  If the access command for an object resides in another namespace, then its qualified name can be used: 



```
itcl::delete object foo::bar::x
```
 If an error is encountered while destructing an object, the **delete** command is aborted and the object remains alive. To destroy an object without regard for errors, use the "**[rename](../tclcmd/rename.htm)**" command to destroy the object access command. 




**delete namespace** *name* ?*name...*?
 Deletes one or more namespaces called *name*. This deletes all commands and variables in the namespace, and deletes all child namespaces as well. When a namespace is deleted, it is automatically removed from the import lists of all other namespaces. 

 Copyright © 1993-1998 Lucent Technologies, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/delete.htm>

code
====

 Name
----

 itcl::code — capture the namespace context for a code fragment Synopsis
--------

 **itcl::code** ?**-namespace** *name*? *command* ?*arg arg ...*?  
 Description
-----------

 Creates a scoped value for the specified *command* and its associated *arg* arguments. A scoped value is a list with three elements: the "@scope" keyword, a namespace context, and a value string. For example, the command 
```
namespace foo {
    code puts "Hello World!"
}
```
 produces the scoped value: 
```
@scope ::foo {puts {Hello World!}}
```
 Note that the **code** command captures the current namespace context. If the **-namespace** flag is specified, then the current context is ignored, and the *name* string is used as the namespace context.  Extensions like Tk execute ordinary code fragments in the global namespace. A scoped value captures a code fragment together with its namespace context in a way that allows it to be executed properly later. It is needed, for example, to wrap up code fragments when a Tk widget is used within a namespace: 



```
namespace foo {
    private proc report {mesg} {
        puts "click: $mesg"
    }

    button .b1 -text "Push Me" 
        -command [code report "Hello World!"]
    pack .b1
}
```
 The code fragment associated with button .b1 only makes sense in the context of namespace "foo". Furthermore, the "report" procedure is private, and can only be accessed within that namespace. The **code** command wraps up the code fragment in a way that allows it to be executed properly when the button is pressed.  Also, note that the **code** command preserves the integrity of arguments on the command line. This makes it a natural replacement for the **[list](../tclcmd/list.htm)** command, which is often used to format Tcl code fragments. In other words, instead of using the **[list](../tclcmd/list.htm)** command like this: 



```
after 1000 [list puts "Hello $name!"]
```
 use the **code** command like this: 
```
after 1000 [code puts "Hello $name!"]
```
 This not only formats the command correctly, but also captures its namespace context.  Scoped commands can be invoked like ordinary code fragments, with or without the **[eval](../tclcmd/eval.htm)** command. For example, the following statements work properly: 



```
set cmd {@scope ::foo .b1}
$cmd configure -background red

set opts {-bg blue -fg white}
eval $cmd configure $opts
```
 Note that scoped commands by-pass the usual protection mechanisms; the command: 
```
@scope ::foo {report {Hello World!}}
```
 can be used to access the "foo::report" proc from any namespace context, even though it is private. Copyright © 1993-1998 Lucent Technologies, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/code.htm>

body
====

 Name
----

 itcl::body — change the body for a class method/proc Synopsis
--------

 **itcl::body** *className***::***function args body*  
 Description
-----------

 The **body** command is used outside of an **[incr Tcl]** class definition to define or redefine the body of a class method or proc. This facility allows a class definition to have separate "interface" and "implementation" parts. The "interface" part is a **class** command with declarations for methods, procs, instance variables and common variables. The "implementation" part is a series of **body** and **configbody** commands. If the "implementation" part is kept in a separate file, it can be sourced again and again as bugs are fixed, to support interactive development. When using the "tcl" mode in the **emacs** editor, the "interface" and "implementation" parts can be kept in the same file; as bugs are fixed, individual bodies can be highlighted and sent to the test application.  The name "*className***::***function*" identifies the method/proc being changed. 


 If an *args* list was specified when the *function* was defined in the class definition, the *args* list for the **body** command must match in meaning. Variable names can change, but the argument lists must have the same required arguments and the same default values for optional arguments. The special **args** argument acts as a wildcard when included in the *args* list in the class definition; it will match zero or more arguments of any type when the body is redefined. 


 If the *body* string starts with "**@**", it is treated as the symbolic name for a C procedure. The *args* list has little meaning for the C procedure, except to document the expected usage. (The C procedure is not guaranteed to use arguments in this manner.) If *body* does not start with "**@**", it is treated as a Tcl command script. When the function is invoked, command line arguments are matched against the *args* list, and local variables are created to represent each argument. This is the usual behavior for a Tcl-style proc. 


 Symbolic names for C procedures are established by registering procedures via **[Itcl\_RegisterC()](https://www.tcl.tk/man/tcl/ItclLib/RegisterC.htm)**. This is usually done in the **[Tcl\_AppInit()](https://www.tcl.tk/man/tcl/TclLib/AppInit.htm)** procedure, which is automatically called when the interpreter starts up. In the following example, the procedure My\_FooCmd() is registered with the symbolic name "foo". This procedure can be referenced in the **body** command as "@foo". 



```
int
[Tcl\_AppInit](https://www.tcl.tk/man/tcl/TclLib/AppInit.htm)(interp)
    [Tcl\_Interp](https://www.tcl.tk/man/tcl/TclLib/Interp.htm) *interp;     /* Interpreter for application. */
{
    if (Itcl_Init(interp) == TCL_ERROR) {
        return TCL_ERROR;
    }

    if ([Itcl\_RegisterC](https://www.tcl.tk/man/tcl/ItclLib/RegisterC.htm)(interp, "foo", My_FooCmd) != TCL_OK) {
        return TCL_ERROR;
    }
}
```
 Example
-------

 In the following example, a "File" class is defined to represent open files. The method bodies are included below the class definition via the **body** command. Note that the bodies of the constructor/destructor must be included in the class definition, but they can be redefined via the **body** command as well. 
```
itcl::class File {
    private variable fid ""
    constructor {name access} {
        set fid [open $name $access]
    }
    destructor {
        close $fid
    }

    method get {}
    method put {line}
    method eof {}
}

itcl::body File::get {} {
    return [gets $fid]
}
itcl::body File::put {line} {
    puts $fid $line
}
itcl::body File::eof {} {
    return [::eof $fid]
}

#
# See the File class in action:
#
File x /etc/passwd "r"
while {![x eof]} {
    puts "=> [x get]"
}
itcl::delete object x
```
 Copyright © 1993-1998 Lucent Technologies, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/body.htm>

itcl
====

 Name
----

 itcl — object-oriented extensions to Tcl Description
-----------

 **[incr Tcl]** provides object-oriented extensions to Tcl, much as C++ provides object-oriented extensions to C. The emphasis of this work, however, is not to create a whiz-bang object-oriented programming environment. Rather, it is to support more structured programming practices in Tcl without changing the flavor of the language. More than anything else, **[incr Tcl]** provides a means of encapsulating related procedures together with their shared data in a namespace that is hidden from the outside world. It encourages better programming by promoting the object-oriented "library" mindset. It also allows for code re-use through inheritance. Classes
-------

 The fundamental construct in **[incr Tcl]** is the class definition. Each class acts as a template for actual objects that can be created. Each object has its own unique bundle of data, which contains instances of the "variables" defined in the class. Special procedures called "methods" are used to manipulate individual objects. Methods are just like the operations that are used to manipulate Tk widgets. The "**[button](../tkcmd/button.htm)**" widget, for example, has methods such as "flash" and "invoke" that cause a particular button to blink and invoke its command.  Within the body of a method, the "variables" defined in the class are automatically available. They need not be declared with anything like the **[global](../tclcmd/global.htm)** command. Within another class method, a method can be invoked like any other command-simply by using its name. From any other context, the method name must be prefaced by an object name, which provides a context for the data that the method can access. 


 Each class has its own namespace containing things that are common to all objects which belong to the class. For example, "common" data members are shared by all objects in the class. They are global variables that exist in the class namespace, but since they are included in the class definition, they need not be declared using the **[global](../tclcmd/global.htm)** command; they are automatically available to any code executing in the class context. A class can also create ordinary global variables, but these must be declared using the **[global](../tclcmd/global.htm)** command each time they are used. 


 Classes can also have ordinary procedures declared as "procs". Within another class method or proc, a proc can be invoked like any other command-simply by using its name. From any other context, the procedure name should be qualified with the class namespace like "*className***::***proc*". Class procs execute in the class context, and therefore have automatic access to all "common" data members. However, they cannot access object-specific "variables", since they are invoked without reference to any specific object. They are usually used to perform generic operations which affect all objects belonging to the class. 


 Each of the elements in a class can be declared "public", "protected" or "private". Public elements can be accessed by the class, by derived classes (other classes that inherit this class), and by external clients that use the class. Protected elements can be accessed by the class, and by derived classes. Private elements are only accessible in the class where they are defined. 


 The "public" elements within a class define its interface to the external world. Public methods define the operations that can be used to manipulate an object. Public variables are recognized as configuration options by the "configure" and "cget" methods that are built into each class. The public interface says *what* an object will do but not *how* it will do it. Protected and private members, along with the bodies of class methods and procs, provide the implementation details. Insulating the application developer from these details leaves the class designer free to change them at any time, without warning, and without affecting programs that rely on the class. It is precisely this encapsulation that makes object-oriented programs easier to understand and maintain. 


 The fact that **[incr Tcl]** objects look like Tk widgets is no accident. **[incr Tcl]** was designed this way, to blend naturally into a Tcl/Tk application. But **[incr Tcl]** extends the Tk paradigm from being merely object-based to being fully object-oriented. An object-oriented system supports inheritance, allowing classes to share common behaviors by inheriting them from an ancestor or base class. Having a base class as a common abstraction allows a programmer to treat related classes in a similar manner. For example, a toaster and a blender perform different (specialized) functions, but both share the abstraction of being appliances. By abstracting common behaviors into a base class, code can be *shared* rather than *copied*. The resulting application is easier to understand and maintain, and derived classes (e.g., specialized appliances) can be added or removed more easily. 


 This description was merely a brief overview of object-oriented programming and **[incr Tcl]**. A more tutorial introduction is presented in the paper included with this distribution. See the **class** command for more details on creating and using classes. 


Namespaces
----------

 **[incr Tcl]** now includes a complete namespace facility. A namespace is a collection of commands and global variables that is kept apart from the usual global scope. This allows Tcl code libraries to be packaged in a well-defined manner, and prevents unwanted interactions with other libraries. A namespace can also have child namespaces within it, so one library can contain its own private copy of many other libraries. A namespace can also be used to wrap up a group of related classes. The global scope (named "::") is the root namespace for an interpreter; all other namespaces are contained within it.  See the **[namespace](../tclcmd/namespace.htm)** command for details on creating and using namespaces. 


Mega-widgets
------------

 Mega-widgets are high-level widgets that are constructed using Tk widgets as component parts, usually without any C code. A fileselectionbox, for example, may have a few listboxes, some entry widgets and some control buttons. These individual widgets are put together in a way that makes them act like one big widget.  **[incr Tk]** is a framework for building mega-widgets. It uses **[incr Tcl]** to support the object paradigm, and adds base classes which provide default widget behaviors. See the **itk** man page for more details. 


 **[incr Widgets]** is a library of mega-widgets built using **[incr Tk]**. It contains more than 30 different widget classes that can be used right out of the box to build Tcl/Tk applications. Each widget class has its own man page describing the features available. 

 Copyright © 1993-1998 Lucent Technologies, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/itcl.htm>

itcldelegate
============

  
[NAME](itcldelegate.htm#M2) itcl::delegation — delegate methods, procs or options to other objects 
[WARNING!](itcldelegate.htm#M3) 
[SYNOPSIS](itcldelegate.htm#M4) 
[DESCRIPTION](itcldelegate.htm#M5)  
[**delegate method** *methodName* **to** *componentName* ?**as** *targetName*?](itcldelegate.htm#M6) 
[**delegate method** *methodName* ?**to** *componentName*? **using** *pattern*](itcldelegate.htm#M7)  
[**%%**](itcldelegate.htm#M8) 
[**%c**](itcldelegate.htm#M9) 
[**%j**](itcldelegate.htm#M10) 
[**%m**](itcldelegate.htm#M11) 
[**%M**](itcldelegate.htm#M12) 
[**%n**](itcldelegate.htm#M13) 
[**%s**](itcldelegate.htm#M14) 
[**%t**](itcldelegate.htm#M15) 
[**%w**](itcldelegate.htm#M16) 








 
[**delegate method** *\** ?**to** *componentName*? ?**using** *pattern*? ?**except** *methodName methodName ...*?](itcldelegate.htm#M17) 
[**delegate option** *namespec* **to** *comp*](itcldelegate.htm#M18) 
[**delegate option namespec to comp as target**](itcldelegate.htm#M19) 
[**delegate option \* to** *comp*](itcldelegate.htm#M20) 
[**delegate option \* to** *comp* **except** *exceptions*](itcldelegate.htm#M21) 
[**delegate** *option* **\*** ?**except** *optionName optionName ...*?](itcldelegate.htm#M22) 







 
[KEYWORDS](itcldelegate.htm#M23) 




 Name
----

 itcl::delegation — delegate methods, procs or options to other objects  Parts of this description are "borrowed" from Tcl extension [snit], as the functionality is mostly identical. 


Warning!
--------

 This is new functionality in [incr Tcl] where the API can still change!! Synopsis
--------

 **delegate method** *methodName* **to** *componentName* ?**as** *targetName*?  
 **delegate method** *methodName* ?**to** *componentName*? **using** *pattern*  
 **delegate method** *\* ?***to** *componentName*? ?**using** *pattern*? ?**except** *methodName methodName ...*?  
   
 **delegate proc** *procName* **to** *componentName* ?**as** *targetName*?  
 **delegate proc** *procName* ?**to** *componentName*? **using** *pattern*  
 **delegate proc** *\** ?**to** *componentName*? ?**using** *pattern*? ?**except** *procName procName ...*?  
   
 **delegate option** *optionSpec* **to** *componentName*  
 **delegate option** *optionSpec* **to** *componentName* **as** *targetname*?  
 **delegate option** *\** **to** *componentName*  
 **delegate option** *\** **to** *componentName* **except** *optionName optionname ...*  
 Description
-----------

 The **delegate** command is used inside an **[incr Tcl]** extendedclass/widget/widgetadaptor definition to delegate methods/procs/options to other objects for handling. 
 
**delegate method** *methodName* **to** *componentName* ?**as** *targetName*?
 This form of delegate method delegates method methodName to component componentName. That is, when method methdoNameame is called on an instance of this type, the method and its arguments will be passed to the named component's command instead. That is, the following statement 

```
delegate method wag to tail
```
  is roughly equivalent to this explicitly defined method: 



```
method wag {args} {
    uplevel $tail wag $args
}
```
  The optional **as** clause allows you to specify the delegated method name and possibly add some arguments: 



```
delegate method wagtail to tail as "wag briskly"
```
 A method cannot be both locally defined and delegated. 




**delegate method** *methodName* ?**to** *componentName*? **using** *pattern*

 In this form of the delegate statement, the **using** clause is used to specify the precise form of the command to which method name name is delegated. The **to** clause is optional, since the chosen command might not involve any particular component.  The value of the using clause is a list that may contain any or all of the following substitution codes; these codes are substituted with the described value to build the delegated command prefix. Note that the following two statements are equivalent: 



```
delegate method wag to tail
delegate method wag to tail using "%c %m"
```
  Each element of the list becomes a single element of the delegated command --it is never reparsed as a string. 


 Substitutions: 


 **%%**
 This is replaced with a single "%". Thus, to pass the string "%c" to the command as an argument, you'd write "%%c". 

**%c**
 This is replaced with the named component's command. 

**%j**
 This is replaced by the method name; if the name consists of multiple tokens, they are joined by underscores ("\_"). 

**%m**
 This is replaced with the final token of the method name; if the method name has one token, this is identical to **%M**. 

**%M**
 This is replaced by the method name; if the name consists of multiple tokens, they are joined by space characters. 

**%n**
 This is replaced with the name of the instance's private namespace. 

**%s**
 This is replaced with the name of the instance command. 

**%t**
 This is replaced with the fully qualified type name. 

**%w**
 This is replaced with the original name of the instance command; for Itcl widgets and widget adaptors, it will be the Tk window name. It remains constant, even if the instance command is renamed. 




**delegate method** *\** ?**to** *componentName*? ?**using** *pattern*? ?**except** *methodName methodName ...*?
 In this form all unknown method names are delegeted to the specified component. The except clause can be used to specify a list of exceptions, i.e., method names that will not be so delegated. The using clause is defined as given above. In this form, the statement must contain the to clause, the using clause, or both.  In fact, the "\*" can be a list of two or more tokens whose last element is "\*", as in the following example: 



```
delegate method {tail *} to tail
```
  This implicitly defines the method tail whose subcommands will be delegated to the tail component. 


The definitions for **delegate proc** ... are the same as for method, the only difference being, that this is for procs. 




**delegate option** *namespec* **to** *comp*

**delegate option namespec to comp as target**

**delegate option \* to** *comp*


**delegate option \* to** *comp* **except** *exceptions*

 Defines a delegated option; the namespec is defined as for the option statement. When the configure, configurelist, or cget instance method is used to set or retrieve the option's value, the equivalent configure or cget command will be applied to the component as though the option was defined with the following **-configuremethod** and **-cgetmethod**: 

```
method ConfigureMethod {option value} {
    $comp configure $option $value
}

method CgetMethod {option} {
    return [$comp cget $option]
}
```
 Note that delegated options never appear in the **itcl\_options** array. If the as clause is specified, then the target option name is used in place of name. 




**delegate** *option* **\*** ?**except** *optionName optionName ...*?
 This form delegates all unknown options to the specified component. The except clause can be used to specify a list of exceptions, i.e., option names that will not be so delegated.  **Warning:** options can only be delegated to a component if it supports the **configure** and **cget** instance methods. 


An option cannot be both locally defined and delegated. TBD: Continue from here. 



 Copyright © 2008 Arnulf Wiedemann 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/itcldelegate.htm>

TkCmd
=====

 

|  |  |  |  |  |
| --- | --- | --- | --- | --- |
| [bell](bell.htm "Ring a display's bell") | [grab](grab.htm "Confine pointer and keyboard events to a window sub-tree") | [scale](scale.htm "Create and manipulate 'scale' value-controlled slider widgets") | [tk\_optionMenu](optionmenu.htm "Create an option menubutton and its menu") | [ttk::menubutton](ttk_menubutton.htm "Widget that pops down a menu when pressed") |
| [bind](bind.htm "Arrange for X events to invoke Tcl scripts") | [grid](grid.htm "Geometry manager that arranges widgets in a grid") | [scrollbar](scrollbar.htm "Create and manipulate 'scrollbar' scrolling control and indicator widgets") | [tk\_patchLevel](tkvars.htm "Variables used or set by Tk") | [ttk::notebook](ttk_notebook.htm "Multi-paned container widget") |
| [bindtags](bindtags.htm "Determine which bindings apply to a window, and order of evaluation") | [image](image.htm "Create and manipulate images") | [selection](selection.htm "Manipulate the X selection") | [tk\_popup](popup.htm "Post a popup menu") | [ttk::panedwindow](ttk_panedwindow.htm "Multi-pane container window") |
| [bitmap](bitmap.htm "Images that display two colors") | [keysyms](keysyms.htm "Keysyms recognized by Tk") | [send](send.htm "Execute a command in a different application") | [tk\_setPalette](palette.htm "Modify the Tk color palette") | [ttk::progressbar](ttk_progressbar.htm "Provide progress feedback") |
| [busy](busy.htm "Confine pointer and keyboard events to a window sub-tree") | [label](label.htm "Create and manipulate 'label' non-interactive text or image widgets") | [spinbox](spinbox.htm "Create and manipulate 'spinbox' value spinner widgets") | [tk\_strictMotif](tkvars.htm "Variables used or set by Tk") | [ttk::radiobutton](ttk_radiobutton.htm "Mutually exclusive option widget") |
| [button](button.htm "Create and manipulate 'button' action widgets") | [labelframe](labelframe.htm "Create and manipulate 'labelframe' labelled container widgets") | [text](text.htm "Create and manipulate 'text' hypertext editing widgets") | [tk\_textCopy](text.htm "Create and manipulate 'text' hypertext editing widgets") | [ttk::scale](ttk_scale.htm "Create and manipulate a scale widget") |
| [canvas](canvas.htm "Create and manipulate 'canvas' hypergraphics drawing surface widgets") | [listbox](listbox.htm "Create and manipulate 'listbox' item list widgets") | [tk](tk.htm "Manipulate Tk internal state") | [tk\_textCut](text.htm "Create and manipulate 'text' hypertext editing widgets") | [ttk::scrollbar](ttk_scrollbar.htm "Control the viewport of a scrollable widget") |
| [checkbutton](checkbutton.htm "Create and manipulate 'checkbutton' boolean selection widgets") | [lower](lower.htm "Change a window's position in the stacking order") | [tk::mac](tk_mac.htm "Access Mac-Specific Functionality on OS X from Tk") | [tk\_textPaste](text.htm "Create and manipulate 'text' hypertext editing widgets") | [ttk::separator](ttk_separator.htm "Separator bar") |
| [clipboard](clipboard.htm "Manipulate Tk clipboard") | [menu](menu.htm "Create and manipulate 'menu' widgets and menubars") | [tk\_bisque](palette.htm "Modify the Tk color palette") | [tk\_version](tkvars.htm "Variables used or set by Tk") | [ttk::sizegrip](ttk_sizegrip.htm "Bottom-right corner resize widget") |
| [colors](colors.htm "Symbolic color names recognized by Tk") | [menubutton](menubutton.htm "Create and manipulate 'menubutton' pop-up menu indicator widgets") | [tk\_chooseColor](choosecolor.htm "Pops up a dialog box for the user to select a color.") | [tkerror](tkerror.htm "Command invoked to process background errors") | [ttk::spinbox](ttk_spinbox.htm "Selecting text field widget") |
| [console](console.htm "Control the console on systems without a real console") | [message](message.htm "Create and manipulate 'message' non-interactive text widgets") | [tk\_chooseDirectory](choosedirectory.htm "Pops up a dialog box for the user to select a directory.") | [tkwait](tkwait.htm "Wait for variable to change or window to be destroyed") | [ttk::style](ttk_style.htm "Manipulate style database") |
| [cursors](cursors.htm "Mouse cursors available in Tk") | [option](option.htm "Add/retrieve window options to/from the option database") | [tk\_dialog](dialog.htm "Create modal dialog and wait for response") | [toplevel](toplevel.htm "Create and manipulate 'toplevel' main and popup window widgets") | [ttk::treeview](ttk_treeview.htm "Hierarchical multicolumn data display widget") |
| [destroy](destroy.htm "Destroy one or more windows") | [options](options.htm "Standard options supported by widgets") | [tk\_focusFollowsMouse](focusnext.htm "Utility procedures for managing the input focus.") | [ttk::button](ttk_button.htm "Widget that issues a command when pressed") | [ttk::widget](ttk_widget.htm "Standard options and commands supported by Tk themed widgets") |
| [entry](entry.htm "Create and manipulate 'entry' one-line text entry widgets") | [pack](pack.htm "Geometry manager that packs around edges of cavity") | [tk\_focusNext](focusnext.htm "Utility procedures for managing the input focus.") | [ttk::checkbutton](ttk_checkbutton.htm "On/off widget") | [ttk\_image](ttk_image.htm "Define an element based on an image") |
| [event](event.htm "Miscellaneous event facilities: define virtual events and generate events") | [panedwindow](panedwindow.htm "Create and manipulate 'panedwindow' split container widgets") | [tk\_focusPrev](focusnext.htm "Utility procedures for managing the input focus.") | [ttk::combobox](ttk_combobox.htm "Text field with popdown selection list") | [ttk\_vsapi](ttk_vsapi.htm "Define a Microsoft Visual Styles element") |
| [focus](focus.htm "Manage the input focus") | [photo](photo.htm "Full-color images") | [tk\_getOpenFile](getopenfile.htm "Pop up a dialog box for the user to select a file to open or save.") | [ttk::entry](ttk_entry.htm "Editable text field widget") | [winfo](winfo.htm "Return window-related information") |
| [font](font.htm "Create and inspect fonts.") | [place](place.htm "Geometry manager for fixed or rubber-sheet placement") | [tk\_getSaveFile](getopenfile.htm "Pop up a dialog box for the user to select a file to open or save.") | [ttk::frame](ttk_frame.htm "Simple container widget") | [wm](wm.htm "Communicate with window manager") |
| [fontchooser](fontchooser.htm "Control font selection dialog") | [radiobutton](radiobutton.htm "Create and manipulate 'radiobutton' pick-one widgets") | [tk\_library](tkvars.htm "Variables used or set by Tk") | [ttk::intro](ttk_intro.htm "Introduction to the Tk theme engine") |
| [frame](frame.htm "Create and manipulate 'frame' simple container widgets") | [raise](raise.htm "Change a window's position in the stacking order") | [tk\_menuSetFocus](menu.htm "Create and manipulate 'menu' widgets and menubars") | [ttk::label](ttk_label.htm "Display a text string and/or image") |
| [geometry](tkvars.htm "Variables used or set by Tk") | [safe::loadTk](loadtk.htm "Load Tk into a safe interpreter.") | [tk\_messageBox](messagebox.htm "Pops up a message window and waits for user response.") | [ttk::labelframe](ttk_labelframe.htm "Container widget with optional label") |

 Copyright © 1990-1994 The Regents of the University of California  
 Copyright © 1993-1998 Lucent Technologies, Inc  
 Copyright © 1994 The Australian National University  
 Copyright © 1994-1997 Sun Microsystems, Inc  
 Copyright © 1997-2000 Scriptics Corporation  
 Copyright © 1998-2000 Ajuba Solutions  
 Copyright © 2000 Jeffrey Hobbs  
 Copyright © 2001-2011 Donal K. Fellows  
 Copyright © 2003 ActiveState Corporation  
 Copyright © 2004-2006 Joe English  
 Copyright © 2006-2008 Daniel A. Steffen <das(at)users.sourceforge.net>  
 Copyright © 2008 Jos Decoster  
 Copyright © 2008 Pat Thoyts  
 Copyright © 2011 Kevin Walzer 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/contents.htm>

TclCmd
======

 

|  |  |  |  |  |
| --- | --- | --- | --- | --- |
| [after](after.htm "Execute a command after a time delay") | [errorInfo](tclvars.htm "Variables used by Tcl") | [load](load.htm "Load machine code and initialize new commands") | [re\_syntax](re_syntax.htm "Syntax of Tcl regular expressions") | [tcl\_startOfNextWord](library.htm "Standard library of Tcl procedures") |
| [append](append.htm "Append to variable") | [eval](eval.htm "Evaluate a Tcl script") | [lrange](lrange.htm "Return one or more adjacent elements from a list") | [read](read.htm "Read from a channel") | [tcl\_startOfPreviousWord](library.htm "Standard library of Tcl procedures") |
| [apply](apply.htm "Apply an anonymous function") | [exec](exec.htm "Invoke subprocesses") | [lrepeat](lrepeat.htm "Build a list by repeating elements") | [refchan](refchan.htm "Command handler API of reflected channels") | [tcl\_traceCompile](tclvars.htm "Variables used by Tcl") |
| [argc](tclvars.htm "Variables used by Tcl") | [exit](exit.htm "End the application") | [lreplace](lreplace.htm "Replace elements in a list with new elements") | [regexp](regexp.htm "Match a regular expression against a string") | [tcl\_traceExec](tclvars.htm "Variables used by Tcl") |
| [argv](tclvars.htm "Variables used by Tcl") | [expr](expr.htm "Evaluate an expression") | [lreverse](lreverse.htm "Reverse the order of a list") | [registry](registry.htm "Manipulate the Windows registry") | [tcl\_version](tclvars.htm "Variables used by Tcl") |
| [argv0](tclvars.htm "Variables used by Tcl") | [fblocked](fblocked.htm "Test whether the last input operation exhausted all available input") | [lsearch](lsearch.htm "See if a list contains a particular element") | [regsub](regsub.htm "Perform substitutions based on regular expression pattern matching") | [tcl\_wordBreakAfter](library.htm "Standard library of Tcl procedures") |
| [array](array.htm "Manipulate array variables") | [fconfigure](fconfigure.htm "Set and get options on a channel") | [lset](lset.htm "Change an element in a list") | [rename](rename.htm "Rename or delete a command") | [tcl\_wordBreakBefore](library.htm "Standard library of Tcl procedures") |
| [auto\_execok](library.htm "Standard library of Tcl procedures") | [fcopy](fcopy.htm "Copy data from one channel to another") | [lsort](lsort.htm "Sort the elements of a list") | [return](return.htm "Return from a procedure, or set return code of a script") | [tcl\_wordchars](tclvars.htm "Variables used by Tcl") |
| [auto\_import](library.htm "Standard library of Tcl procedures") | [file](file.htm "Manipulate file names and attributes") | [mathfunc](mathfunc.htm "Mathematical functions for Tcl expressions") | [safe](safe.htm "Creating and manipulating safe interpreters") | [tcltest](tcltest.htm "Test harness support code and utilities") |
| [auto\_load](library.htm "Standard library of Tcl procedures") | [fileevent](fileevent.htm "Execute a script when a channel becomes readable or writable") | [mathop](mathop.htm "Mathematical operators as Tcl commands") | [scan](scan.htm "Parse string using conversion specifiers in the style of sscanf") | [tell](tell.htm "Return current access position for an open channel") |
| [auto\_mkindex](library.htm "Standard library of Tcl procedures") | [filename](filename.htm "File name conventions supported by Tcl commands") | [memory](memory.htm "Control Tcl memory debugging capabilities") | [seek](seek.htm "Change the access position for an open channel") | [throw](throw.htm "Generate a machine-readable error") |
| [auto\_path](tclvars.htm "Variables used by Tcl") | [flush](flush.htm "Flush buffered output for a channel") | [msgcat](msgcat.htm "Tcl message catalog") | [self](self.htm "Method call internal introspection") | [time](time.htm "Time the execution of a script") |
| [auto\_qualify](library.htm "Standard library of Tcl procedures") | [for](for.htm "'For' loop") | [my](my.htm "Invoke any method of current object") | [set](set.htm "Read and write variables") | [tm](tm.htm "Facilities for locating and loading of Tcl Modules") |
| [auto\_reset](library.htm "Standard library of Tcl procedures") | [foreach](foreach.htm "Iterate over all elements in one or more lists") | [namespace](namespace.htm "Create and manipulate contexts for commands and variables") | [socket](socket.htm "Open a TCP network connection") | [trace](trace.htm "Monitor variable accesses, command usages and command executions") |
| [bgerror](bgerror.htm "Command invoked to process background errors") | [format](format.htm "Format a string in the style of sprintf") | [next](next.htm "Invoke superclass method implementations") | [source](source.htm "Evaluate a file or resource as a Tcl script") | [transchan](transchan.htm "Command handler API of channel transforms") |
| [binary](binary.htm "Insert and extract fields from binary strings") | [gets](gets.htm "Read a line from a channel") | [nextto](next.htm "Invoke superclass method implementations") | [split](split.htm "Split a string into a proper Tcl list") | [try](try.htm "Trap and process errors and exceptions") |
| [break](break.htm "Abort looping command") | [glob](glob.htm "Return names of files that match patterns") | [oo::class](class.htm "Class of all classes") | [string](string.htm "Manipulate strings") | [unknown](unknown.htm "Handle attempts to use non-existent commands") |
| [catch](catch.htm "Evaluate script and trap exceptional returns") | [global](global.htm "Access global variables") | [oo::copy](copy.htm "Create copies of objects and classes") | [subst](subst.htm "Perform backslash, command, and variable substitutions") | [unload](unload.htm "Unload machine code") |
| [cd](cd.htm "Change working directory") | [history](history.htm "Manipulate the history list") | [oo::define](define.htm "Define and configure classes and objects") | [switch](switch.htm "Evaluate one of several scripts, depending on a given value") | [unset](unset.htm "Delete variables") |
| [chan](chan.htm "Read, write and manipulate channels") | [http](http.htm "Client-side implementation of the HTTP/1.1 protocol") | [oo::objdefine](define.htm "Define and configure classes and objects") | [tailcall](tailcall.htm "Replace the current procedure with another command") | [update](update.htm "Process pending events and idle callbacks") |
| [clock](clock.htm "Obtain and manipulate dates and times") | [if](if.htm "Execute scripts conditionally") | [oo::object](object.htm "Root class of the class hierarchy") | [Tcl](tcl.htm "Tool Command Language") | [uplevel](uplevel.htm "Execute a script in a different stack frame") |
| [close](close.htm "Close an open channel") | [incr](incr.htm "Increment the value of a variable") | [open](open.htm "Open a file-based or command pipeline channel") | [tcl::prefix](prefix.htm "Facilities for prefix matching") | [upvar](upvar.htm "Create link to variable in a different stack frame") |
| [concat](concat.htm "Join lists together") | [info](info.htm "Return information about the state of the Tcl interpreter") | [package](package.htm "Facilities for package loading and version control") | [tcl\_endOfWord](library.htm "Standard library of Tcl procedures") | [variable](variable.htm "Create and initialize a namespace variable") |
| [continue](continue.htm "Skip to the next iteration of a loop") | [interp](interp.htm "Create and manipulate Tcl interpreters") | [parray](library.htm "Standard library of Tcl procedures") | [tcl\_findLibrary](library.htm "Standard library of Tcl procedures") | [vwait](vwait.htm "Process events until a variable is written") |
| [coroutine](coroutine.htm "Create and produce values from coroutines") | [join](join.htm "Create a string by joining together list elements") | [pid](pid.htm "Retrieve process identifiers") | [tcl\_interactive](tclvars.htm "Variables used by Tcl") | [while](while.htm "Execute script repeatedly as long as a condition is met") |
| [dde](dde.htm "Execute a Dynamic Data Exchange command") | [lappend](lappend.htm "Append list elements onto a variable") | [pkg::create](packagens.htm "Construct an appropriate 'package ifneeded' command for a given package specification") | [tcl\_library](tclvars.htm "Variables used by Tcl") | [yield](coroutine.htm "Create and produce values from coroutines") |
| [dict](dict.htm "Manipulate dictionaries") | [lassign](lassign.htm "Assign list elements to variables") | [pkg\_mkIndex](pkgmkindex.htm "Build an index for automatic loading of packages") | [tcl\_nonwordchars](tclvars.htm "Variables used by Tcl") | [yieldto](coroutine.htm "Create and produce values from coroutines") |
| [encoding](encoding.htm "Manipulate encodings") | [lindex](lindex.htm "Retrieve an element from a list") | [platform](platform.htm "System identification support code and utilities") | [tcl\_patchLevel](tclvars.htm "Variables used by Tcl") | [zlib](zlib.htm "Compression and decompression operations") |
| [env](tclvars.htm "Variables used by Tcl") | [linsert](linsert.htm "Insert elements into a list") | [platform::shell](platform_shell.htm "System identification support code and utilities") | [tcl\_pkgPath](tclvars.htm "Variables used by Tcl") |
| [eof](eof.htm "Check for end of file condition on channel") | [list](list.htm "Create a list") | [proc](proc.htm "Create a Tcl procedure") | [tcl\_platform](tclvars.htm "Variables used by Tcl") |
| [error](error.htm "Generate an error") | [llength](llength.htm "Count the number of elements in a list") | [puts](puts.htm "Write to a channel") | [tcl\_precision](tclvars.htm "Variables used by Tcl") |
| [errorCode](tclvars.htm "Variables used by Tcl") | [lmap](lmap.htm "Iterate over all elements in one or more lists and collect results") | [pwd](pwd.htm "Return the absolute path of the current working directory") | [tcl\_rcFileName](tclvars.htm "Variables used by Tcl") |

 Copyright © 1990-1994 The Regents of the University of California  
 Copyright © 1992-1999 Karl Lehenbauer & Mark Diekhans  
 Copyright © 1992-1999 Karl Lehenbauer and Mark Diekhans  
 Copyright © 1993-1997 Bell Labs Innovations for Lucent Technologies  
 Copyright © 1994-2000 Sun Microsystems, Inc  
 Copyright © 1998 Mark Harrison  
 Copyright © 1998-2000 Ajuba Solutions  
 Copyright © 1998-2000 Scriptics Corporation  
 Copyright © 2001-2004 ActiveState Corporation  
 Copyright © 2001-2005 Kevin B. Kenny <kennykb(at)acm.org>  
 Copyright © 2001-2012 Donal K. Fellows  
 Copyright © 2003 George Petasis <petasis(at)iit.demokritos.gr>  
 Copyright © 2003 Simon Geard  
 Copyright © 2004-2010 Andreas Kupries <andreas\_kupries(at)users.sourceforge.net>  
 Copyright © 2006 Miguel Sofer  
 Copyright © 2006-2008 ActiveState Software Inc  
 Copyright © 2006-2008 Joe Mistachkin  
 Copyright © 2008 Pat Thoyts  
 Copyright © 2008 Peter Spjuth <pspjuth(at)users.sourceforge.net>  
 Copyright © 2012 Trevor Davel 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/contents.htm>

wish
====

  
[NAME](wish.htm#M2) wish — Simple windowing shell 
[SYNOPSIS](wish.htm#M3) 
[OPTIONS](wish.htm#M4)  
[**-encoding** *name*](wish.htm#M5) 
[**-colormap** *new*](wish.htm#M6) 
[**-display** *display*](wish.htm#M7) 
[**-geometry** *geometry*](wish.htm#M8) 
[**-name** *name*](wish.htm#M9) 
[**-sync**](wish.htm#M10) 
[**-use** *id*](wish.htm#M11) 
[**-visual** *visual*](wish.htm#M12) 
[**--**](wish.htm#M13) 








 
[DESCRIPTION](wish.htm#M14) 
[OPTION PROCESSING](wish.htm#M15) 
[APPLICATION NAME AND CLASS](wish.htm#M16) 
[VARIABLES](wish.htm#M17)  
[**argc**](wish.htm#M18) 
[**argv**](wish.htm#M19) 
[**argv0**](wish.htm#M20) 
[**geometry**](wish.htm#M21) 
[**tcl\_interactive**](wish.htm#M22) 




 
[SCRIPT FILES](wish.htm#M23) 
[PROMPTS](wish.htm#M24) 
[SEE ALSO](wish.htm#M25) 
[KEYWORDS](wish.htm#M26) 










 Name
----

 wish — Simple windowing shell Synopsis
--------

 **wish** ?**-encoding** *name*? ?*fileName arg arg ...*?  
 Options
-------

  
**-encoding** *name*

 Specifies the encoding of the text stored in *fileName*. This option is only recognized prior to the *fileName* argument. 


**-colormap** *new*

 Specifies that the window should have a new private colormap instead of using the default colormap for the screen. 


**-display** *display*

 Display (and screen) on which to display window. 


**-geometry** *geometry*

 Initial geometry to use for window. If this option is specified, its value is stored in the **[geometry](../tkcmd/tkvars.htm)** global variable of the application's Tcl interpreter. 


**-name** *name*

 Use *name* as the title to be displayed in the window, and as the name of the interpreter for **[send](../tkcmd/send.htm)** commands. 

**-sync**
 Execute all X server commands synchronously, so that errors are reported immediately. This will result in much slower execution, but it is useful for debugging. 


**-use** *id*

 Specifies that the main window for the application is to be embedded in the window whose identifier is *id*, instead of being created as an independent toplevel window. *Id* must be specified in the same way as the value for the **-use** option for toplevel widgets (i.e. it has a form like that returned by the **[winfo id](../tkcmd/winfo.htm)** command).  Note that on some platforms this will only work correctly if *id* refers to a Tk **[frame](../tkcmd/frame.htm)** or **[toplevel](../tkcmd/toplevel.htm)** that has its **-container** option enabled. 


**-visual** *visual*

 Specifies the visual to use for the window. *Visual* may have any of the forms supported by the **[Tk\_GetVisual](https://www.tcl.tk/man/tcl/TkLib/GetVisual.htm)** procedure. 

**--**
 Pass all remaining arguments through to the script's **[argv](../tclcmd/tclvars.htm)** variable without interpreting them. This provides a mechanism for passing arguments such as **-name** to a script instead of having **wish** interpret them. 

 Description
-----------

 **Wish** is a simple program consisting of the Tcl command language, the Tk toolkit, and a main program that reads commands from standard input or from a file. It creates a main window and then processes Tcl commands. If **wish** is invoked with arguments, then the first few arguments, ?**-encoding** *name*? ?*fileName*?, specify the name of a script file, and, optionally, the encoding of the text data stored in that script file. A value for *fileName* is recognized if the appropriate argument does not start with “-”.  If there are no arguments, or the arguments do not specify a *fileName*, then wish reads Tcl commands interactively from standard input. It will continue processing commands until all windows have been deleted or until end-of-file is reached on standard input. If there exists a file “**.wishrc**” in the home directory of the user, **wish** evaluates the file as a Tcl script just before reading the first command from standard input. 


 If arguments to **wish** do specify a *fileName*, then *fileName* is treated as the name of a script file. **Wish** will evaluate the script in *fileName* (which presumably creates a user interface), then it will respond to events until all windows have been deleted. Commands will not be read from standard input. There is no automatic evaluation of “**.wishrc**” when the name of a script file is presented on the **wish** command line, but the script file can always **[source](../tclcmd/source.htm)** it if desired. 


 Note that on Windows, the **wish***version***.exe** program varies from the **[tclsh](tclsh.htm)***version***.exe** program in an additional important way: it does not connect to a standard Windows console and is instead a windowed program. Because of this, it additionally provides access to its own **[console](../tkcmd/console.htm)** command. 


Option processing
-----------------

 **Wish** automatically processes all of the command-line options described in the **[OPTIONS](#M4)** summary above. Any other command-line arguments besides these are passed through to the application using the **[argc](../tclcmd/tclvars.htm)** and **[argv](../tclcmd/tclvars.htm)** variables described later. Application name and class
--------------------------

 The name of the application, which is used for purposes such as **[send](../tkcmd/send.htm)** commands, is taken from the **-name** option, if it is specified; otherwise it is taken from *fileName*, if it is specified, or from the command name by which **wish** was invoked. In the last two cases, if the name contains a “/” character, then only the characters after the last slash are used as the application name.  The class of the application, which is used for purposes such as specifying options with a **RESOURCE\_MANAGER** property or .Xdefaults file, is the same as its name except that the first letter is capitalized. 


Variables
---------

 **Wish** sets the following Tcl variables: 
 **argc**
 Contains a count of the number of *arg* arguments (0 if none), not including the options described above. 

**argv**
 Contains a Tcl list whose elements are the *arg* arguments that follow a **--** option or do not match any of the options described in **[OPTIONS](#M4)** above, in order, or an empty string if there are no such arguments. 

**argv0**
 Contains *fileName* if it was specified. Otherwise, contains the name by which **wish** was invoked. 

**geometry**
 If the **-geometry** option is specified, **wish** copies its value into this variable. If the variable still exists after *fileName* has been evaluated, **wish** uses the value of the variable in a **[wm geometry](../tkcmd/wm.htm)** command to set the main window's geometry. 

**tcl\_interactive**
 Contains 1 if **wish** is reading commands interactively (*fileName* was not specified and standard input is a terminal-like device), 0 otherwise. 

 Script files
------------

 If you create a Tcl script in a file whose first line is 
```
**#!/usr/local/bin/wish**
```
 then you can invoke the script file directly from your shell if you mark it as executable. This assumes that **wish** has been installed in the default location in /usr/local/bin; if it is installed somewhere else then you will have to modify the above line to match. Many UNIX systems do not allow the **#!** line to exceed about 30 characters in length, so be sure that the **wish** executable can be accessed with a short file name.  An even better approach is to start your script files with the following three lines: 



```
**#!/bin/sh
# the next line restarts using wish \
exec wish "$0" ${1+"$@"}**
```
 This approach has three advantages over the approach in the previous paragraph. First, the location of the **wish** binary does not have to be hard-wired into the script: it can be anywhere in your shell search path. Second, it gets around the 30-character file name limit in the previous approach. Third, this approach will work even if **wish** is itself a shell script (this is done on some systems in order to handle multiple architectures or operating systems: the **wish** script selects one of several binaries to run). The three lines cause both **sh** and **wish** to process the script, but the **[exec](../tclcmd/exec.htm)** is only executed by **sh**. **sh** processes the script first; it treats the second line as a comment and executes the third line. The **[exec](../tclcmd/exec.htm)** statement cause the shell to stop processing and instead to start up **wish** to reprocess the entire script. When **wish** starts up, it treats all three lines as comments, since the backslash at the end of the second line causes the third line to be treated as part of the comment on the second line.  The end of a script file may be marked either by the physical end of the medium, or by the character, “\032” (“\u001a”, control-Z). If this character is present in the file, the **wish** application will read text up to but not including the character. An application that requires this character in the file may encode it as “\032”, “\x1a”, or “\u001a”; or may generate it by use of commands such as **[format](../tclcmd/format.htm)** or **[binary](../tclcmd/binary.htm)**. 


Prompts
-------

 When **wish** is invoked interactively it normally prompts for each command with “**%** ”. You can change the prompt by setting the variables **tcl\_prompt1** and **tcl\_prompt2**. If variable **tcl\_prompt1** exists then it must consist of a Tcl script to output a prompt; instead of outputting a prompt **wish** will evaluate the script in **tcl\_prompt1**. The variable **tcl\_prompt2** is used in a similar way when a newline is typed but the current command is not yet complete; if **tcl\_prompt2** is not set then no prompt is output for incomplete commands. See also
--------

 **[tclsh](tclsh.htm)**, **[toplevel](../tkcmd/toplevel.htm)**, **[Tk\_Main](https://www.tcl.tk/man/tcl/TkLib/Tk_Main.htm)**, **[Tk\_MainLoop](https://www.tcl.tk/man/tcl/TkLib/MainLoop.htm)**, **[Tk\_MainWindow](https://www.tcl.tk/man/tcl/TkLib/MainWin.htm)** Copyright © 1991-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/UserCmd/wish.htm>

source
======

 Name
----

 source — Evaluate a file or resource as a Tcl script Synopsis
--------

 **source** *fileName*  
 **source** **-encoding** *encodingName fileName*  
 Description
-----------

 This command takes the contents of the specified file or resource and passes it to the Tcl interpreter as a text script. The return value from **source** is the return value of the last command executed in the script. If an error occurs in evaluating the contents of the script then the **source** command will return that error. If a **[return](return.htm)** command is invoked from within the script then the remainder of the file will be skipped and the **source** command will return normally with the result from the **[return](return.htm)** command.  The end-of-file character for files is “\32” (^Z) for all platforms. The source command will read files up to this character. This restriction does not exist for the **[read](read.htm)** or **[gets](gets.htm)** commands, allowing for files containing code and data segments (scripted documents). If you require a “^Z” in code for string comparison, you can use “\032” or “\u001a”, which will be safely substituted by the Tcl interpreter into “^Z”. 


 A leading BOM (Byte order mark) contained in the file is ignored for unicode encodings (utf-8, unicode). 


 The **-encoding** option is used to specify the encoding of the data stored in *fileName*. When the **-encoding** option is omitted, the system encoding is assumed. 


Example
-------

 Run the script in the file **foo.tcl** and then the script in the file **bar.tcl**: 

```
**source** foo.tcl
**source** bar.tcl
```
  Alternatively: 



```
foreach scriptFile {foo.tcl bar.tcl} {
    **source** $scriptFile
}
```
 See also
--------

 **[file](file.htm)**, **[cd](cd.htm)**, **[encoding](encoding.htm)**, **[info](info.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2000 Scriptics Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/source.htm>

scope
=====

 Name
----

 itcl::scope — capture the namespace context for a variable Synopsis
--------

 **itcl::scope** *name*  
 Description
-----------

 Creates a scoped value for the specified *name*, which must be a variable name. If the *name* is an instance variable, then the scope command returns a name which will resolve in any context as an instance variable belonging to *object*. The precise format of this name is an internal detail to Itcl. Use of such a scoped value makes it possible to use instance variables in conjunction with widgets. For example, if you have an object with a private variable x, and you can use x in conjunction with the -textvariable option of an entry widget. Before itcl3.0, only common variables could be used in this manner.  If the *name* is not an instance variable, then it must be a common variable or a global variable. In that case, the scope command returns the fully qualified name of the variable, e.g., ::foo::bar::x. 


 If the *name* is not recognized as a variable, the scope command returns an error. 


 Ordinary variable names refer to variables in the global namespace. A scoped value captures a variable name together with its namespace context in a way that allows it to be referenced properly later. It is needed, for example, to wrap up variable names when a Tk widget is used within a namespace: 



```
namespace foo {
    private variable mode 1

    radiobutton .rb1 -text "Mode #1" 
        -variable [scope mode] -value 1
    pack .rb1

    radiobutton .rb2 -text "Mode #2" 
        -variable [scope mode] -value 2
    pack .rb2
}
```
 Radiobuttons .rb1 and .rb2 interact via the variable "mode" contained in the namespace "foo". The **scope** command guarantees this by returning the fully qualified variable name ::foo::mode.  You should never use the @itcl syntax directly. For example, it is a bad idea to write code like this: 



```
set {@itcl ::fred x} 3
puts "value = ${@itcl ::fred x}"
```
 Instead, you should always use the scope command to generate the variable name dynamically. Then, you can pass that name to a widget or to any other bit of code in your program. Copyright © 1993-1998 Lucent Technologies, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/scope.htm>

itclvars
========

 Name
----

 itclvars — variables used by [incr Tcl] Description
-----------

 The following global variables are created and managed automatically by the **[incr Tcl]** library. Except where noted below, these variables should normally be treated as read-only by application-specific code and by users. 
 **itcl::library**
 When an interpreter is created, **[incr Tcl]** initializes this variable to hold the name of a directory containing the system library of **[incr Tcl]** scripts. The initial value of **itcl::library** is set from the ITCL\_LIBRARY environment variable if it exists, or from a compiled-in value otherwise. 

**itcl::patchLevel**
 When an interpreter is created, **[incr Tcl]** initializes this variable to hold the current patch level for **[incr Tcl]**. For example, the value "**2.0p1**" indicates **[incr Tcl]** version 2.0 with the first set of patches applied. 

**itcl::purist**
 When an interpreter is created containing Tcl/Tk and the **[incr Tcl]** namespace facility, this variable controls a "backward-compatibility" mode for widget access.  In vanilla Tcl/Tk, there is a single pool of commands, so the access command for a widget is the same as the window name. When a widget is created within a namespace, however, its access command is installed in that namespace, and should be accessed outside of the namespace using a qualified name. For example, 



```
namespace foo {
    namespace bar {
        button .b -text "Testing"
    }
}
foo::bar::.b configure -background red
pack .b
```
  Note that the window name ".b" is still used in conjunction with commands like **[pack](../tkcmd/pack.htm)** and **[destroy](../tkcmd/destroy.htm)**. However, the access command for the widget (i.e., name that appears as the *first* argument on a command line) must be more specific. 


 The "**[winfo command](../tkcmd/winfo.htm)**" command can be used to query the fully-qualified access command for any widget, so one can write: 



```
[winfo command .b] configure -background red
```
  and this is good practice when writing library procedures. Also, in conjunction with the **[bind](../tkcmd/bind.htm)** command, the "%q" field can be used in place of "%W" as the access command: 



```
bind Button <Key-Return> {%q flash; %q invoke}
```
  While this behavior makes sense from the standpoint of encapsulation, it causes problems with existing Tcl/Tk applications. Many existing applications are written with bindings that use "%W". Many library procedures assume that the window name is the access command. 


The **itcl::purist** variable controls a backward-compatibility mode. By default, this variable is "0", and the window name can be used as an access command in any context. Whenever the **[unknown](../tclcmd/unknown.htm)** procedure stumbles across a widget name, it simply uses "**[winfo command](../tkcmd/winfo.htm)**" to determine the appropriate command name. If this variable is set to "1", this backward-compatibility mode is disabled. This gives better encapsulation, but using the window name as the access command may lead to "invalid command" errors. 



**itcl::version**
 When an interpreter is created, **[incr Tcl]** initializes this variable to hold the version number of the form *x.y*. Changes to *x* represent major changes with probable incompatibilities and changes to *y* represent small enhancements and bug fixes that retain backward compatibility. 

 Copyright © 1993-1998 Lucent Technologies, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/itclvars.htm>

configbody
==========

 Name
----

 itcl::configbody — change the "config" code for a public variable Synopsis
--------

 **itcl::configbody** *className***::***varName body*  
 Description
-----------

 The **configbody** command is used outside of an **[incr Tcl]** class definition to define or redefine the configuration code associated with a public variable. Public variables act like configuration options for an object. They can be modified outside the class scope using the built-in **configure** method. Each variable can have a bit of "config" code associate with it that is automatically executed when the variable is configured. The **configbody** command can be used to define or redefine this body of code.  Like the **body** command, this facility allows a class definition to have separate "interface" and "implementation" parts. The "interface" part is a **class** command with declarations for methods, procs, instance variables and common variables. The "implementation" part is a series of **body** and **configbody** commands. If the "implementation" part is kept in a separate file, it can be sourced again and again as bugs are fixed, to support interactive development. When using the "tcl" mode in the **emacs** editor, the "interface" and "implementation" parts can be kept in the same file; as bugs are fixed, individual bodies can be highlighted and sent to the test application. 


 The name "*className***::***varName*" identifies the public variable being updated. If the *body* string starts with "**@**", it is treated as the symbolic name for a C procedure. Otherwise, it is treated as a Tcl command script. 


 Symbolic names for C procedures are established by registering procedures via **[Itcl\_RegisterC()](https://www.tcl.tk/man/tcl/ItclLib/RegisterC.htm)**. This is usually done in the **[Tcl\_AppInit()](https://www.tcl.tk/man/tcl/TclLib/AppInit.htm)** procedure, which is automatically called when the interpreter starts up. In the following example, the procedure My\_FooCmd() is registered with the symbolic name "foo". This procedure can be referenced in the **configbody** command as "@foo". 



```
int
[Tcl\_AppInit](https://www.tcl.tk/man/tcl/TclLib/AppInit.htm)(interp)
    [Tcl\_Interp](https://www.tcl.tk/man/tcl/TclLib/Interp.htm) *interp;     /* Interpreter for application. */
{
    if (Itcl_Init(interp) == TCL_ERROR) {
        return TCL_ERROR;
    }

    if ([Itcl\_RegisterC](https://www.tcl.tk/man/tcl/ItclLib/RegisterC.htm)(interp, "foo", My_FooCmd) != TCL_OK) {
        return TCL_ERROR;
    }
}
```
 Example
-------

 In the following example, a "File" class is defined to represent open files. Whenever the "-name" option is configured, the existing file is closed, and a new file is opened. Note that the "config" code for a public variable is optional. The "-access" option, for example, does not have it. 
```
itcl::class File {
    private variable fid ""

    public variable name ""
    public variable access "r"

    constructor {args} {
        eval configure $args
    }
    destructor {
        if {$fid != ""} {
            close $fid
        }
    }

    method get {}
    method put {line}
    method eof {}
}

itcl::body File::get {} {
    return [gets $fid]
}
itcl::body File::put {line} {
    puts $fid $line
}
itcl::body File::eof {} {
    return [::eof $fid]
}

itcl::configbody File::name {
    if {$fid != ""} {
        close $fid
    }
    set fid [open $name $access]
}

#
# See the File class in action:
#
File x

x configure -name /etc/passwd
while {![x eof]} {
    puts "=> [x get]"
}
itcl::delete object x
```
 Copyright © 1993-1998 Lucent Technologies, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/configbody.htm>

ensemble
========

 Name
----

 itcl::ensemble — create or modify a composite command Synopsis
--------

 **itcl::ensemble** *ensName* ?*command arg arg...*?  
 or  
 **ensemble** *ensName* {  
 **part** *partName args body*  
 *...*  
 **ensemble** *partName* {  
 **part** *subPartName args body*  
 **part** *subPartName args body*  
 *...*  
 }  
 }  
 Description
-----------

 The **ensemble** command is used to create or modify a composite command. See the section **[WHAT IS AN ENSEMBLE?](#M5)** below for a brief overview of ensembles.  If the **ensemble** command finds an existing ensemble called *ensName*, it updates that ensemble. Otherwise, it creates an ensemble called *ensName*. If the *ensName* is a simple name like "foo", then an ensemble command named "foo" is added to the current namespace context. If a command named "foo" already exists in that context, then it is deleted. If the *ensName* contains namespace qualifiers like "a::b::foo", then the namespace path is resolved, and the ensemble command is added that namespace context. Parent namespaces like "a" and "b" are created automatically, as needed. 


 If the *ensName* contains spaces like "a::b::foo bar baz", then additional words like "bar" and "baz" are treated as sub-ensembles. Sub-ensembles are merely parts within an ensemble; they do not have a Tcl command associated with them. An ensemble like "foo" can have a sub-ensemble called "foo bar", which in turn can have a sub-ensemble called "foo bar baz". In this case, the sub-ensemble "foo bar" must be created before the sub-ensemble "foo bar baz" that resides within it. 


 If there are any arguments following *ensName*, then they are treated as commands, and they are executed to update the ensemble. The following commands are recognized in this context: **part** and **ensemble**. 


 The **part** command defines a new part for the ensemble. Its syntax is identical to the usual **[proc](../tclcmd/proc.htm)** command, but it defines a part within an ensemble, instead of a Tcl command. If a part called *partName* already exists within the ensemble, then the **part** command returns an error. 


 The **ensemble** command can be nested inside another **ensemble** command to define a sub-ensemble. 


What is an ensemble?
--------------------

 The usual "info" command is a composite command--the command name **[info](../tclcmd/info.htm)** must be followed by a sub-command like **body** or **globals**. We will refer to a command like **[info](../tclcmd/info.htm)** as an *ensemble*, and to sub-commands like **body** or **globals** as its *parts*.  Ensembles can be nested. For example, the **[info](../tclcmd/info.htm)** command has an ensemble **[info namespace](../tclcmd/info.htm)** within it. This ensemble has parts like **info namespace all** and **info namespace children**. 


 With ensembles, composite commands can be created and extended in an automatic way. Any package can find an existing ensemble and add new parts to it. So extension writers can add their own parts, for example, to the **[info](../tclcmd/info.htm)** command. 


 The ensemble facility manages all of the part names and keeps track of unique abbreviations. Normally, you can abbreviate **[info complete](../tclcmd/info.htm)** to **[info comp](../tclcmd/info.htm)**. But if an extension adds the part **[info complexity](../tclcmd/info.htm)**, the minimum abbreviation for **[info complete](../tclcmd/info.htm)** becomes **[info complet](../tclcmd/info.htm)**. 


 The ensemble facility not only automates the construction of composite commands, but it automates the error handling as well. If you invoke an ensemble command without specifying a part name, you get an automatically generated error message that summarizes the usage information. For example, when the **[info](../tclcmd/info.htm)** command is invoked without any arguments, it produces the following error message: 



```
wrong # args: should be one of...
  info args procname
  info body procname
  info cmdcount
  info commands ?pattern?
  info complete command
  info context
  info default procname arg varname
  info exists varName
  info globals ?pattern?
  info level ?number?
  info library
  info locals ?pattern?
  info namespace option ?arg arg ...?
  info patchlevel
  info procs ?pattern?
  info protection ?-command? ?-variable? name
  info script
  info tclversion
  info vars ?pattern?
  info which ?-command? ?-variable? ?-namespace? name
```
  You can also customize the way an ensemble responds to errors. When an ensemble encounters an unspecified or ambiguous part name, it looks for a part called **@error**. If it exists, then it is used to handle the error. This part will receive all of the arguments on the command line starting with the offending part name. It can find another way of resolving the command, or generate its own error message. 


Example
-------

 We could use an ensemble to clean up the syntax of the various "wait" commands in Tcl/Tk. Instead of using a series of strange commands like this: 

```
vwait x
tkwait visibility .top
tkwait window .
```
  we could use commands with a uniform syntax, like this: 



```
wait variable x
wait visibility .top
wait window .
```
  The Tcl package could define the following ensemble: 



```
itcl::ensemble wait part variable {name} {
    uplevel vwait $name
}
```
  The Tk package could add some options to this ensemble, with a command like this: 



```
itcl::ensemble wait {
    part visibility {name} {
        tkwait visibility $name
    }
    part window {name} {
        tkwait window $name
    }
}
```
  Other extensions could add their own parts to the **wait** command too. 

 Copyright © 1993-1998 Lucent Technologies, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/ensemble.htm>

is
==

 Name
----

 itcl::is — test argument to see if it is a class or an object Synopsis
--------

 **[itcl::is](is.htm)** *option* ?*arg arg ...*?  
 Description
-----------

 The **is** command is used to check if the argument given is a class or an object; depending on the option given. If the argument if a class or object, then 1 is returned. Otherwise, 0 is returned. The **is** command also recognizes the commands wrapped in the itcl **code** command.  The *option* argument determines what action is carried out by the command. The legal *options* (which may be abbreviated) are: 


 
**is class** *command*

 Returns 1 if command is a class, and returns 0 otherwise.  The fully qualified name of the class needs to be given as the *command* argument. So, if a class resides in a namespace, then the namespace needs to be specified as well. So, if a class **C** resides in a namespace **N**, then the command should be called like: 



```
**is N::C**
    or
**is ::N::C**
```



**is** object ?**-class** *className*? *command*

 Returns 1 if *command* is an object, and returns 0 otherwise.  If the optional "**-class**" parameter is specified, then the *command* will be checked within the context of the class given. Note that *className* has to exist. If not, then an error will be given. So, if *className* is uncertain to be a class, then the programmer will need to check it's existance beforehand, or wrap it in a catch statement. 


 So, if **c** is an object in the class **C**, in namespace N then these are the possibilities (all return 1): 



```
set obj [N::C c]
itcl::is object N::c
itcl::is object c
itcl::is object $obj
itcl::is object [itcl::code c]
```


 Copyright © 1993-1998 Lucent Technologies, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/is.htm>

sqlite3
=======

 Name
----

 sqlite3 — an interface to the SQLite3 database engine Synopsis
--------

 **sqlite3** *command\_name ?filename?*  
 Description
-----------

 SQLite3 is a self-contains, zero-configuration, transactional SQL database engine. This extension provides an easy to use interface for accessing SQLite database files from Tcl.  For full documentation see *<http://www.sqlite.org/>* and in particular *<http://www.sqlite.org/tclsqlite.html>*. 




 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/SqliteCmd/sqlite3.htm>

encoding
========

  
[NAME](encoding.htm#M2) encoding — Manipulate encodings 
[SYNOPSIS](encoding.htm#M3) 
[INTRODUCTION](encoding.htm#M4) 
[DESCRIPTION](encoding.htm#M5)  
[**encoding convertfrom** ?*encoding*? *data*](encoding.htm#M6) 
[**encoding convertto** ?*encoding*? *string*](encoding.htm#M7) 
[**encoding dirs** ?*directoryList*?](encoding.htm#M8) 
[**encoding names**](encoding.htm#M9) 
[**encoding system** ?*encoding*?](encoding.htm#M10) 




 
[EXAMPLE](encoding.htm#M11) 
[SEE ALSO](encoding.htm#M12) 
[KEYWORDS](encoding.htm#M13) 






 Name
----

 encoding — Manipulate encodings Synopsis
--------

 **encoding** *option* ?*arg arg ...*?  
 Introduction
------------

 Strings in Tcl are logically a sequence of 16-bit Unicode characters. These strings are represented in memory as a sequence of bytes that may be in one of several encodings: modified UTF-8 (which uses 1 to 3 bytes per character), 16-bit “Unicode” (which uses 2 bytes per character, with an endianness that is dependent on the host architecture), and binary (which uses a single byte per character but only handles a restricted range of characters). Tcl does not guarantee to always use the same encoding for the same string.  Different operating system interfaces or applications may generate strings in other encodings such as Shift-JIS. The **encoding** command helps to bridge the gap between Unicode and these other formats. 


Description
-----------

 Performs one of several encoding related operations, depending on *option*. The legal *option*s are: 
 
**encoding convertfrom** ?*encoding*? *data*

 Convert *data* to Unicode from the specified *encoding*. The characters in *data* are treated as binary data where the lower 8-bits of each character is taken as a single byte. The resulting sequence of bytes is treated as a string in the specified *encoding*. If *encoding* is not specified, the current system encoding is used. 


**encoding convertto** ?*encoding*? *string*

 Convert *string* from Unicode to the specified *encoding*. The result is a sequence of bytes that represents the converted string. Each byte is stored in the lower 8-bits of a Unicode character (indeed, the resulting string is a binary string as far as Tcl is concerned, at least initially). If *encoding* is not specified, the current system encoding is used. 


**encoding dirs** ?*directoryList*?
 Tcl can load encoding data files from the file system that describe additional encodings for it to work with. This command sets the search path for **\*.enc** encoding data files to the list of directories *directoryList*. If *directoryList* is omitted then the command returns the current list of directories that make up the search path. It is an error for *directoryList* to not be a valid list. If, when a search for an encoding data file is happening, an element in *directoryList* does not refer to a readable, searchable directory, that element is ignored. 

**encoding names**
 Returns a list containing the names of all of the encodings that are currently available. The encodings “utf-8” and “iso8859-1” are guaranteed to be present in the list. 


**encoding system** ?*encoding*?
 Set the system encoding to *encoding*. If *encoding* is omitted then the command returns the current system encoding. The system encoding is used whenever Tcl passes strings to system calls. 

 Example
-------

 It is common practice to write script files using a text editor that produces output in the euc-jp encoding, which represents the ASCII characters as singe bytes and Japanese characters as two bytes. This makes it easy to embed literal strings that correspond to non-ASCII characters by simply typing the strings in place in the script. However, because the **[source](source.htm)** command always reads files using the current system encoding, Tcl will only source such files correctly when the encoding used to write the file is the same. This tends not to be true in an internationalized setting. For example, if such a file was sourced in North America (where the ISO8859-1 is normally used), each byte in the file would be treated as a separate character that maps to the 00 page in Unicode. The resulting Tcl strings will not contain the expected Japanese characters. Instead, they will contain a sequence of Latin-1 characters that correspond to the bytes of the original string. The **encoding** command can be used to convert this string to the expected Japanese Unicode characters. For example, 

```
set s [**encoding convertfrom** euc-jp "\xA4\xCF"]
```
  would return the Unicode string “\u306F”, which is the Hiragana letter HA. 


See also
--------

 **[Tcl\_GetEncoding](https://www.tcl.tk/man/tcl/TclLib/Encoding.htm)** Copyright © 1998 by Scriptics Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/encoding.htm>

itcloption
==========

  
[NAME](itcloption.htm#M2) itcl::option — define options for extendedclass, widget or widgetadaptor 
[WARNING!](itcloption.htm#M3) 
[SYNOPSIS](itcloption.htm#M4) 
[DESCRIPTION](itcloption.htm#M5)  
[**-default** *defvalue*](itcloption.htm#M6) 
[**-readonly**](itcloption.htm#M7) 
[**-cgetmethod** *methodName*](itcloption.htm#M8) 
[**-cgetmethodvar** *varName*](itcloption.htm#M9) 
[**-configuremethod** *methodName*](itcloption.htm#M10) 
[**-configuremethodvar** *varName*](itcloption.htm#M11) 
[**-validatemethod** *methodName*](itcloption.htm#M12) 
[**-validatemethodvar** *varName*](itcloption.htm#M13) 







 
[KEYWORDS](itcloption.htm#M14) 




 Name
----

 itcl::option — define options for extendedclass, widget or widgetadaptor  Parts of this description are "borrowed" from Tcl extension [snit], as the functionality is mostly identical. 


Warning!
--------

 This is new functionality in [incr Tcl] where the API can still change!! Synopsis
--------

 **[option](../tkcmd/option.htm)** *optionSpec* ?*defaultValue*?  
 **[option](../tkcmd/option.htm)** *optionSpec* ?*options*?  
 Description
-----------

 The **[option](../tkcmd/option.htm)** command is used inside an **[incr Tcl]** extendedclass/widget/widgetadaptor definition to define options.  In the first form defines an option for instances of this type, and optionally gives it an initial value. The initial value defaults to the empty string if no defaultValue is specified. 


 An option defined in this way is said to be locally defined. The optionSpec is a list defining the option's name, resource name, and class name, e.g.: 



```
option {-font font Font} {Courier 12}
```
  The option name must begin with a hyphen, and must not contain any upper case letters. The resource name and class name are optional; if not specified, the resource name defaults to the option name, minus the hyphen, and the class name defaults to the resource name with the first letter capitalized. Thus, the following statement is equivalent to the previous example: 



```
option -font {Courier 12}
```
  See The Tk Option Database for more information about resource and class names. 


 Options are normally set and retrieved using the standard instance methods configure and cget; within instance code (method bodies, etc.), option values are available through the options array: 



```
set myfont $itcl_options(-font)
```
  In the second form you can define option handlers (e.g., -configuremethod), then it should probably use configure and cget to access its options to avoid subtle errors. 


 The option statement may include the following options: 


 
**-default** *defvalue*

 Defines the option's default value; the option's default value will be "" otherwise. 

**-readonly**
 The option is handled read-only -- it can only be set using configure at creation time, i.e., in the type's constructor. 


**-cgetmethod** *methodName*

 Every locally-defined option may define a -cgetmethod; it is called when the option's value is retrieved using the cget method. Whatever the method's body returns will be the return value of the call to cget.  The named method must take one argument, the option name. For example, this code is equivalent to (though slower than) Itcl's default handling of cget: 



```
option -font -cgetmethod GetOption
        method GetOption {option} {
            return $itcl_options($option)
        }
```
 Note that it's possible for any number of options to share a -cgetmethod. 




**-cgetmethodvar** *varName*

 That is very similar to -cgetmethod, the only difference is, one can define a variable, where to find the cgetmethod during runtime. 


**-configuremethod** *methodName*

 Every locally-defined option may define a -configuremethod; it is called when the option's value is set using the configure or configurelist methods. It is the named method's responsibility to save the option's value; in other words, the value will not be saved to the itcl\_options() array unless the method saves it there.  The named method must take two arguments, the option name and its new value. For example, this code is equivalent to (though slower than) Itcl's default handling of configure: 



```
option -font -configuremethod SetOption
        method SetOption {option value} {
            set itcl_options($option) $value
        }
```
 Note that it's possible for any number of options to share a single -configuremethod. 




**-configuremethodvar** *varName*

 That is very similar to -configuremethod, the only difference is, one can define a variable, where to find the configuremethod during runtime. 


**-validatemethod** *methodName*

 Every locally-defined option may define a -validatemethod; it is called when the option's value is set using the configure or configurelist methods, just before the -configuremethod (if any). It is the named method's responsibility to validate the option's new value, and to throw an error if the value is invalid.  The named method must take two arguments, the option name and its new value. For example, this code verifies that -flag's value is a valid Boolean value: 



```
option -font -validatemethod CheckBoolean
        method CheckBoolean {option value} {
            if {![string is boolean -strict $value]} {
                error "option $option must have a boolean value."
            }
        }
```
 Note that it's possible for any number of options to share a single -validatemethod. 




**-validatemethodvar** *varName*

 That is very similar to -validatemethod, the only difference is, one can define a variable, where to find the validatemethod during runtime. 

 Copyright © 2008 Arnulf Wiedemann 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/itcloption.htm>

format
======

  
[NAME](format.htm#M2) format — Format a string in the style of sprintf 
[SYNOPSIS](format.htm#M3) 
[INTRODUCTION](format.htm#M4) 
[DETAILS ON FORMATTING](format.htm#M5) 
[OPTIONAL POSITIONAL SPECIFIER](format.htm#M6) 
[OPTIONAL FLAGS](format.htm#M7)  
[**-**](format.htm#M8) 
[**+**](format.htm#M9) 
[*space*](format.htm#M10) 
[**0**](format.htm#M11) 
[**#**](format.htm#M12) 




 
[OPTIONAL FIELD WIDTH](format.htm#M13) 
[OPTIONAL PRECISION/BOUND](format.htm#M14) 
[OPTIONAL SIZE MODIFIER](format.htm#M15) 
[MANDATORY CONVERSION TYPE](format.htm#M16)  
[**d**](format.htm#M17) 
[**u**](format.htm#M18) 
[**i**](format.htm#M19) 
[**o**](format.htm#M20) 
[**x** or **X**](format.htm#M21) 
[**b**](format.htm#M22) 
[**c**](format.htm#M23) 
[**s**](format.htm#M24) 
[**f**](format.htm#M25) 
[**e** or **E**](format.htm#M26) 
[**g** or **G**](format.htm#M27) 
[**%**](format.htm#M28) 











 
[DIFFERENCES FROM ANSI SPRINTF](format.htm#M29) 
[EXAMPLES](format.htm#M30) 
[SEE ALSO](format.htm#M31) 
[KEYWORDS](format.htm#M32) 













 Name
----

 format — Format a string in the style of sprintf Synopsis
--------

 **format** *formatString* ?*arg arg ...*?  
 Introduction
------------

 This command generates a formatted string in a fashion similar to the ANSI C **sprintf** procedure. *FormatString* indicates how to format the result, using **%** conversion specifiers as in **sprintf**, and the additional arguments, if any, provide values to be substituted into the result. The return value from **format** is the formatted string. Details on formatting
---------------------

 The command operates by scanning *formatString* from left to right. Each character from the format string is appended to the result string unless it is a percent sign. If the character is a **%** then it is not copied to the result string. Instead, the characters following the **%** character are treated as a conversion specifier. The conversion specifier controls the conversion of the next successive *arg* to a particular format and the result is appended to the result string in place of the conversion specifier. If there are multiple conversion specifiers in the format string, then each one controls the conversion of one additional *arg*. The **format** command must be given enough *arg*s to meet the needs of all of the conversion specifiers in *formatString*.  Each conversion specifier may contain up to six different parts: an XPG3 position specifier, a set of flags, a minimum field width, a precision, a size modifier, and a conversion character. Any of these fields may be omitted except for the conversion character. The fields that are present must appear in the order given above. The paragraphs below discuss each of these fields in turn. 


### Optional positional specifier

 If the **%** is followed by a decimal number and a **$**, as in “**%2$d**”, then the value to convert is not taken from the next sequential argument. Instead, it is taken from the argument indicated by the number, where 1 corresponds to the first *arg*. If the conversion specifier requires multiple arguments because of **\*** characters in the specifier then successive arguments are used, starting with the argument given by the number. This follows the XPG3 conventions for positional specifiers. If there are any positional specifiers in *formatString* then all of the specifiers must be positional. ### Optional flags

 The second portion of a conversion specifier may contain any of the following flag characters, in any order: 
 **-**
 Specifies that the converted argument should be left-justified in its field (numbers are normally right-justified with leading spaces if needed). 

**+**
 Specifies that a number should always be printed with a sign, even if positive. 

*space*
 Specifies that a space should be added to the beginning of the number if the first character is not a sign. 

**0**
 Specifies that the number should be padded on the left with zeroes instead of spaces. 

**#**
 Requests an alternate output form. For **o** and **O** conversions it guarantees that the first digit is always **0**. For **x** or **X** conversions, **0x** or **0X** (respectively) will be added to the beginning of the result unless it is zero. For **b** conversions, **0b** will be added to the beginning of the result unless it is zero. For all floating-point conversions (**e**, **E**, **f**, **g**, and **G**) it guarantees that the result always has a decimal point. For **g** and **G** conversions it specifies that trailing zeroes should not be removed. 

 ### Optional field width

 The third portion of a conversion specifier is a decimal number giving a minimum field width for this conversion. It is typically used to make columns line up in tabular printouts. If the converted argument contains fewer characters than the minimum field width then it will be padded so that it is as wide as the minimum field width. Padding normally occurs by adding extra spaces on the left of the converted argument, but the **0** and **-** flags may be used to specify padding with zeroes on the left or with spaces on the right, respectively. If the minimum field width is specified as **\*** rather than a number, then the next argument to the **format** command determines the minimum field width; it must be an integer value. ### Optional precision/bound

 The fourth portion of a conversion specifier is a precision, which consists of a period followed by a number. The number is used in different ways for different conversions. For **e**, **E**, and **f** conversions it specifies the number of digits to appear to the right of the decimal point. For **g** and **G** conversions it specifies the total number of digits to appear, including those on both sides of the decimal point (however, trailing zeroes after the decimal point will still be omitted unless the **#** flag has been specified). For integer conversions, it specifies a minimum number of digits to print (leading zeroes will be added if necessary). For **s** conversions it specifies the maximum number of characters to be printed; if the string is longer than this then the trailing characters will be dropped. If the precision is specified with **\*** rather than a number then the next argument to the **format** command determines the precision; it must be a numeric string. ### Optional size modifier

 The fifth part of a conversion specifier is a size modifier, which must be **ll**, **h**, or **l**. If it is **ll** it specifies that an integer value is taken without truncation for conversion to a formatted substring. If it is **h** it specifies that an integer value is truncated to a 16-bit range before converting. This option is rarely useful. If it is **l** it specifies that the integer value is truncated to the same range as that produced by the **[wide()](mathfunc.htm)** function of the **[expr](expr.htm)** command (at least a 64-bit range). If neither **h** nor **l** are present, the integer value is truncated to the same range as that produced by the **[int()](mathfunc.htm)** function of the **[expr](expr.htm)** command (at least a 32-bit range, but determined by the value of the **wordSize** element of the **[tcl\_platform](tclvars.htm)** array). ### Mandatory conversion type

 The last thing in a conversion specifier is an alphabetic character that determines what kind of conversion to perform. The following conversion characters are currently supported: 
 **d**
 Convert integer to signed decimal string. 

**u**
 Convert integer to unsigned decimal string. 

**i**
 Convert integer to signed decimal string (equivalent to **d**). 

**o**
 Convert integer to unsigned octal string. 


**x** or **X**

 Convert integer to unsigned hexadecimal string, using digits “0123456789abcdef” for **x** and “0123456789ABCDEF” for **X**). 

**b**
 Convert integer to binary string, using digits 0 and 1. 

**c**
 Convert integer to the Unicode character it represents. 

**s**
 No conversion; just insert string. 

**f**
 Convert number to signed decimal string of the form *xx.yyy*, where the number of *y*'s is determined by the precision (default: 6). If the precision is 0 then no decimal point is output. 


**e** or **E**

 Convert number to scientific notation in the form *x.yyy***e±***zz*, where the number of *y*'s is determined by the precision (default: 6). If the precision is 0 then no decimal point is output. If the **E** form is used then **E** is printed instead of **e**. 


**g** or **G**

 If the exponent is less than -4 or greater than or equal to the precision, then convert number as for **%e** or **%E**. Otherwise convert as for **%f**. Trailing zeroes and a trailing decimal point are omitted. 

**%**
 No conversion: just insert **%**. 

 Differences from ansi sprintf
-----------------------------

 The behavior of the format command is the same as the ANSI C **sprintf** procedure except for the following differences: 
1. Tcl guarantees that it will be working with UNICODE characters.
2. **%p** and **%n** specifiers are not supported.
3. For **%c** conversions the argument must be an integer value, which will then be converted to the corresponding character value.
4. The size modifiers are ignored when formatting floating-point values. The **ll** modifier has no **sprintf** counterpart. The **b** specifier has no **sprintf** counterpart.

 Examples
--------

 Convert the numeric value of a UNICODE character to the character itself: 

```
set value 120
set char [**format** %c $value]
```
  Convert the output of **[time](time.htm)** into seconds to an accuracy of hundredths of a second: 



```
set us [lindex [time $someTclCode] 0]
puts [**format** "%.2f seconds to execute" [expr {$us / 1e6}]]
```
  Create a packed X11 literal color specification: 



```
# Each color-component should be in range (0..255)
set color [**format** "#%02x%02x%02x" $r $g $b]
```
  Use XPG3 format codes to allow reordering of fields (a technique that is often used in localized message catalogs; see **[msgcat](msgcat.htm)**) without reordering the data values passed to **format**: 



```
set fmt1 "Today, %d shares in %s were bought at $%.2f each"
puts [**format** $fmt1 123 "Global BigCorp" 19.37]

set fmt2 "Bought %2\$s equity ($%3$.2f x %1\$d) today"
puts [**format** $fmt2 123 "Global BigCorp" 19.37]
```
  Print a small table of powers of three: 



```
# Set up the column widths
set w1 5
set w2 10

# Make a nice header (with separator) for the table first
set sep +-[string repeat - $w1]-+-[string repeat - $w2]-+
puts $sep
puts [**format** "| %-*s | %-*s |" $w1 "Index" $w2 "Power"]
puts $sep

# Print the contents of the table
set p 1
for {set i 0} {$i<=20} {incr i} {
    puts [**format** "| %*d | %*ld |" $w1 $i $w2 $p]
    set p [expr {wide($p) * 3}]
}

# Finish off by printing the separator again
puts $sep
```
 See also
--------

 **[scan](scan.htm)**, **sprintf**, **[string](string.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/format.htm>

itclextendedclass
=================

  
[NAME](itclextendedclass.htm#M2) itcl::extendedclass — create a extendedclass of objects 
[WARNING!](itclextendedclass.htm#M3) 
[SYNOPSIS](itclextendedclass.htm#M4) 
[DESCRIPTION](itclextendedclass.htm#M5) 
[CLASS DEFINITIONS](itclextendedclass.htm#M6)  
[**extendedclass** *extendedclassName definition*](itclextendedclass.htm#M7) 
  
[**inherit** *baseExtendedclass* ?*baseExtendedclass*...?](itclextendedclass.htm#M8) 
[**constructor** *args* ?*init*? *body*](itclextendedclass.htm#M9) 
[**destructor** *body*](itclextendedclass.htm#M10) 


  
[**method** *name* ?*args*? ?*body*?](itclextendedclass.htm#M11) 
[**proc** *name* ?*args*? ?*body*?](itclextendedclass.htm#M12) 
[**variable** *varName* ?*init*? ?*config*?](itclextendedclass.htm#M13) 
[**common** *varName* ?*init*?](itclextendedclass.htm#M14) 
[**public** *command* ?*arg arg ...*?](itclextendedclass.htm#M15) 
[**protected** *command* ?*arg arg ...*?](itclextendedclass.htm#M16) 
[**private** *command* ?*arg arg ...*?](itclextendedclass.htm#M17) 






 
[CLASS USAGE](itclextendedclass.htm#M18)  
[*extendedclassName objName* ?*args...*?](itclextendedclass.htm#M19) 
 
[OBJECT USAGE](itclextendedclass.htm#M20)  
[*objName method* ?*args...*?](itclextendedclass.htm#M21) 
 
[BUILT-IN METHODS](itclextendedclass.htm#M22)  
[*objName* **cget option**](itclextendedclass.htm#M23) 
[*objName* **configure** ?*option*? ?*value option value ...*?](itclextendedclass.htm#M24) 
[*objName* **isa** *extendedclassName*](itclextendedclass.htm#M25) 
[*objName* **info** *option* ?*args...*?](itclextendedclass.htm#M26)  
[*objName* **info extendedclass**](itclextendedclass.htm#M27) 
[*objName* **info inherit**](itclextendedclass.htm#M28) 
[*objName* **info heritage**](itclextendedclass.htm#M29) 
[*objName* **info function** ?*cmdName*? ?**-protection**? ?**-type**? ?**-name**? ?**-args**? ?**-body**?](itclextendedclass.htm#M30) 
[*objName* **info variable** ?*varName*? ?**-protection**? ?**-type**? ?**-name**? ?**-init**? ?**-value**? ?**-config**?](itclextendedclass.htm#M31) 




 



 
[CHAINING METHODS/PROCS](itclextendedclass.htm#M32) 
[AUTO-LOADING](itclextendedclass.htm#M33) 
[C PROCEDURES](itclextendedclass.htm#M34) 
[KEYWORDS](itclextendedclass.htm#M35) 











 Name
----

 itcl::extendedclass — create a extendedclass of objects Warning!
--------

 This is new functionality in [incr Tcl] where the API can still change!! Synopsis
--------

 **itcl::extendedclass** *extendedclassName* **{**  
 **inherit** *baseExtendedclass* ?*baseExtendedclass*...?  
 **constructor** *args* ?*init*? *body*  
 **destructor** *body*  
 **public method** *name* ?*args*? ?*body*?  
 **protected method** *name* ?*args*? ?*body*?  
 **private method** *name* ?*args*? ?*body*?  
 **public proc** *name* ?*args*? ?*body*?  
 **protected proc** *name* ?*args*? ?*body*?  
 **private proc** *name* ?*args*? ?*body*?  
 **public variable** *varName* ?*init*? ?*config*?  
 **protected variable** *varName* ?*init*? ?*config*?  
 **private variable** *varName* ?*init*? ?*config*?  
 **public common** *varName* ?*init*?  
 **protected common** *varName* ?*init*?  
 **private common** *varName* ?*init*?  
   
 **public** *command* ?*arg arg ...*?  
 **protected** *command* ?*arg arg ...*?  
 **private** *command* ?*arg arg ...*?  
   
 **<delegation info>** see delegation page  
   
 **<option info>** see option page  
   
 **set** *varName* ?*value*?  
 **[array](../tclcmd/array.htm)** *option* ?*arg arg ...*?  
 **}**  
   
 *extendedclassName objName* ?*arg arg ...*?  
   
 *objName method* ?*arg arg ...*?  
   
 *extendedclassName::proc* ?*arg arg ...*?  
 Description
-----------

 The fundamental construct in **[incr Tcl]** is the extendedclass definition. Each extendedclass acts as a template for actual objects that can be created. The extendedclass itself is a namespace which contains things common to all objects. Each object has its own unique bundle of data which contains instances of the "variables" defined in the extendedclass definition. Each object also has a built-in variable named "this", which contains the name of the object. Extendedclasses can also have "common" data members that are shared by all objects in a extendedclass.  Two types of functions can be included in the extendedclass definition. "Methods" are functions which operate on a specific object, and therefore have access to both "variables" and "common" data members. "Procs" are ordinary procedures in the extendedclass namespace, and only have access to "common" data members. 


 If the body of any method or proc starts with "**@**", it is treated as the symbolic name for a C procedure. Otherwise, it is treated as a Tcl code script. See below for details on registering and using C procedures. 


 A extendedclass can only be defined once, although the bodies of extendedclass methods and procs can be defined again and again for interactive debugging. See the **body** and **configbody** commands for details. 


 Each namespace can have its own collection of objects and extendedclasses. The list of extendedclasses available in the current context can be queried using the "**[itcl::find extendedclasses](find.htm)**" command, and the list of objects, with the "**[itcl::find objects](find.htm)**" command. 


 A extendedclass can be deleted using the "**delete extendedclass**" command. Individual objects can be deleted using the "**delete object**" command. 


Class definitions
-----------------

  
**extendedclass** *extendedclassName definition*

 Provides the definition for a extendedclass named *extendedclassName*. If the extendedclass *extendedclassName* already exists, or if a command called *extendedclassName* exists in the current namespace context, this command returns an error. If the extendedclass definition is successfully parsed, *extendedclassName* becomes a command in the current context, handling the creation of objects for this extendedclass. 

  The extendedclass *definition* is evaluated as a series of Tcl statements that define elements within the extendedclass. The following extendedclass definition commands are recognized: 


 
**inherit** *baseExtendedclass* ?*baseExtendedclass*...?
 Causes the current extendedclass to inherit characteristics from one or more base extendedclasses. Extendedclasses must have been defined by a previous **extendedclass** command, or must be available to the auto-loading facility (see "AUTO-LOADING" below). A single extendedclass definition can contain no more than one **inherit** command.  The order of *baseExtendedclass* names in the **inherit** list affects the name resolution for extendedclass members. When the same member name appears in two or more base extendedclasses, the base extendedclass that appears first in the **inherit** list takes precedence. For example, if extendedclasses "Foo" and "Bar" both contain the member "x", and if another extendedclass has the "**inherit**" statement: 



```
inherit Foo Bar
```
 then the name "x" means "Foo::x". Other inherited members named "x" must be referenced with their explicit name, like "Bar::x". 




**constructor** *args* ?*init*? *body*

 Declares the *args* argument list and *body* used for the constructor, which is automatically invoked whenever an object is created.  Before the *body* is executed, the optional *init* statement is used to invoke any base extendedclass constructors that require arguments. Variables in the *args* specification can be accessed in the *init* code fragment, and passed to base extendedclass constructors. After evaluating the *init* statement, any base extendedclass constructors that have not been executed are invoked automatically without arguments. This ensures that all base extendedclasses are fully constructed before the constructor *body* is executed. By default, this scheme causes constructors to be invoked in order from least- to most-specific. This is exactly the opposite of the order that extendedclasses are reported by the **[info heritage](../tclcmd/info.htm)** command. 


If construction is successful, the constructor always returns the object name-regardless of how the *body* is defined-and the object name becomes a command in the current namespace context. If construction fails, an error message is returned. 




**destructor** *body*

 Declares the *body* used for the destructor, which is automatically invoked when an object is deleted. If the destructor is successful, the object data is destroyed and the object name is removed as a command from the interpreter. If destruction fails, an error message is returned and the object remains. 

When an object is destroyed, all destructors in its extendedclass hierarchy are invoked in order from most- to least-specific. This is the order that the extendedclasses are reported by the "**[info heritage](../tclcmd/info.htm)**" command, and it is exactly the opposite of the default constructor order.


 
**method** *name* ?*args*? ?*body*?
 Declares a method called *name*. When the method *body* is executed, it will have automatic access to object-specific variables and common data members.  If the *args* list is specified, it establishes the usage information for this method. The **body** command can be used to redefine the method body, but the *args* list must match this specification. 


Within the body of another extendedclass method, a method can be invoked like any other command-simply by using its name. Outside of the extendedclass context, the method name must be prefaced an object name, which provides the context for the data that it manipulates. Methods in a base extendedclass that are redefined in the current extendedclass, or hidden by another base extendedclass, can be qualified using the "*extendedclassName*::*method*" syntax. 




**proc** *name* ?*args*? ?*body*?
 Declares a proc called *name*. A proc is an ordinary procedure within the extendedclass namespace. Unlike a method, a proc is invoked without referring to a specific object. When the proc *body* is executed, it will have automatic access only to common data members.  If the *args* list is specified, it establishes the usage information for this proc. The **body** command can be used to redefine the proc body, but the *args* list must match this specification. 


Within the body of another extendedclass method or proc, a proc can be invoked like any other command-simply by using its name. In any other namespace context, the proc is invoked using a qualified name like "*extendedclassName***::***proc*". Procs in a base extendedclass that are redefined in the current extendedclass, or hidden by another base extendedclass, can also be accessed via their qualified name. 




**variable** *varName* ?*init*? ?*config*?
 Defines an object-specific variable named *varName*. All object-specific variables are automatically available in extendedclass methods. They need not be declared with anything like the **[global](../tclcmd/global.htm)** command.  If the optional *init* string is specified, it is used as the initial value of the variable when a new object is created. Initialization forces the variable to be a simple scalar value; uninitialized variables, on the other hand, can be set within the constructor and used as arrays. 


The optional *config* script is only allowed for public variables. If specified, this code fragment is executed whenever a public variable is modified by the built-in "configure" method. The *config* script can also be specified outside of the extendedclass definition using the **configbody** command. 




**common** *varName* ?*init*?
 Declares a common variable named *varName*. Common variables reside in the extendedclass namespace and are shared by all objects belonging to the extendedclass. They are just like global variables, except that they need not be declared with the usual **[global](../tclcmd/global.htm)** command. They are automatically visible in all extendedclass methods and procs.  If the optional *init* string is specified, it is used as the initial value of the variable. Initialization forces the variable to be a simple scalar value; uninitialized variables, on the other hand, can be set with subsequent **[set](../tclcmd/set.htm)** and **[array](../tclcmd/array.htm)** commands and used as arrays. 


 Once a common data member has been defined, it can be set using **[set](../tclcmd/set.htm)** and **[array](../tclcmd/array.htm)** commands within the extendedclass definition. This allows common data members to be initialized as arrays. For example: 



```
itcl::extendedclass Foo {
    common boolean
    set boolean(true) 1
    set boolean(false) 0
}
```
 Note that if common data members are initialized within the constructor, they get initialized again and again whenever new objects are created. 




**public** *command* ?*arg arg ...*?

**protected** *command* ?*arg arg ...*?

**private** *command* ?*arg arg ...*?
 These commands are used to set the protection level for extendedclass members that are created when *command* is evaluated. The *command* is usually **method**, **[proc](../tclcmd/proc.htm)**, **[variable](../tclcmd/variable.htm)** or**common**, and the remaining *arg*'s complete the member definition. However, *command* can also be a script containing many different member definitions, and the protection level will apply to all of the members that are created. 

 Class usage
-----------

 Once a extendedclass has been defined, the extendedclass name can be used as a command to create new objects belonging to the extendedclass. 
 
*extendedclassName objName* ?*args...*?
 Creates a new object in extendedclass *extendedclassName* with the name *objName*. Remaining arguments are passed to the constructor of the most-specific extendedclass. This in turn passes arguments to base extendedclass constructors before invoking its own body of commands. If construction is successful, a command called *objName* is created in the current namespace context, and *objName* is returned as the result of this operation. If an error is encountered during construction, the destructors are automatically invoked to free any resources that have been allocated, the object is deleted, and an error is returned.  If *objName* contains the string "**#auto**", that string is replaced with an automatically generated name. Names have the form *extendedclassName<number>*, where the *extendedclassName* part is modified to start with a lowercase letter. In extendedclass "Toaster", for example, the "**#auto**" specification would produce names like toaster0, toaster1, etc. Note that "**#auto**" can be also be buried within an object name: 



```
fileselectiondialog .foo.bar.#auto -background red
```
 This would generate an object named ".foo.bar.fileselectiondialog0". 



 Object usage
------------

 Once an object has been created, the object name can be used as a command to invoke methods that operate on the object. 
 
*objName method* ?*args...*?
 Invokes a method named *method* on an object named *objName*. Remaining arguments are passed to the argument list for the method. The method name can be "constructor", "destructor", any method name appearing in the extendedclass definition, or any of the following built-in methods. 

 Built-in methods
----------------

  
*objName* **cget option**

 Provides access to public variables as configuration options. This mimics the behavior of the usual "cget" operation for Tk widgets. The *option* argument is a string of the form "**-***varName*", and this method returns the current value of the public variable *varName*. 


*objName* **configure** ?*option*? ?*value option value ...*?
 Provides access to public variables as configuration options. This mimics the behavior of the usual "configure" operation for Tk widgets. With no arguments, this method returns a list of lists describing all of the public variables. Each list has three elements: the variable name, its initial value and its current value.  If a single *option* of the form "**-***varName*" is specified, then this method returns the information for that one variable. 


Otherwise, the arguments are treated as *option*/*value* pairs assigning new values to public variables. Each variable is assigned its new value, and if it has any "config" code associated with it, it is executed in the context of the extendedclass where it was defined. If the "config" code generates an error, the variable is set back to its previous value, and the **configure** method returns an error. 




*objName* **isa** *extendedclassName*

 Returns non-zero if the given *extendedclassName* can be found in the object's heritage, and zero otherwise. 


*objName* **info** *option* ?*args...*?
 Returns information related to a particular object named *objName*, or to its extendedclass definition. The *option* parameter includes the following things, as well as the options recognized by the usual Tcl "info" command: 
 
*objName* **info extendedclass**

 Returns the name of the most-specific extendedclass for object *objName*. 


*objName* **info inherit**

 Returns the list of base extendedclasses as they were defined in the "**inherit**" command, or an empty string if this extendedclass has no base extendedclasses. 


*objName* **info heritage**

 Returns the current extendedclass name and the entire list of base extendedclasses in the order that they are traversed for member lookup and object destruction. 


*objName* **info function** ?*cmdName*? ?**-protection**? ?**-type**? ?**-name**? ?**-args**? ?**-body**?
 With no arguments, this command returns a list of all extendedclass methods and procs. If *cmdName* is specified, it returns information for a specific method or proc. If no flags are specified, this command returns a list with the following elements: the protection level, the type (method/proc), the qualified name, the argument list and the body. Flags can be used to request specific elements from this list. 


*objName* **info variable** ?*varName*? ?**-protection**? ?**-type**? ?**-name**? ?**-init**? ?**-value**? ?**-config**?
 With no arguments, this command returns a list of all object-specific variables and common data members. If *varName* is specified, it returns information for a specific data member. If no flags are specified, this command returns a list with the following elements: the protection level, the type (variable/common), the qualified name, the initial value, and the current value. If *varName* is a public variable, the "config" code is included on this list. Flags can be used to request specific elements from this list. 



 Chaining methods/procs
----------------------

 Sometimes a base extendedclass has a method or proc that is redefined with the same name in a derived extendedclass. This is a way of making the derived extendedclass handle the same operations as the base extendedclass, but with its own specialized behavior. For example, suppose we have a Toaster extendedclass that looks like this: 

```
itcl::extendedclass Toaster {
    variable crumbs 0
    method toast {nslices} {
        if {$crumbs > 50} {
            error "== FIRE! FIRE! =="
        }
        set crumbs [expr $crumbs+4*$nslices]
    }
    method clean {} {
        set crumbs 0
    }
}
```
  We might create another extendedclass like SmartToaster that redefines the "toast" method. If we want to access the base extendedclass method, we can qualify it with the base extendedclass name, to avoid ambiguity: 



```
itcl::extendedclass SmartToaster {
    inherit Toaster
    method toast {nslices} {
        if {$crumbs > 40} {
            clean
        }
        return [Toaster::toast $nslices]
    }
}
```
  Instead of hard-coding the base extendedclass name, we can use the "chain" command like this: 



```
itcl::extendedclass SmartToaster {
    inherit Toaster
    method toast {nslices} {
        if {$crumbs > 40} {
            clean
        }
        return [chain $nslices]
    }
}
```
  The chain command searches through the extendedclass hierarchy for a slightly more generic (base extendedclass) implementation of a method or proc, and invokes it with the specified arguments. It starts at the current extendedclass context and searches through base extendedclasses in the order that they are reported by the "info heritage" command. If another implementation is not found, this command does nothing and returns the null string. 


Auto-loading
------------

 Extendedclass definitions need not be loaded explicitly; they can be loaded as needed by the usual Tcl auto-loading facility. Each directory containing extendedclass definition files should have an accompanying "tclIndex" file. Each line in this file identifies a Tcl procedure or **[incr Tcl]** extendedclass definition and the file where the definition can be found.  For example, suppose a directory contains the definitions for extendedclasses "Toaster" and "SmartToaster". Then the "tclIndex" file for this directory would look like: 



```
# Tcl autoload index file, version 2.0 for [incr Tcl]
# This file is generated by the "auto_mkindex" command
# and sourced to set up indexing information for one or
# more commands.  Typically each line is a command that
# sets an element in the auto_index array, where the
# element name is the name of a command and the value is
# a script that loads the command.

set auto_index(::Toaster) "source $dir/Toaster.itcl"
set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"
```
  The **[auto\_mkindex](../tclcmd/library.htm)** command is used to automatically generate "tclIndex" files. 


 The auto-loader must be made aware of this directory by appending the directory name to the "auto\_path" variable. When this is in place, extendedclasses will be auto-loaded as needed when used in an application. 


C procedures
------------

 C procedures can be integrated into an **[incr Tcl]** extendedclass definition to implement methods, procs, and the "config" code for public variables. Any body that starts with "**@**" is treated as the symbolic name for a C procedure.  Symbolic names are established by registering procedures via **[Itcl\_RegisterC()](https://www.tcl.tk/man/tcl/ItclLib/RegisterC.htm)**. This is usually done in the **[Tcl\_AppInit()](https://www.tcl.tk/man/tcl/TclLib/AppInit.htm)** procedure, which is automatically called when the interpreter starts up. In the following example, the procedure My\_FooCmd() is registered with the symbolic name "foo". This procedure can be referenced in the **body** command as "@foo". 



```
int
[Tcl\_AppInit](https://www.tcl.tk/man/tcl/TclLib/AppInit.htm)(interp)
    [Tcl\_Interp](https://www.tcl.tk/man/tcl/TclLib/Interp.htm) *interp;     /* Interpreter for application. */
{
    if (Itcl_Init(interp) == TCL_ERROR) {
        return TCL_ERROR;
    }

    if ([Itcl\_RegisterC](https://www.tcl.tk/man/tcl/ItclLib/RegisterC.htm)(interp, "foo", My_FooCmd) != TCL_OK) {
        return TCL_ERROR;
    }
}
```
  C procedures are implemented just like ordinary Tcl commands. See the **CrtCommand** man page for details. Within the procedure, extendedclass data members can be accessed like ordinary variables using **[Tcl\_SetVar()](https://www.tcl.tk/man/tcl/TclLib/SetVar.htm)**, **[Tcl\_GetVar()](https://www.tcl.tk/man/tcl/TclLib/SetVar.htm)**, **[Tcl\_TraceVar()](https://www.tcl.tk/man/tcl/TclLib/TraceVar.htm)**, etc. Extendedclass methods and procs can be executed like ordinary commands using **[Tcl\_Eval()](https://www.tcl.tk/man/tcl/TclLib/Eval.htm)**. **[incr Tcl]** makes this possible by automatically setting up the context before executing the C procedure. 


 This scheme provides a natural migration path for code development. Extendedclasses can be developed quickly using Tcl code to implement the bodies. An entire application can be built and tested. When necessary, individual bodies can be implemented with C code to improve performance. 

 Copyright © 2008 Arnulf Wiedemann 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/itclextendedclass.htm>

itclwidget
==========

  
[NAME](itclwidget.htm#M2) itcl::widget — create a widget class of objects 
[WARNING!](itclwidget.htm#M3) 
[SYNOPSIS](itclwidget.htm#M4) 
[DESCRIPTION](itclwidget.htm#M5) 
[WIDGET DEFINITIONS](itclwidget.htm#M6)  
[**widget** *widgetName definition*](itclwidget.htm#M7) 
  
[**inherit** *baseWidget* ?*baseWidget*...?](itclwidget.htm#M8) 
[**constructor** *args* ?*init*? *body*](itclwidget.htm#M9) 
[**destructor** *body*](itclwidget.htm#M10) 
[**method** *name* ?*args*? ?*body*?](itclwidget.htm#M11) 
[**proc** *name* ?*args*? ?*body*?](itclwidget.htm#M12) 
[**variable** *varName* ?*init*? ?*config*?](itclwidget.htm#M13) 
[**common** *varName* ?*init*?](itclwidget.htm#M14) 
[**public** *command* ?*arg arg ...*?](itclwidget.htm#M15) 
[**protected** *command* ?*arg arg ...*?](itclwidget.htm#M16) 
[**private** *command* ?*arg arg ...*?](itclwidget.htm#M17) 









 
[WIDGET USAGE](itclwidget.htm#M18)  
[*widgetName objName* ?*args...*?](itclwidget.htm#M19) 
 
[OBJECT USAGE](itclwidget.htm#M20)  
[*objName method* ?*args...*?](itclwidget.htm#M21) 
 
[BUILT-IN METHODS](itclwidget.htm#M22)  
[*objName* **cget option**](itclwidget.htm#M23) 
[*objName* **configure** ?*option*? ?*value option value ...*?](itclwidget.htm#M24) 
[*objName* **isa** *widgetName*](itclwidget.htm#M25) 
[*objName* **info** *option* ?*args...*?](itclwidget.htm#M26)  
[*objName* **info widget**](itclwidget.htm#M27) 
[*objName* **info inherit**](itclwidget.htm#M28) 
[*objName* **info heritage**](itclwidget.htm#M29) 
[*objName* **info function** ?*cmdName*? ?**-protection**? ?**-type**? ?**-name**? ?**-args**? ?**-body**?](itclwidget.htm#M30) 
[*objName* **info variable** ?*varName*? ?**-protection**? ?**-type**? ?**-name**? ?**-init**? ?**-value**? ?**-config**?](itclwidget.htm#M31) 




 



 
[CHAINING METHODS/PROCS](itclwidget.htm#M32) 
[AUTO-LOADING](itclwidget.htm#M33) 
[C PROCEDURES](itclwidget.htm#M34) 
[KEYWORDS](itclwidget.htm#M35) 











 Name
----

 itcl::widget — create a widget class of objects Warning!
--------

 This is new functionality in [incr Tcl] where the API can still change!! Synopsis
--------

 **itcl::widget** *widgetName* **{**  
 **inherit** *baseWidget* ?*baseWidget*...?  
 **constructor** *args* ?*init*? *body*  
 **destructor** *body*  
 **public method** *name* ?*args*? ?*body*?  
 **protected method** *name* ?*args*? ?*body*?  
 **private method** *name* ?*args*? ?*body*?  
 **public proc** *name* ?*args*? ?*body*?  
 **protected proc** *name* ?*args*? ?*body*?  
 **private proc** *name* ?*args*? ?*body*?  
 **public variable** *varName* ?*init*? ?*config*?  
 **protected variable** *varName* ?*init*? ?*config*?  
 **private variable** *varName* ?*init*? ?*config*?  
 **public common** *varName* ?*init*?  
 **protected common** *varName* ?*init*?  
 **private common** *varName* ?*init*?  
   
 **public** *command* ?*arg arg ...*?  
 **protected** *command* ?*arg arg ...*?  
 **private** *command* ?*arg arg ...*?  
   
 **<delegation info>** see delegation page  
   
 **<option info>** see option page  
   
 **set** *varName* ?*value*?  
 **[array](../tclcmd/array.htm)** *option* ?*arg arg ...*?  
 **}**  
   
 *widgetName objName* ?*arg arg ...*?  
   
 *objName method* ?*arg arg ...*?  
   
 *widgetName::proc* ?*arg arg ...*?  
 Description
-----------

 One of the fundamental constructs in **[incr Tcl]** is the widget definition. A widget is like a class with some additional features. Each widget acts as a template for actual objects that can be created. The widget itself is a namespace which contains things common to all objects. Each object has its own unique bundle of data which contains instances of the "variables" defined in the widget definition. Each object also has a built-in variable named "this", which contains the name of the object. Widgets can also have "common" data members that are shared by all objects in a widget.  Two types of functions can be included in the widget definition. "Methods" are functions which operate on a specific object, and therefore have access to both "variables" and "common" data members. "Procs" are ordinary procedures in the widget namespace, and only have access to "common" data members. 


 If the body of any method or proc starts with "**@**", it is treated as the symbolic name for a C procedure. Otherwise, it is treated as a Tcl code script. See below for details on registering and using C procedures. 


 A widget can only be defined once, although the bodies of widget methods and procs can be defined again and again for interactive debugging. See the **body** and **configbody** commands for details. 


 Each namespace can have its own collection of objects and widgets. The list of widgets available in the current context can be queried using the "**[itcl::find widgets](find.htm)**" command, and the list of objects, with the "**[itcl::find objects](find.htm)**" command. 


 A widget can be deleted using the "**delete widget**" command. Individual objects can be deleted using the "**delete object**" command. 


Widget definitions
------------------

  
**widget** *widgetName definition*

 Provides the definition for a widget named *widgetName*. If the widget *widgetName* already exists, or if a command called *widgetName* exists in the current namespace context, this command returns an error. If the widget definition is successfully parsed, *widgetName* becomes a command in the current context, handling the creation of objects for this widget. 

  The widget *definition* is evaluated as a series of Tcl statements that define elements within the widget. The following widget definition commands are recognized: 


 
**inherit** *baseWidget* ?*baseWidget*...?
 Causes the current widget to inherit characteristics from one or more base widgets. Widgets must have been defined by a previous **widget** command, or must be available to the auto-loading facility (see "AUTO-LOADING" below). A single widget definition can contain no more than one **inherit** command.  The order of *baseWidget* names in the **inherit** list affects the name resolution for widget members. When the same member name appears in two or more base widgets, the base widget that appears first in the **inherit** list takes precedence. For example, if widgets "Foo" and "Bar" both contain the member "x", and if another widget has the "**inherit**" statement: 



```
inherit Foo Bar
```
 then the name "x" means "Foo::x". Other inherited members named "x" must be referenced with their explicit name, like "Bar::x". 




**constructor** *args* ?*init*? *body*

 Declares the *args* argument list and *body* used for the constructor, which is automatically invoked whenever an object is created.  Before the *body* is executed, the optional *init* statement is used to invoke any base widget constructors that require arguments. Variables in the *args* specification can be accessed in the *init* code fragment, and passed to base widget constructors. After evaluating the *init* statement, any base widget constructors that have not been executed are invoked automatically without arguments. This ensures that all base widgets are fully constructed before the constructor *body* is executed. By default, this scheme causes constructors to be invoked in order from least- to most-specific. This is exactly the opposite of the order that widgets are reported by the **[info heritage](../tclcmd/info.htm)** command. 


If construction is successful, the constructor always returns the object name-regardless of how the *body* is defined-and the object name becomes a command in the current namespace context. If construction fails, an error message is returned. 




**destructor** *body*

 Declares the *body* used for the destructor, which is automatically invoked when an object is deleted. If the destructor is successful, the object data is destroyed and the object name is removed as a command from the interpreter. If destruction fails, an error message is returned and the object remains.  When an object is destroyed, all destructors in its widget hierarchy are invoked in order from most- to least-specific. This is the order that the widgets are reported by the "**[info heritage](../tclcmd/info.htm)**" command, and it is exactly the opposite of the default constructor order. 




**method** *name* ?*args*? ?*body*?
 Declares a method called *name*. When the method *body* is executed, it will have automatic access to object-specific variables and common data members.  If the *args* list is specified, it establishes the usage information for this method. The **body** command can be used to redefine the method body, but the *args* list must match this specification. 


Within the body of another widget method, a method can be invoked like any other command-simply by using its name. Outside of the widget context, the method name must be prefaced an object name, which provides the context for the data that it manipulates. Methods in a base widget that are redefined in the current widget, or hidden by another base widget, can be qualified using the "*widgetName*::*method*" syntax. 




**proc** *name* ?*args*? ?*body*?
 Declares a proc called *name*. A proc is an ordinary procedure within the widget namespace. Unlike a method, a proc is invoked without referring to a specific object. When the proc *body* is executed, it will have automatic access only to common data members.  If the *args* list is specified, it establishes the usage information for this proc. The **body** command can be used to redefine the proc body, but the *args* list must match this specification. 


Within the body of another widget method or proc, a proc can be invoked like any other command-simply by using its name. In any other namespace context, the proc is invoked using a qualified name like "*widgetName***::***proc*". Procs in a base widget that are redefined in the current widget, or hidden by another base widget, can also be accessed via their qualified name. 




**variable** *varName* ?*init*? ?*config*?
 Defines an object-specific variable named *varName*. All object-specific variables are automatically available in widget methods. They need not be declared with anything like the **[global](../tclcmd/global.htm)** command.  If the optional *init* string is specified, it is used as the initial value of the variable when a new object is created. Initialization forces the variable to be a simple scalar value; uninitialized variables, on the other hand, can be set within the constructor and used as arrays. 


The optional *config* script is only allowed for public variables. If specified, this code fragment is executed whenever a public variable is modified by the built-in "configure" method. The *config* script can also be specified outside of the widget definition using the **configbody** command. 




**common** *varName* ?*init*?
 Declares a common variable named *varName*. Common variables reside in the widget namespace and are shared by all objects belonging to the widget. They are just like global variables, except that they need not be declared with the usual **[global](../tclcmd/global.htm)** command. They are automatically visible in all widget methods and procs.  If the optional *init* string is specified, it is used as the initial value of the variable. Initialization forces the variable to be a simple scalar value; uninitialized variables, on the other hand, can be set with subsequent **[set](../tclcmd/set.htm)** and **[array](../tclcmd/array.htm)** commands and used as arrays. 


 Once a common data member has been defined, it can be set using **[set](../tclcmd/set.htm)** and **[array](../tclcmd/array.htm)** commands within the widget definition. This allows common data members to be initialized as arrays. For example: 



```
itcl::widget Foo {
    protected common boolean
    set boolean(true) 1
    set boolean(false) 0
}
```
 Note that if common data members are initialized within the constructor, they get initialized again and again whenever new objects are created. 




**public** *command* ?*arg arg ...*?

**protected** *command* ?*arg arg ...*?

**private** *command* ?*arg arg ...*?
 These commands are used to set the protection level for widget members that are created when *command* is evaluated. The *command* is usually **method**, **[proc](../tclcmd/proc.htm)**, **[variable](../tclcmd/variable.htm)** or**common**, and the remaining *arg*'s complete the member definition. However, *command* can also be a script containing many different member definitions, and the protection level will apply to all of the members that are created. 

 Widget usage
------------

 Once a widget has been defined, the widget name can be used as a command to create new objects belonging to the widget. 
 
*widgetName objName* ?*args...*?
 Creates a new object in widget *widgetName* with the name *objName*. Remaining arguments are passed to the constructor of the most-specific widget. This in turn passes arguments to base widget constructors before invoking its own body of commands. If construction is successful, a command called *objName* is created in the current namespace context, and *objName* is returned as the result of this operation. If an error is encountered during construction, the destructors are automatically invoked to free any resources that have been allocated, the object is deleted, and an error is returned.  If *objName* contains the string "**#auto**", that string is replaced with an automatically generated name. Names have the form *widgetName<number>*, where the *widgetName* part is modified to start with a lowercase letter. In widget "Toaster", for example, the "**#auto**" specification would produce names like toaster0, toaster1, etc. Note that "**#auto**" can be also be buried within an object name: 



```
fileselectiondialog .foo.bar.#auto -background red
```
 This would generate an object named ".foo.bar.fileselectiondialog0". 



 Object usage
------------

 Once an object has been created, the object name can be used as a command to invoke methods that operate on the object. 
 
*objName method* ?*args...*?
 Invokes a method named *method* on an object named *objName*. Remaining arguments are passed to the argument list for the method. The method name can be "constructor", "destructor", any method name appearing in the widget definition, or any of the following built-in methods. 

 Built-in methods
----------------

  
*objName* **cget option**

 Provides access to public variables as configuration options. This mimics the behavior of the usual "cget" operation for Tk widgets. The *option* argument is a string of the form "**-***varName*", and this method returns the current value of the public variable *varName*. 


*objName* **configure** ?*option*? ?*value option value ...*?
 Provides access to public variables as configuration options. This mimics the behavior of the usual "configure" operation for Tk widgets. With no arguments, this method returns a list of lists describing all of the public variables. Each list has three elements: the variable name, its initial value and its current value.  If a single *option* of the form "**-***varName*" is specified, then this method returns the information for that one variable. 


Otherwise, the arguments are treated as *option*/*value* pairs assigning new values to public variables. Each variable is assigned its new value, and if it has any "config" code associated with it, it is executed in the context of the widget where it was defined. If the "config" code generates an error, the variable is set back to its previous value, and the **configure** method returns an error. 




*objName* **isa** *widgetName*

 Returns non-zero if the given *widgetName* can be found in the object's heritage, and zero otherwise. 


*objName* **info** *option* ?*args...*?
 Returns information related to a particular object named *objName*, or to its widget definition. The *option* parameter includes the following things, as well as the options recognized by the usual Tcl "info" command: 
 
*objName* **info widget**

 Returns the name of the most-specific widget for object *objName*. 


*objName* **info inherit**

 Returns the list of base widgets as they were defined in the "**inherit**" command, or an empty string if this widget has no base widgets. 


*objName* **info heritage**

 Returns the current widget name and the entire list of base widgets in the order that they are traversed for member lookup and object destruction. 


*objName* **info function** ?*cmdName*? ?**-protection**? ?**-type**? ?**-name**? ?**-args**? ?**-body**?
 With no arguments, this command returns a list of all widgets methods and procs. If *cmdName* is specified, it returns information for a specific method or proc. If no flags are specified, this command returns a list with the following elements: the protection level, the type (method/proc), the qualified name, the argument list and the body. Flags can be used to request specific elements from this list. 


*objName* **info variable** ?*varName*? ?**-protection**? ?**-type**? ?**-name**? ?**-init**? ?**-value**? ?**-config**?
 With no arguments, this command returns a list of all object-specific variables and common data members. If *varName* is specified, it returns information for a specific data member. If no flags are specified, this command returns a list with the following elements: the protection level, the type (variable/common), the qualified name, the initial value, and the current value. If *varName* is a public variable, the "config" code is included on this list. Flags can be used to request specific elements from this list. 



 Chaining methods/procs
----------------------

 Sometimes a base widget has a method or proc that is redefined with the same name in a derived widget. This is a way of making the derived widget handle the same operations as the base widget, but with its own specialized behavior. For example, suppose we have a Toaster widget that looks like this: 

```
itcl::widget Toaster {
    variable crumbs 0
    method toast {nslices} {
        if {$crumbs > 50} {
            error "== FIRE! FIRE! =="
        }
        set crumbs [expr $crumbs+4*$nslices]
    }
    method clean {} {
        set crumbs 0
    }
}
```
  We might create another widget like SmartToaster that redefines the "toast" method. If we want to access the base widget method, we can qualify it with the base widget name, to avoid ambiguity: 



```
itcl::widget SmartToaster {
    inherit Toaster
    method toast {nslices} {
        if {$crumbs > 40} {
            clean
        }
        return [Toaster::toast $nslices]
    }
}
```
  Instead of hard-coding the base widget name, we can use the "chain" command like this: 



```
itcl::widget SmartToaster {
    inherit Toaster
    method toast {nslices} {
        if {$crumbs > 40} {
            clean
        }
        return [chain $nslices]
    }
}
```
  The chain command searches through the widget hierarchy for a slightly more generic (base widget) implementation of a method or proc, and invokes it with the specified arguments. It starts at the current widget context and searches through base widgets in the order that they are reported by the "info heritage" command. If another implementation is not found, this command does nothing and returns the null string. 


Auto-loading
------------

 Widget definitions need not be loaded explicitly; they can be loaded as needed by the usual Tcl auto-loading facility. Each directory containing widget definition files should have an accompanying "tclIndex" file. Each line in this file identifies a Tcl procedure or **[incr Tcl]** widget definition and the file where the definition can be found.  For example, suppose a directory contains the definitions for widgets "Toaster" and "SmartToaster". Then the "tclIndex" file for this directory would look like: 



```
# Tcl autoload index file, version 2.0 for [incr Tcl]
# This file is generated by the "auto_mkindex" command
# and sourced to set up indexing information for one or
# more commands.  Typically each line is a command that
# sets an element in the auto_index array, where the
# element name is the name of a command and the value is
# a script that loads the command.

set auto_index(::Toaster) "source $dir/Toaster.itcl"
set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"
```
  The **[auto\_mkindex](../tclcmd/library.htm)** command is used to automatically generate "tclIndex" files. 


 The auto-loader must be made aware of this directory by appending the directory name to the "auto\_path" variable. When this is in place, widgets will be auto-loaded as needed when used in an application. 


C procedures
------------

 C procedures can be integrated into an **[incr Tcl]** widget definition to implement methods, procs, and the "config" code for public variables. Any body that starts with "**@**" is treated as the symbolic name for a C procedure.  Symbolic names are established by registering procedures via **[Itcl\_RegisterC()](https://www.tcl.tk/man/tcl/ItclLib/RegisterC.htm)**. This is usually done in the **[Tcl\_AppInit()](https://www.tcl.tk/man/tcl/TclLib/AppInit.htm)** procedure, which is automatically called when the interpreter starts up. In the following example, the procedure My\_FooCmd() is registered with the symbolic name "foo". This procedure can be referenced in the **body** command as "@foo". 



```
int
[Tcl\_AppInit](https://www.tcl.tk/man/tcl/TclLib/AppInit.htm)(interp)
    [Tcl\_Interp](https://www.tcl.tk/man/tcl/TclLib/Interp.htm) *interp;     /* Interpreter for application. */
{
    if (Itcl_Init(interp) == TCL_ERROR) {
        return TCL_ERROR;
    }

    if ([Itcl\_RegisterC](https://www.tcl.tk/man/tcl/ItclLib/RegisterC.htm)(interp, "foo", My_FooCmd) != TCL_OK) {
        return TCL_ERROR;
    }
}
```
  C procedures are implemented just like ordinary Tcl commands. See the **CrtCommand** man page for details. Within the procedure, widget data members can be accessed like ordinary variables using **[Tcl\_SetVar()](https://www.tcl.tk/man/tcl/TclLib/SetVar.htm)**, **[Tcl\_GetVar()](https://www.tcl.tk/man/tcl/TclLib/SetVar.htm)**, **[Tcl\_TraceVar()](https://www.tcl.tk/man/tcl/TclLib/TraceVar.htm)**, etc. Widget methods and procs can be executed like ordinary commands using **[Tcl\_Eval()](https://www.tcl.tk/man/tcl/TclLib/Eval.htm)**. **[incr Tcl]** makes this possible by automatically setting up the context before executing the C procedure. 


 This scheme provides a natural migration path for code development. Widgets can be developed quickly using Tcl code to implement the bodies. An entire application can be built and tested. When necessary, individual bodies can be implemented with C code to improve performance. 

 Copyright © 2008 Arnulf Wiedemann 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/itclwidget.htm>

tdbc
====

 Name
----

 tdbc — Tcl Database Connectivity Synopsis
--------

 package require **tdbc 1.0**  
 package require **tdbc::***driver version*  
   
 **tdbc::***driver***::connection create** *db* ?*-option value*...?  
 Description
-----------

 Tcl Database Connectivity (TDBC) is a common interface for Tcl programs to access SQL databases. It is implemented by a series of database *drivers*: separate modules, each of which adapts Tcl to the interface of one particular database system. All of the drivers implement a common series of commands for manipulating the database. These commands are all named dynamically, since they all represent objects in the database system. They include **connections,** which represent connections to a database; **statements,** which represent SQL statements, and **result sets,** which represent the sets of rows that result from executing statements. All of these have manual pages of their own, listed under **[SEE ALSO](#M5)**.  In addition, TDBC itself has a few service procedures that are chiefly of interest to driver writers. **[SEE ALSO](#M5)** also enumerates them. 


See also
--------

 **[Tdbc\_Init](https://www.tcl.tk/man/tcl/TdbcLib/Tdbc_Init.htm)**, **[tdbc::connection](tdbc_connection.htm)**, **tdbc::mapSqlState**, **[tdbc::resultset](tdbc_resultset.htm)**, **[tdbc::statement](tdbc_statement.htm)**, **[tdbc::tokenize](tdbc_tokenize.htm)**, **[tdbc::mysql](../tdbcmysqlcmd/tdbc_mysql.htm)**, **[tdbc::odbc](../tdbcodbccmd/tdbc_odbc.htm)**, **[tdbc::postgres](../tdbcpostgrescmd/tdbc_postgres.htm)**, **[tdbc::sqlite3](../tdbcsqlitecmd/tdbc_sqlite3.htm)** Copyright
---------

 Copyright (c) 2008 by Kevin B. Kenny. Copyright © 2008 by Kevin B. Kenny. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcCmd/tdbc.htm>

tdbc\_mapSqlState
=================

 Name
----

 tdbc::mapSqlState — Map SQLSTATE to error class Synopsis
--------

 package require **tdbc 1.0**  
   
 **tdbc::mapSqlState** *sqlstate*  
 Description
-----------

 The **tdbc::mapSqlState** command accepts a string that is expected to be a five-character 'SQL state' as returned from a SQL database when an error occurs. It examines the first two characters of the string, and returns an error class as a human- and machine-readable name (for example, **FEATURE\_NOT\_SUPPORTED**, **DATA\_EXCEPTION** or **INVALID\_CURSOR\_STATE**).  The TDBC specification requires database drivers to return a description of an error in the error code when an error occurs. The description is a string that has at least four elements: "**[TDBC](tdbc.htm)** *errorClass* *sqlstate* *driverName* *details...*". The **tdbc::mapSqlState** command gives a convenient way for a TDBC driver to generate the *errorClass* element given the SQL state returned from a database. 


See also
--------

 **[tdbc](tdbc.htm)**, **[tdbc::tokenize](tdbc_tokenize.htm)**, **[tdbc::connection](tdbc_connection.htm)**, **[tdbc::statement](tdbc_statement.htm)**, **[tdbc::resultset](tdbc_resultset.htm)** Copyright
---------

 Copyright (c) 2009 by Kevin B. Kenny. Copyright © 2009 by Kevin B. Kenny. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcCmd/tdbc_mapSqlState.htm>

tdbc\_tokenize
==============

 Name
----

 tdbc::tokenize — TDBC SQL tokenizer Synopsis
--------

 package require **tdbc 1.0**  
   
 **tdbc::tokenize** *string*  
 Description
-----------

 As a convenience to database drivers, Tcl Database Connectivity (TDBC) provides a command to break SQL code apart into tokens so that bound variables can readily be identified and substituted.  The **tdbc::tokenize** command accepts as its parameter a string that is expected to contain one or more SQL statements. It returns a list of substrings; concatenating these substrings together will yield the original string. Each substring is one of the following: 


1. A bound variable, which begins with one of the characters '**:**', '**@**', or '**$**'. The remainder of the string is the variable name and will consist of alphanumeric characters and underscores. (The leading character will be be non-numeric.)
2. A semicolon that separates two SQL statements.
3. Something else in a SQL statement. The tokenizer does not attempt to parse SQL; it merely identifies bound variables (distinguishing them from similar strings appearing inside quotes or comments) and statement delimiters.

 See also
--------

 **[tdbc](tdbc.htm)**, **[tdbc::connection](tdbc_connection.htm)**, **[tdbc::statement](tdbc_statement.htm)**, **[tdbc::resultset](tdbc_resultset.htm)** Copyright
---------

 Copyright (c) 2008 by Kevin B. Kenny. Copyright © 2008 by Kevin B. Kenny. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcCmd/tdbc_tokenize.htm>

exec
====

  
[NAME](exec.htm#M2) exec — Invoke subprocesses 
[SYNOPSIS](exec.htm#M3) 
[DESCRIPTION](exec.htm#M4)  
[**-ignorestderr**](exec.htm#M5) 
[**-keepnewline**](exec.htm#M6) 
[**--**](exec.htm#M7) 


  
[**|**](exec.htm#M8) 
[**|&**](exec.htm#M9) 
[**<** *fileName*](exec.htm#M10) 
[**<@** *fileId*](exec.htm#M11) 
[**<<** *value*](exec.htm#M12) 
[**>** *fileName*](exec.htm#M13) 
[**2>** *fileName*](exec.htm#M14) 
[**>&** *fileName*](exec.htm#M15) 
[**>>** *fileName*](exec.htm#M16) 
[**2>>** *fileName*](exec.htm#M17) 
[**>>&** *fileName*](exec.htm#M18) 
[**>@** *fileId*](exec.htm#M19) 
[**2>@** *fileId*](exec.htm#M20) 
[**2>@1**](exec.htm#M21)  
[**>&@** *fileId*](exec.htm#M22) 














 
[PORTABILITY ISSUES](exec.htm#M23)  
[**Windows** (all versions)](exec.htm#M24) 
[**Unix** (including Mac OS X)](exec.htm#M25) 

 
[UNIX EXAMPLES](exec.htm#M26) 
[WORKING WITH NON-ZERO RESULTS](exec.htm#M27) 
[WORKING WITH QUOTED ARGUMENTS](exec.htm#M28) 
[WORKING WITH GLOBBING](exec.htm#M29) 
[WORKING WITH USER-SUPPLIED SHELL SCRIPT FRAGMENTS](exec.htm#M30) 
[WINDOWS EXAMPLES](exec.htm#M31) 
[WORKING WITH CONSOLE PROGRAMS](exec.htm#M32) 
[WORKING WITH COMMAND BUILT-INS](exec.htm#M33) 
[WORKING WITH NATIVE FILENAMES](exec.htm#M34) 
[SEE ALSO](exec.htm#M35) 
[KEYWORDS](exec.htm#M36) 














 Name
----

 exec — Invoke subprocesses Synopsis
--------

 **exec** ?*switches*? *arg* ?*arg ...*? ?**&**?  
 Description
-----------

 This command treats its arguments as the specification of one or more subprocesses to execute. The arguments take the form of a standard shell pipeline where each *arg* becomes one word of a command, and each distinct command becomes a subprocess.  If the initial arguments to **exec** start with **-** then they are treated as command-line switches and are not part of the pipeline specification. The following switches are currently supported: 


 **-ignorestderr**
 Stops the **exec** command from treating the output of messages to the pipeline's standard error channel as an error case. 

**-keepnewline**
 Retains a trailing newline in the pipeline's output. Normally a trailing newline will be deleted. 

**--**
 Marks the end of switches. The argument following this one will be treated as the first *arg* even if it starts with a **-**. 

  If an *arg* (or pair of *arg*s) has one of the forms described below then it is used by **exec** to control the flow of input and output among the subprocess(es). Such arguments will not be passed to the subprocess(es). In forms such as “**<** *fileName*”, *fileName* may either be in a separate argument from “**<**” or in the same argument with no intervening space (i.e. “**<***fileName*”). 


 **|**
 Separates distinct commands in the pipeline. The standard output of the preceding command will be piped into the standard input of the next command. 

**|&**
 Separates distinct commands in the pipeline. Both standard output and standard error of the preceding command will be piped into the standard input of the next command. This form of redirection overrides forms such as 2> and >&. 


**<** *fileName*

 The file named by *fileName* is opened and used as the standard input for the first command in the pipeline. 


**<@** *fileId*

 *FileId* must be the identifier for an open file, such as the return value from a previous call to **[open](open.htm)**. It is used as the standard input for the first command in the pipeline. *FileId* must have been opened for reading. 


**<<** *value*

 *Value* is passed to the first command as its standard input. 


**>** *fileName*

 Standard output from the last command is redirected to the file named *fileName*, overwriting its previous contents. 


**2>** *fileName*

 Standard error from all commands in the pipeline is redirected to the file named *fileName*, overwriting its previous contents. 


**>&** *fileName*

 Both standard output from the last command and standard error from all commands are redirected to the file named *fileName*, overwriting its previous contents. 


**>>** *fileName*

 Standard output from the last command is redirected to the file named *fileName*, appending to it rather than overwriting it. 


**2>>** *fileName*

 Standard error from all commands in the pipeline is redirected to the file named *fileName*, appending to it rather than overwriting it. 


**>>&** *fileName*

 Both standard output from the last command and standard error from all commands are redirected to the file named *fileName*, appending to it rather than overwriting it. 


**>@** *fileId*

 *FileId* must be the identifier for an open file, such as the return value from a previous call to **[open](open.htm)**. Standard output from the last command is redirected to *fileId*'s file, which must have been opened for writing. 


**2>@** *fileId*

 *FileId* must be the identifier for an open file, such as the return value from a previous call to **[open](open.htm)**. Standard error from all commands in the pipeline is redirected to *fileId*'s file. The file must have been opened for writing. 

**2>@1** 
 Standard error from all commands in the pipeline is redirected to the command result. This operator is only valid at the end of the command pipeline. 


**>&@** *fileId*

 *FileId* must be the identifier for an open file, such as the return value from a previous call to **[open](open.htm)**. Both standard output from the last command and standard error from all commands are redirected to *fileId*'s file. The file must have been opened for writing. 

  If standard output has not been redirected then the **exec** command returns the standard output from the last command in the pipeline, unless “2>@1” was specified, in which case standard error is included as well. If any of the commands in the pipeline exit abnormally or are killed or suspended, then **exec** will return an error and the error message will include the pipeline's output followed by error messages describing the abnormal terminations; the **-errorcode** return option will contain additional information about the last abnormal termination encountered. If any of the commands writes to its standard error file and that standard error is not redirected and **-ignorestderr** is not specified, then **exec** will return an error; the error message will include the pipeline's standard output, followed by messages about abnormal terminations (if any), followed by the standard error output. 


 If the last character of the result or error message is a newline then that character is normally deleted from the result or error message. This is consistent with other Tcl return values, which do not normally end with newlines. However, if **-keepnewline** is specified then the trailing newline is retained. 


 If standard input is not redirected with “<”, “<<” or “<@” then the standard input for the first command in the pipeline is taken from the application's current standard input. 


 If the last *arg* is “&” then the pipeline will be executed in background. In this case the **exec** command will return a list whose elements are the process identifiers for all of the subprocesses in the pipeline. The standard output from the last command in the pipeline will go to the application's standard output if it has not been redirected, and error output from all of the commands in the pipeline will go to the application's standard error file unless redirected. 


 The first word in each command is taken as the command name; tilde-substitution is performed on it, and if the result contains no slashes then the directories in the PATH environment variable are searched for an executable by the given name. If the name contains a slash then it must refer to an executable reachable from the current directory. No “glob” expansion or other shell-like substitutions are performed on the arguments to commands. 


Portability issues
------------------

  
**Windows** (all versions)
 Reading from or writing to a socket, using the “**@** *fileId*” notation, does not work. When reading from a socket, a 16-bit DOS application will hang and a 32-bit application will return immediately with end-of-file. When either type of application writes to a socket, the information is instead sent to the console, if one is present, or is discarded.  The Tk console text widget does not provide real standard IO capabilities. Under Tk, when redirecting from standard input, all applications will see an immediate end-of-file; information redirected to standard output or standard error will be discarded. 


 Either forward or backward slashes are accepted as path separators for arguments to Tcl commands. When executing an application, the path name specified for the application may also contain forward or backward slashes as path separators. Bear in mind, however, that most Windows applications accept arguments with forward slashes only as option delimiters and backslashes only in paths. Any arguments to an application that specify a path name with forward slashes will not automatically be converted to use the backslash character. If an argument contains forward slashes as the path separator, it may or may not be recognized as a path name, depending on the program. 


 Additionally, when calling a 16-bit DOS or Windows 3.X application, all path names must use the short, cryptic, path format (e.g., using “applba~1.def” instead of “applbakery.default”), which can be obtained with the “**[file attributes](file.htm)** *fileName* **-shortname**” command. 


 Two or more forward or backward slashes in a row in a path refer to a network path. For example, a simple concatenation of the root directory **c:/** with a subdirectory **/windows/system** will yield **c://windows/system** (two slashes together), which refers to the mount point called **system** on the machine called **windows** (and the **c:/** is ignored), and is not equivalent to **c:/windows/system**, which describes a directory on the current computer. The **[file join](file.htm)** command should be used to concatenate path components. 


 Note that there are two general types of Win32 console applications: 


1. CLI — CommandLine Interface, simple stdio exchange. **netstat.exe** for example.
2. TUI — Textmode User Interface, any application that accesses the console API for doing such things as cursor movement, setting text color, detecting key presses and mouse movement, etc. An example would be **telnet.exe** from Windows 2000. These types of applications are not common in a windows environment, but do exist.

  **exec** will not work well with TUI applications when a console is not present, as is done when launching applications under wish. It is desirable to have console applications hidden and detached. This is a designed-in limitation as **exec** wants to communicate over pipes. The Expect extension addresses this issue when communicating with a TUI application. 


 When attempting to execute an application, **exec** first searches for the name as it was specified. Then, in order, **.com**, **.exe**, **.bat** and **.cmd** are appended to the end of the specified name and it searches for the longer name. If a directory name was not specified as part of the application name, the following directories are automatically searched in order when attempting to locate the application: 


* The directory from which the Tcl executable was loaded.
* The current directory.
* The Windows NT 32-bit system directory.
* The Windows NT 16-bit system directory.
* The Windows NT home directory.
* The directories listed in the path.


In order to execute shell built-in commands like **dir** and **copy**, the caller must prepend the desired command with “**cmd.exe /c** ” because built-in commands are not implemented using executables.




**Unix** (including Mac OS X)
 The **exec** command is fully functional and works as described. 

 Unix examples
-------------

 Here are some examples of the use of the **exec** command on Unix. To execute a simple program and get its result: 

```
**exec** uname -a
```
 ### Working with non-zero results

 To execute a program that can return a non-zero result, you should wrap the call to **exec** in **[catch](catch.htm)** and check the contents of the **-errorcode** return option if you have an error: 

```
set status 0
if {[catch {**exec** grep foo bar.txt} results options]} {
    set details [dict get $options -errorcode]
    if {[lindex $details 0] eq "CHILDSTATUS"} {
        set status [lindex $details 2]
    } else {
        # Some other error; regenerate it to let caller handle
        return -options $options -level 0 $results
    }
}
```
  This is more easily written using the **[try](try.htm)** command, as that makes it simpler to trap specific types of errors. This is done using code like this: 



```
try {
    set results [**exec** grep foo bar.txt]
    set status 0
} trap CHILDSTATUS {results options} {
    set status [lindex [dict get $options -errorcode] 2]
}
```
 ### Working with quoted arguments

 When translating a command from a Unix shell invocation, care should be taken over the fact that single quote characters have no special significance to Tcl. Thus: 

```
awk '{sum += $1} END {print sum}' numbers.list
```
  would be translated into something like: 



```
**exec** awk {{sum += $1} END {print sum}} numbers.list
```
 ### Working with globbing

 If you are converting invocations involving shell globbing, you should remember that Tcl does not handle globbing or expand things into multiple arguments by default. Instead you should write things like this: 

```
**exec** ls -l {*}[glob *.tcl]
```
 ### Working with user-supplied shell script fragments

 One useful technique can be to expose to users of a script the ability to specify a fragment of shell script to execute that will have some data passed in on standard input that was produced by the Tcl program. This is a common technique for using the *lpr* program for printing. By far the simplest way of doing this is to pass the user's script to the user's shell for processing, as this avoids a lot of complexity with parsing other languages. 

```
set lprScript [*get from user...*]
set postscriptData [*generate somehow...*]

**exec** $env(SHELL) -c $lprScript << $postscriptData
```
 Windows examples
----------------

 Here are some examples of the use of the **exec** command on Windows. To start an instance of *notepad* editing a file without waiting for the user to finish editing the file: 

```
**exec** notepad myfile.txt &
```
  To print a text file using *notepad*: 



```
**exec** notepad /p myfile.txt
```
 ### Working with console programs

 If a program calls other programs, such as is common with compilers, then you may need to resort to batch files to hide the console windows that sometimes pop up: 

```
**exec** cmp.bat somefile.c -o somefile
```
  With the file *cmp.bat* looking something like: 



```
@gcc %1 %2 %3 %4 %5 %6 %7 %8 %9
```
 ### Working with command built-ins

 Sometimes you need to be careful, as different programs may have the same name and be in the path. It can then happen that typing a command at the DOS prompt finds *a different program* than the same command run via **exec**. This is because of the (documented) differences in behaviour between **exec** and DOS batch files.  When in doubt, use the command **[auto\_execok](library.htm)**: it will return the complete path to the program as seen by the **exec** command. This applies especially when you want to run “internal” commands like *dir* from a Tcl script (if you just want to list filenames, use the **[glob](glob.htm)** command.) To do that, use this: 



```
**exec** {*}[auto_execok dir] *.tcl
```
 ### Working with native filenames

 Many programs on Windows require filename arguments to be passed in with backslashes as pathname separators. This is done with the help of the **[file nativename](file.htm)** command. For example, to make a directory (on NTFS) encrypted so that only the current user can access it requires use of the *CIPHER* command, like this: 

```
set secureDir "~/Desktop/Secure Directory"
file mkdir $secureDir
**exec** CIPHER /e /s:[file nativename $secureDir]
```
 See also
--------

 **[error](error.htm)**, **[file](file.htm)**, **[open](open.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2006 Donal K. Fellows. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/exec.htm>

fconfigure
==========

  
[NAME](fconfigure.htm#M2) fconfigure — Set and get options on a channel 
[SYNOPSIS](fconfigure.htm#M3) 
[DESCRIPTION](fconfigure.htm#M4)  
[**-blocking** *boolean*](fconfigure.htm#M5) 
[**-buffering** *newValue*](fconfigure.htm#M6) 
[**-buffersize** *newSize*](fconfigure.htm#M7) 
[**-encoding** *name*](fconfigure.htm#M8) 
[**-eofchar** *char*](fconfigure.htm#M9) 
[**-eofchar** **{***inChar outChar***}**](fconfigure.htm#M10) 
[**-translation** *mode*](fconfigure.htm#M11) 
[**-translation** **{***inMode outMode***}**](fconfigure.htm#M12)  
[**auto**](fconfigure.htm#M13) 
[**binary**](fconfigure.htm#M14) 
[**cr**](fconfigure.htm#M15) 
[**crlf**](fconfigure.htm#M16) 
[**lf**](fconfigure.htm#M17) 




 







 
[STANDARD CHANNELS](fconfigure.htm#M18) 
[EXAMPLES](fconfigure.htm#M19) 
[SEE ALSO](fconfigure.htm#M20) 
[KEYWORDS](fconfigure.htm#M21) 






 Name
----

 fconfigure — Set and get options on a channel Synopsis
--------

 **fconfigure** *channelId*  
 **fconfigure** *channelId* *name*  
 **fconfigure** *channelId* *name value* ?*name value ...*?  
 Description
-----------

 The **fconfigure** command sets and retrieves options for channels.  *ChannelId* identifies the channel for which to set or query an option and must refer to an open channel such as a Tcl standard channel (**[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, or **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**), the return value from an invocation of **[open](open.htm)** or **[socket](socket.htm)**, or the result of a channel creation command provided by a Tcl extension. 


 If no *name* or *value* arguments are supplied, the command returns a list containing alternating option names and values for the channel. If *name* is supplied but no *value* then the command returns the current value of the given option. If one or more pairs of *name* and *value* are supplied, the command sets each of the named options to the corresponding *value*; in this case the return value is an empty string. 


 The options described below are supported for all channels. In addition, each channel type may add options that only it supports. See the manual entry for the command that creates each type of channels for the options that that specific type of channel supports. For example, see the manual entry for the **[socket](socket.htm)** command for additional options for sockets, and the **[open](open.htm)** command for additional options for serial devices. 


 
**-blocking** *boolean*

 The **-blocking** option determines whether I/O operations on the channel can cause the process to block indefinitely. The value of the option must be a proper boolean value. Channels are normally in blocking mode; if a channel is placed into nonblocking mode it will affect the operation of the **[gets](gets.htm)**, **[read](read.htm)**, **[puts](puts.htm)**, **[flush](flush.htm)**, and **[close](close.htm)** commands by allowing them to operate asynchronously; see the documentation for those commands for details. For nonblocking mode to work correctly, the application must be using the Tcl event loop (e.g. by calling **[Tcl\_DoOneEvent](https://www.tcl.tk/man/tcl/TclLib/DoOneEvent.htm)** or invoking the **[vwait](vwait.htm)** command). 


**-buffering** *newValue*

 If *newValue* is **full** then the I/O system will buffer output until its internal buffer is full or until the **[flush](flush.htm)** command is invoked. If *newValue* is **line**, then the I/O system will automatically flush output for the channel whenever a newline character is output. If *newValue* is **none**, the I/O system will flush automatically after every output operation. The default is for **-buffering** to be set to **full** except for channels that connect to terminal-like devices; for these channels the initial setting is **line**. Additionally, **[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** and **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** are initially set to **line**, and **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** is set to **none**. 


**-buffersize** *newSize*

 *Newvalue* must be an integer; its value is used to set the size of buffers, in bytes, subsequently allocated for this channel to store input or output. *Newvalue* must be between one and one million, allowing buffers of one to one million bytes in size. 


**-encoding** *name*

 This option is used to specify the encoding of the channel, so that the data can be converted to and from Unicode for use in Tcl. For instance, in order for Tcl to read characters from a Japanese file in **shiftjis** and properly process and display the contents, the encoding would be set to **shiftjis**. Thereafter, when reading from the channel, the bytes in the Japanese file would be converted to Unicode as they are read. Writing is also supported - as Tcl strings are written to the channel they will automatically be converted to the specified encoding on output.  If a file contains pure binary data (for instance, a JPEG image), the encoding for the channel should be configured to be **[binary](binary.htm)**. Tcl will then assign no interpretation to the data in the file and simply read or write raw bytes. The Tcl **[binary](binary.htm)** command can be used to manipulate this byte-oriented data. It is usually better to set the **-translation** option to **[binary](binary.htm)** when you want to transfer binary data, as this turns off the other automatic interpretations of the bytes in the stream as well. 


The default encoding for newly opened channels is the same platform- and locale-dependent system encoding used for interfacing with the operating system, as returned by **[encoding system](encoding.htm)**. 




**-eofchar** *char*


**-eofchar** **{***inChar outChar***}**

 This option supports DOS file systems that use Control-z (\x1a) as an end of file marker. If *char* is not an empty string, then this character signals end-of-file when it is encountered during input. For output, the end-of-file character is output when the channel is closed. If *char* is the empty string, then there is no special end of file character marker. For read-write channels, a two-element list specifies the end of file marker for input and output, respectively. As a convenience, when setting the end-of-file character for a read-write channel you can specify a single value that will apply to both reading and writing. When querying the end-of-file character of a read-write channel, a two-element list will always be returned. The default value for **-eofchar** is the empty string in all cases except for files under Windows. In that case the **-eofchar** is Control-z (\x1a) for reading and the empty string for writing. The acceptable range for **-eofchar** values is \x01 - \x7f; attempting to set **-eofchar** to a value outside of this range will generate an error. 


**-translation** *mode*


**-translation** **{***inMode outMode***}**

 In Tcl scripts the end of a line is always represented using a single newline character (\n). However, in actual files and devices the end of a line may be represented differently on different platforms, or even for different devices on the same platform. For example, under UNIX newlines are used in files, whereas carriage-return-linefeed sequences are normally used in network connections. On input (i.e., with **[gets](gets.htm)** and **[read](read.htm)**) the Tcl I/O system automatically translates the external end-of-line representation into newline characters. Upon output (i.e., with **[puts](puts.htm)**), the I/O system translates newlines to the external end-of-line representation. The default translation mode, **auto**, handles all the common cases automatically, but the **-translation** option provides explicit control over the end of line translations.  The value associated with **-translation** is a single item for read-only and write-only channels. The value is a two-element list for read-write channels; the read translation mode is the first element of the list, and the write translation mode is the second element. As a convenience, when setting the translation mode for a read-write channel you can specify a single value that will apply to both reading and writing. When querying the translation mode of a read-write channel, a two-element list will always be returned. The following values are currently supported: 


 **auto**
 As the input translation mode, **auto** treats any of newline (**lf**), carriage return (**cr**), or carriage return followed by a newline (**crlf**) as the end of line representation. The end of line representation can even change from line-to-line, and all cases are translated to a newline. As the output translation mode, **auto** chooses a platform specific representation; for sockets on all platforms Tcl chooses **crlf**, for all Unix flavors, it chooses **lf**, and for the various flavors of Windows it chooses **crlf**. The default setting for **-translation** is **auto** for both input and output. 

**binary**
 No end-of-line translations are performed. This is nearly identical to **lf** mode, except that in addition **[binary](binary.htm)** mode also sets the end-of-file character to the empty string (which disables it) and sets the encoding to **[binary](binary.htm)** (which disables encoding filtering). See the description of **-eofchar** and **-encoding** for more information.  Internally, i.e. when it comes to the actual behaviour of the translator this value **is** identical to **lf** and is therefore reported as such when queried. Even if **[binary](binary.htm)** was used to set the translation. 



**cr**
 The end of a line in the underlying file or device is represented by a single carriage return character. As the input translation mode, **cr** mode converts carriage returns to newline characters. As the output translation mode, **cr** mode translates newline characters to carriage returns. 

**crlf**
 The end of a line in the underlying file or device is represented by a carriage return character followed by a linefeed character. As the input translation mode, **crlf** mode converts carriage-return-linefeed sequences to newline characters. As the output translation mode, **crlf** mode translates newline characters to carriage-return-linefeed sequences. This mode is typically used on Windows platforms and for network connections. 

**lf**
 The end of a line in the underlying file or device is represented by a single newline (linefeed) character. In this mode no translations occur during either input or output. This mode is typically used on UNIX platforms. 




Standard channels
-----------------

 The Tcl standard channels (**[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, and **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**) can be configured through this command like every other channel opened by the Tcl library. Beyond the standard options described above they will also support any special option according to their current type. If, for example, a Tcl application is started by the **inet** super-server common on Unix system its Tcl standard channels will be sockets and thus support the socket options. Examples
--------

 Instruct Tcl to always send output to **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** immediately, whether or not it is to a terminal: 

```
**fconfigure** stdout -buffering none
```
  Open a socket and read lines from it without ever blocking the processing of other events: 



```
set s [socket some.where.com 12345]
**fconfigure** $s -blocking 0
fileevent $s readable "readMe $s"
proc readMe chan {
    if {[gets $chan line] < 0} {
        if {[eof $chan]} {
            close $chan
            return
        }
        # Could not read a complete line this time; Tcl's
        # internal buffering will hold the partial line for us
        # until some more data is available over the socket.
    } else {
        puts stdout $line
    }
}
```
  Read a PPM-format image from a file: 



```
# Open the file and put it into Unix ASCII mode
set f [open teapot.ppm]
**fconfigure** $f -encoding ascii -translation lf

# Get the header
if {[gets $f] ne "P6"} {
    error "not a raw-bits PPM"
}

# Read lines until we have got non-comment lines
# that supply us with three decimal values.
set words {}
while {[llength $words] < 3} {
    gets $f line
    if {[string match "#*" $line]} continue
    lappend words {*}[join [scan $line %d%d%d]]
}

# Those words supply the size of the image and its
# overall depth per channel. Assign to variables.
lassign $words xSize ySize depth

# Now switch to binary mode to pull in the data,
# one byte per channel (red,green,blue) per pixel.
**fconfigure** $f -translation binary
set numDataBytes [expr {3 * $xSize * $ySize}]
set data [read $f $numDataBytes]

close $f
```
 See also
--------

 **[close](close.htm)**, **[flush](flush.htm)**, **[gets](gets.htm)**, **[open](open.htm)**, **[puts](puts.htm)**, **[read](read.htm)**, **[socket](socket.htm)**, **[Tcl\_StandardChannels](https://www.tcl.tk/man/tcl/TclLib/StdChannels.htm)** Copyright © 1995-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/fconfigure.htm>

find
====

 Name
----

 itcl::find — search for classes and objects Synopsis
--------

 **[itcl::find](find.htm)** *option* ?*arg arg ...*?  
 Description
-----------

 The **find** command is used to find classes and objects that are available in the current interpreter. Classes and objects are reported first in the active namespace, then in all other namespaces in the interpreter.  The *option* argument determines what action is carried out by the command. The legal *options* (which may be abbreviated) are: 


 
**find classes ?***pattern*?
 Returns a list of [incr Tcl] classes. Classes in the current namespace are listed first, followed by classes in all other namespaces in the interpreter. If the optional *pattern* is specified, then the reported names are compared using the rules of the "**[string match](../tclcmd/string.htm)**" command, and only matching names are reported.  If a class resides in the current namespace context, this command reports its simple name--without any qualifiers. However, if the *pattern* contains **::** qualifiers, or if the class resides in another context, this command reports its fully-qualified name. Therefore, you can use the following command to obtain a list where all names are fully-qualified: 



```
itcl::find classes ::*
```



**find objects ?***pattern*? ?**-class** *className*? ?**-isa** *className*?
 Returns a list of [incr Tcl] objects. Objects in the current namespace are listed first, followed by objects in all other namespaces in the interpreter. If the optional *pattern* is specified, then the reported names are compared using the rules of the "**[string match](../tclcmd/string.htm)**" command, and only matching names are reported. If the optional "**-class**" parameter is specified, this list is restricted to objects whose most-specific class is *className*. If the optional "**-isa**" parameter is specified, this list is further restricted to objects having the given *className* anywhere in their heritage.  If an object resides in the current namespace context, this command reports its simple name--without any qualifiers. However, if the *pattern* contains **::** qualifiers, or if the object resides in another context, this command reports its fully-qualified name. Therefore, you can use the following command to obtain a list where all names are fully-qualified: 



```
itcl::find objects ::*
```


 Copyright © 1993-1998 Lucent Technologies, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/find.htm>

tdbc\_sqlite3
=============

 Name
----

 tdbc::sqlite3 — TDBC driver for the SQLite3 database manager Synopsis
--------

 package require **tdbc::sqlite3 1.0**  
 **tdbc::sqlite3::connection create** *db* *fileName* ?*-option value...*?  
 Description
-----------

 The **tdbc::sqlite3** driver provides a database interface that conforms to Tcl DataBase Connectivity (TDBC) and allows a Tcl script to connect to a SQLite3 database. It is also provided as a worked example of how to write a database driver in Tcl, so that driver authors have a starting point for further development.  Connection to a SQLite3 database is established by invoking **tdbc::sqlite3::connection create**, passing it a string to be used as the connection handle followed by the file name of the database. The side effect of **tdbc::sqlite3::connection create** is to create a new database connection.. As an alternative, **tdbc::sqlite::connection new** may be used to create a database connection with an automatically assigned name. The return value from **tdbc::sqlite::connection new** is the name that was chosen for the connection handle. See **tdbc::connection(n)** for the details of how to use the connection to manipulate a database. 


Configuration options
---------------------

 The standard configuration options **-encoding**, **-isolation**, **-readonly** and **-timeout** are all recognized, both on **tdbc::sqlite3::connection create** and on the **configure** method of the resulting connection.  Since the encoding of a SQLite3 database is always well known, the **-encoding** option accepts only **utf-8** as an encoding and always returns **utf-8** for an encoding. The actual encoding may be set using a SQLite3 **PRAGMA** statement when creating a new database. 


 Only the isolation levels **readuncommitted** and **serializable** are implemented. Other isolation levels are promoted to **serializable**. 


 The **-readonly** flag is not implemented. **-readonly 0** is accepted silently, while **-readonly 1** reports an error. 


Bugs
----

 If any column name is not unique among the columns in a result set, the results of **-as dicts** returns will be missing all but the rightmost of the duplicated columns. This limitation can be worked around by adding appropriate **AS** clauses to **SELECT** statements to ensure that all returned column names are unique. Plans are to fix this bug by using a C implementation of the driver, which will also improve performance significantly. See also
--------

 **[tdbc](../tdbccmd/tdbc.htm)**, **[tdbc::connection](../tdbccmd/tdbc_connection.htm)**, **[tdbc::resultset](../tdbccmd/tdbc_resultset.htm)**, **[tdbc::statement](../tdbccmd/tdbc_statement.htm)** Copyright
---------

 Copyright (c) 2008 by Kevin B. Kenny. 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcsqliteCmd/tdbc_sqlite3.htm>

class
=====

  
[NAME](class.htm#M2) itcl::class — create a class of objects 
[SYNOPSIS](class.htm#M3) 
[DESCRIPTION](class.htm#M4) 
[CLASS DEFINITIONS](class.htm#M5)  
[**class** *className definition*](class.htm#M6) 
  
[**inherit** *baseClass* ?*baseClass*...?](class.htm#M7) 
[**constructor** *args* ?*init*? *body*](class.htm#M8) 
[**destructor** *body*](class.htm#M9) 
[**method** *name* ?*args*? ?*body*?](class.htm#M10) 
[**proc** *name* ?*args*? ?*body*?](class.htm#M11) 
[**variable** *varName* ?*init*? ?*config*?](class.htm#M12) 
[**common** *varName* ?*init*?](class.htm#M13) 
[**public** *command* ?*arg arg ...*?](class.htm#M14) 
[**protected** *command* ?*arg arg ...*?](class.htm#M15) 
[**private** *command* ?*arg arg ...*?](class.htm#M16) 









 
[CLASS USAGE](class.htm#M17)  
[*className objName* ?*args...*?](class.htm#M18) 
 
[OBJECT USAGE](class.htm#M19)  
[*objName method* ?*args...*?](class.htm#M20) 
 
[BUILT-IN METHODS](class.htm#M21)  
[*objName* **cget option**](class.htm#M22) 
[*objName* **configure** ?*option*? ?*value option value ...*?](class.htm#M23) 
[*objName* **isa** *className*](class.htm#M24) 
[*objName* **info** *option* ?*args...*?](class.htm#M25)  
[*objName* **info class**](class.htm#M26) 
[*objName* **info inherit**](class.htm#M27) 
[*objName* **info heritage**](class.htm#M28) 
[*objName* **info function** ?*cmdName*? ?**-protection**? ?**-type**? ?**-name**? ?**-args**? ?**-body**?](class.htm#M29) 
[*objName* **info variable** ?*varName*? ?**-protection**? ?**-type**? ?**-name**? ?**-init**? ?**-value**? ?**-config**?](class.htm#M30) 




 



 
[CHAINING METHODS/PROCS](class.htm#M31) 
[AUTO-LOADING](class.htm#M32) 
[C PROCEDURES](class.htm#M33) 
[KEYWORDS](class.htm#M34) 










 Name
----

 itcl::class — create a class of objects Synopsis
--------

 **itcl::class** *className* **{**  
 **inherit** *baseClass* ?*baseClass*...?  
 **constructor** *args* ?*init*? *body*  
 **destructor** *body*  
 **method** *name* ?*args*? ?*body*?  
 **proc** *name* ?*args*? ?*body*?  
 **variable** *varName* ?*init*? ?*config*?  
 **common** *varName* ?*init*?  
   
 **public** *command* ?*arg arg ...*?  
 **protected** *command* ?*arg arg ...*?  
 **private** *command* ?*arg arg ...*?  
   
 **set** *varName* ?*value*?  
 **[array](../tclcmd/array.htm)** *option* ?*arg arg ...*?  
 **}**  
   
 *className objName* ?*arg arg ...*?  
   
 *objName method* ?*arg arg ...*?  
   
 *className::proc* ?*arg arg ...*?  
 Description
-----------

 The fundamental construct in **[incr Tcl]** is the class definition. Each class acts as a template for actual objects that can be created. The class itself is a namespace which contains things common to all objects. Each object has its own unique bundle of data which contains instances of the "variables" defined in the class definition. Each object also has a built-in variable named "this", which contains the name of the object. Classes can also have "common" data members that are shared by all objects in a class.  Two types of functions can be included in the class definition. "Methods" are functions which operate on a specific object, and therefore have access to both "variables" and "common" data members. "Procs" are ordinary procedures in the class namespace, and only have access to "common" data members. 


 If the body of any method or proc starts with "**@**", it is treated as the symbolic name for a C procedure. Otherwise, it is treated as a Tcl code script. See below for details on registering and using C procedures. 


 A class can only be defined once, although the bodies of class methods and procs can be defined again and again for interactive debugging. See the **body** and **configbody** commands for details. 


 Each namespace can have its own collection of objects and classes. The list of classes available in the current context can be queried using the "**[itcl::find classes](find.htm)**" command, and the list of objects, with the "**[itcl::find objects](find.htm)**" command. 


 A class can be deleted using the "**delete class**" command. Individual objects can be deleted using the "**delete object**" command. 


Class definitions
-----------------

  
**class** *className definition*

 Provides the definition for a class named *className*. If the class *className* already exists, or if a command called *className* exists in the current namespace context, this command returns an error. If the class definition is successfully parsed, *className* becomes a command in the current context, handling the creation of objects for this class. 

  The class *definition* is evaluated as a series of Tcl statements that define elements within the class. The following class definition commands are recognized: 


 
**inherit** *baseClass* ?*baseClass*...?
 Causes the current class to inherit characteristics from one or more base classes. Classes must have been defined by a previous **class** command, or must be available to the auto-loading facility (see "AUTO-LOADING" below). A single class definition can contain no more than one **inherit** command.  The order of *baseClass* names in the **inherit** list affects the name resolution for class members. When the same member name appears in two or more base classes, the base class that appears first in the **inherit** list takes precedence. For example, if classes "Foo" and "Bar" both contain the member "x", and if another class has the "**inherit**" statement: 



```
inherit Foo Bar
```
 then the name "x" means "Foo::x". Other inherited members named "x" must be referenced with their explicit name, like "Bar::x". 




**constructor** *args* ?*init*? *body*

 Declares the *args* argument list and *body* used for the constructor, which is automatically invoked whenever an object is created.  Before the *body* is executed, the optional *init* statement is used to invoke any base class constructors that require arguments. Variables in the *args* specification can be accessed in the *init* code fragment, and passed to base class constructors. After evaluating the *init* statement, any base class constructors that have not been executed are invoked automatically without arguments. This ensures that all base classes are fully constructed before the constructor *body* is executed. By default, this scheme causes constructors to be invoked in order from least- to most-specific. This is exactly the opposite of the order that classes are reported by the **[info heritage](../tclcmd/info.htm)** command. 


If construction is successful, the constructor always returns the object name-regardless of how the *body* is defined-and the object name becomes a command in the current namespace context. If construction fails, an error message is returned. 




**destructor** *body*

 Declares the *body* used for the destructor, which is automatically invoked when an object is deleted. If the destructor is successful, the object data is destroyed and the object name is removed as a command from the interpreter. If destruction fails, an error message is returned and the object remains.  When an object is destroyed, all destructors in its class hierarchy are invoked in order from most- to least-specific. This is the order that the classes are reported by the "**[info heritage](../tclcmd/info.htm)**" command, and it is exactly the opposite of the default constructor order. 




**method** *name* ?*args*? ?*body*?
 Declares a method called *name*. When the method *body* is executed, it will have automatic access to object-specific variables and common data members.  If the *args* list is specified, it establishes the usage information for this method. The **body** command can be used to redefine the method body, but the *args* list must match this specification. 


Within the body of another class method, a method can be invoked like any other command-simply by using its name. Outside of the class context, the method name must be prefaced an object name, which provides the context for the data that it manipulates. Methods in a base class that are redefined in the current class, or hidden by another base class, can be qualified using the "*className*::*method*" syntax. 




**proc** *name* ?*args*? ?*body*?
 Declares a proc called *name*. A proc is an ordinary procedure within the class namespace. Unlike a method, a proc is invoked without referring to a specific object. When the proc *body* is executed, it will have automatic access only to common data members.  If the *args* list is specified, it establishes the usage information for this proc. The **body** command can be used to redefine the proc body, but the *args* list must match this specification. 


Within the body of another class method or proc, a proc can be invoked like any other command-simply by using its name. In any other namespace context, the proc is invoked using a qualified name like "*className***::***proc*". Procs in a base class that are redefined in the current class, or hidden by another base class, can also be accessed via their qualified name. 




**variable** *varName* ?*init*? ?*config*?
 Defines an object-specific variable named *varName*. All object-specific variables are automatically available in class methods. They need not be declared with anything like the **[global](../tclcmd/global.htm)** command.  If the optional *init* string is specified, it is used as the initial value of the variable when a new object is created. Initialization forces the variable to be a simple scalar value; uninitialized variables, on the other hand, can be set within the constructor and used as arrays. 


The optional *config* script is only allowed for public variables. If specified, this code fragment is executed whenever a public variable is modified by the built-in "configure" method. The *config* script can also be specified outside of the class definition using the **configbody** command. 




**common** *varName* ?*init*?
 Declares a common variable named *varName*. Common variables reside in the class namespace and are shared by all objects belonging to the class. They are just like global variables, except that they need not be declared with the usual **[global](../tclcmd/global.htm)** command. They are automatically visible in all class methods and procs.  If the optional *init* string is specified, it is used as the initial value of the variable. Initialization forces the variable to be a simple scalar value; uninitialized variables, on the other hand, can be set with subsequent **[set](../tclcmd/set.htm)** and **[array](../tclcmd/array.htm)** commands and used as arrays. 


 Once a common data member has been defined, it can be set using **[set](../tclcmd/set.htm)** and **[array](../tclcmd/array.htm)** commands within the class definition. This allows common data members to be initialized as arrays. For example: 



```
itcl::class Foo {
    common boolean
    set boolean(true) 1
    set boolean(false) 0
}
```
 Note that if common data members are initialized within the constructor, they get initialized again and again whenever new objects are created. 




**public** *command* ?*arg arg ...*?

**protected** *command* ?*arg arg ...*?

**private** *command* ?*arg arg ...*?
 These commands are used to set the protection level for class members that are created when *command* is evaluated. The *command* is usually **method**, **[proc](../tclcmd/proc.htm)**, **[variable](../tclcmd/variable.htm)** or**common**, and the remaining *arg*'s complete the member definition. However, *command* can also be a script containing many different member definitions, and the protection level will apply to all of the members that are created. 

 Class usage
-----------

 Once a class has been defined, the class name can be used as a command to create new objects belonging to the class. 
 
*className objName* ?*args...*?
 Creates a new object in class *className* with the name *objName*. Remaining arguments are passed to the constructor of the most-specific class. This in turn passes arguments to base class constructors before invoking its own body of commands. If construction is successful, a command called *objName* is created in the current namespace context, and *objName* is returned as the result of this operation. If an error is encountered during construction, the destructors are automatically invoked to free any resources that have been allocated, the object is deleted, and an error is returned.  If *objName* contains the string "**#auto**", that string is replaced with an automatically generated name. Names have the form *className<number>*, where the *className* part is modified to start with a lowercase letter. In class "Toaster", for example, the "**#auto**" specification would produce names like toaster0, toaster1, etc. Note that "**#auto**" can be also be buried within an object name: 



```
fileselectiondialog .foo.bar.#auto -background red
```
 This would generate an object named ".foo.bar.fileselectiondialog0". 



 Object usage
------------

 Once an object has been created, the object name can be used as a command to invoke methods that operate on the object. 
 
*objName method* ?*args...*?
 Invokes a method named *method* on an object named *objName*. Remaining arguments are passed to the argument list for the method. The method name can be "constructor", "destructor", any method name appearing in the class definition, or any of the following built-in methods. 

 Built-in methods
----------------

  
*objName* **cget option**

 Provides access to public variables as configuration options. This mimics the behavior of the usual "cget" operation for Tk widgets. The *option* argument is a string of the form "**-***varName*", and this method returns the current value of the public variable *varName*. 


*objName* **configure** ?*option*? ?*value option value ...*?
 Provides access to public variables as configuration options. This mimics the behavior of the usual "configure" operation for Tk widgets. With no arguments, this method returns a list of lists describing all of the public variables. Each list has three elements: the variable name, its initial value and its current value.  If a single *option* of the form "**-***varName*" is specified, then this method returns the information for that one variable. 


Otherwise, the arguments are treated as *option*/*value* pairs assigning new values to public variables. Each variable is assigned its new value, and if it has any "config" code associated with it, it is executed in the context of the class where it was defined. If the "config" code generates an error, the variable is set back to its previous value, and the **configure** method returns an error. 




*objName* **isa** *className*

 Returns non-zero if the given *className* can be found in the object's heritage, and zero otherwise. 


*objName* **info** *option* ?*args...*?
 Returns information related to a particular object named *objName*, or to its class definition. The *option* parameter includes the following things, as well as the options recognized by the usual Tcl "info" command: 
 
*objName* **info class**

 Returns the name of the most-specific class for object *objName*. 


*objName* **info inherit**

 Returns the list of base classes as they were defined in the "**inherit**" command, or an empty string if this class has no base classes. 


*objName* **info heritage**

 Returns the current class name and the entire list of base classes in the order that they are traversed for member lookup and object destruction. 


*objName* **info function** ?*cmdName*? ?**-protection**? ?**-type**? ?**-name**? ?**-args**? ?**-body**?
 With no arguments, this command returns a list of all class methods and procs. If *cmdName* is specified, it returns information for a specific method or proc. If no flags are specified, this command returns a list with the following elements: the protection level, the type (method/proc), the qualified name, the argument list and the body. Flags can be used to request specific elements from this list. 


*objName* **info variable** ?*varName*? ?**-protection**? ?**-type**? ?**-name**? ?**-init**? ?**-value**? ?**-config**?
 With no arguments, this command returns a list of all object-specific variables and common data members. If *varName* is specified, it returns information for a specific data member. If no flags are specified, this command returns a list with the following elements: the protection level, the type (variable/common), the qualified name, the initial value, and the current value. If *varName* is a public variable, the "config" code is included on this list. Flags can be used to request specific elements from this list. 



 Chaining methods/procs
----------------------

 Sometimes a base class has a method or proc that is redefined with the same name in a derived class. This is a way of making the derived class handle the same operations as the base class, but with its own specialized behavior. For example, suppose we have a Toaster class that looks like this: 

```
itcl::class Toaster {
    variable crumbs 0
    method toast {nslices} {
        if {$crumbs > 50} {
            error "== FIRE! FIRE! =="
        }
        set crumbs [expr $crumbs+4*$nslices]
    }
    method clean {} {
        set crumbs 0
    }
}
```
  We might create another class like SmartToaster that redefines the "toast" method. If we want to access the base class method, we can qualify it with the base class name, to avoid ambiguity: 



```
itcl::class SmartToaster {
    inherit Toaster
    method toast {nslices} {
        if {$crumbs > 40} {
            clean
        }
        return [Toaster::toast $nslices]
    }
}
```
  Instead of hard-coding the base class name, we can use the "chain" command like this: 



```
itcl::class SmartToaster {
    inherit Toaster
    method toast {nslices} {
        if {$crumbs > 40} {
            clean
        }
        return [chain $nslices]
    }
}
```
  The chain command searches through the class hierarchy for a slightly more generic (base class) implementation of a method or proc, and invokes it with the specified arguments. It starts at the current class context and searches through base classes in the order that they are reported by the "info heritage" command. If another implementation is not found, this command does nothing and returns the null string. 


Auto-loading
------------

 Class definitions need not be loaded explicitly; they can be loaded as needed by the usual Tcl auto-loading facility. Each directory containing class definition files should have an accompanying "tclIndex" file. Each line in this file identifies a Tcl procedure or **[incr Tcl]** class definition and the file where the definition can be found.  For example, suppose a directory contains the definitions for classes "Toaster" and "SmartToaster". Then the "tclIndex" file for this directory would look like: 



```
# Tcl autoload index file, version 2.0 for [incr Tcl]
# This file is generated by the "auto_mkindex" command
# and sourced to set up indexing information for one or
# more commands.  Typically each line is a command that
# sets an element in the auto_index array, where the
# element name is the name of a command and the value is
# a script that loads the command.

set auto_index(::Toaster) "source $dir/Toaster.itcl"
set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"
```
  The **[auto\_mkindex](../tclcmd/library.htm)** command is used to automatically generate "tclIndex" files. 


 The auto-loader must be made aware of this directory by appending the directory name to the "auto\_path" variable. When this is in place, classes will be auto-loaded as needed when used in an application. 


C procedures
------------

 C procedures can be integrated into an **[incr Tcl]** class definition to implement methods, procs, and the "config" code for public variables. Any body that starts with "**@**" is treated as the symbolic name for a C procedure.  Symbolic names are established by registering procedures via **[Itcl\_RegisterC()](https://www.tcl.tk/man/tcl/ItclLib/RegisterC.htm)**. This is usually done in the **[Tcl\_AppInit()](https://www.tcl.tk/man/tcl/TclLib/AppInit.htm)** procedure, which is automatically called when the interpreter starts up. In the following example, the procedure My\_FooCmd() is registered with the symbolic name "foo". This procedure can be referenced in the **body** command as "@foo". 



```
int
[Tcl\_AppInit](https://www.tcl.tk/man/tcl/TclLib/AppInit.htm)(interp)
    [Tcl\_Interp](https://www.tcl.tk/man/tcl/TclLib/Interp.htm) *interp;     /* Interpreter for application. */
{
    if (Itcl_Init(interp) == TCL_ERROR) {
        return TCL_ERROR;
    }

    if ([Itcl\_RegisterC](https://www.tcl.tk/man/tcl/ItclLib/RegisterC.htm)(interp, "foo", My_FooCmd) != TCL_OK) {
        return TCL_ERROR;
    }
}
```
  C procedures are implemented just like ordinary Tcl commands. See the **CrtCommand** man page for details. Within the procedure, class data members can be accessed like ordinary variables using **[Tcl\_SetVar()](https://www.tcl.tk/man/tcl/TclLib/SetVar.htm)**, **[Tcl\_GetVar()](https://www.tcl.tk/man/tcl/TclLib/SetVar.htm)**, **[Tcl\_TraceVar()](https://www.tcl.tk/man/tcl/TclLib/TraceVar.htm)**, etc. Class methods and procs can be executed like ordinary commands using **[Tcl\_Eval()](https://www.tcl.tk/man/tcl/TclLib/Eval.htm)**. **[incr Tcl]** makes this possible by automatically setting up the context before executing the C procedure. 


 This scheme provides a natural migration path for code development. Classes can be developed quickly using Tcl code to implement the bodies. An entire application can be built and tested. When necessary, individual bodies can be implemented with C code to improve performance. 

 Copyright © 1993-1998 Lucent Technologies, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ItclCmd/class.htm>

tdbc\_statement
===============

  
[NAME](tdbc_statement.htm#M2) tdbc::statement — TDBC statement object 
[SYNOPSIS](tdbc_statement.htm#M3) 
[DESCRIPTION](tdbc_statement.htm#M4)  
[**direction**](tdbc_statement.htm#M5) 
[**type**](tdbc_statement.htm#M6) 
[**precision**](tdbc_statement.htm#M7) 
[**scale**](tdbc_statement.htm#M8) 
[**nullable**](tdbc_statement.htm#M9) 




 
[EXAMPLES](tdbc_statement.htm#M10) 
[SEE ALSO](tdbc_statement.htm#M11) 
[KEYWORDS](tdbc_statement.htm#M12) 
[COPYRIGHT](tdbc_statement.htm#M13) 






 Name
----

 tdbc::statement — TDBC statement object Synopsis
--------

 package require **tdbc 1.0**  
 package require **tdbc::***driver version*  
   
 **tdbc::***driver***::connection create** *db* *?-option value*...?  
   
 **[set](../tclcmd/set.htm)** *stmt* **[***db* **prepare** *sql-code***]**  
 **[set](../tclcmd/set.htm)** *stmt* **[***db* **preparecall** *call***]**  
   
 *$stmt* **params**  
 *$stmt* **paramtype** ?*direction*? *type* ?*precision*? ?*scale*?  
 *$stmt* **execute** ?*dict*?  
 *$stmt* **resultsets**  
 *$stmt* **allrows** ?**-as lists|dicts**? ?**-columnsvariable** *name*? ?**--**? ?*dict*  
 *$stmt* **[foreach](../tclcmd/foreach.htm)** ?**-as lists|dicts**? ?**-columnsvariable** *name*? ?**--**? *varName* ?*dict*? *script*  
 *$stmt* **[close](../tclcmd/close.htm)**  
 Description
-----------

 Every database driver for TDBC (Tcl DataBase Connectivity) implements a *statement* object that represents a SQL statement in a database. Instances of this object are created by executing the **prepare** or **preparecall** object command on a database connection.  The **prepare** object command against the connection accepts arbitrary SQL code to be executed against the database. The SQL code may contain *bound variables*, which are strings of alphanumeric characters or underscores (the first character of the string may not be numeric), prefixed with a colon (**:**). If a bound variable appears in the SQL statement, and is not in a string set off by single or double quotes, nor in a comment introduced by **--**, it becomes a value that is substituted when the statement is executed. A bound variable becomes a single value (string or numeric) in the resulting statement. *Drivers are responsible for ensuring that the mechanism for binding variables prevents SQL injection.* 


 The **preparecall** object command against the connection accepts a stylized statement in the form: 



```
*procname* **(**?**:***varname*? ?**,:***varname*...?**)**
```
  or 



```
*varname* **=** *procname* **(**?**:***varname*? ?**,:***varname*...?**)**
```
  This statement represents a call to a stored procedure *procname* in the database. The variable name to the left of the equal sign (if present), and all variable names that are parameters inside parentheses, become bound variables. 


 The **params** method against a statement object enumerates the bound variables that appear in the statement. The result returned from the **params** method is a dictionary whose keys are the names of bound variables (listed in the order in which the variables first appear in the statement), and whose values are dictionaries. The subdictionaries include at least the following keys (database drivers may add additional keys that are not in this list). 


 **direction**
 Contains one of the keywords, **in**, **out** or **inout** according to whether the variable is an input to or output from the statement. Only stored procedure calls will have **out** or **inout** parameters. 

**type**
 Contains the data type of the column, and will generally be chosen from the set, **bigint**, **[binary](../tclcmd/binary.htm)**, **bit**, **char**, **date**, **decimal**, **double**, **float**, **integer**, **longvarbinary**, **longvarchar**, **numeric**, **real**, **[time](../tclcmd/time.htm)**, **timestamp**, **smallint**, **tinyint**, **varbinary**, and **varchar**. (If the variable has a type that cannot be represented as one of the above, **type** will contain a driver-dependent description of the type.) 

**precision**
 Contains the precision of the column in bits, decimal digits, or the width in characters, according to the type. 

**scale**
 Contains the scale of the column (the number of digits after the radix point), for types that support the concept. 

**nullable**
 Contains 1 if the column can contain NULL values, and 0 otherwise. 

  The **paramtype** object command allows the script to specify the type and direction of parameter transmission of a variable in a statement. (Some databases provide no method to determine this information automatically and place the burden on the caller to do so.) The *direction*, *type*, *precision*, *scale*, and *nullable* arguments have the same meaning as the corresponding dictionary values in the **params** object command. 


 The **execute** object command executes the statement. Prior to executing the statement, values are provided for the bound variables that appear in it. If the *dict* parameter is supplied, it is searched for a key whose name matches the name of the bound variable. If the key is present, its value becomes the substituted variable. If not, the value of the substituted variable becomes a SQL NULL. If the *dict* parameter is *not* supplied, the **execute** object command searches for a variable in the caller's scope whose name matches the name of the bound variable. If one is found, its value becomes the bound variable's value. If none is found, the bound variable is assigned a SQL NULL as its value. Once substitution is finished, the resulting statement is executed. The return value is a result set object (see **[tdbc::resultset](tdbc_resultset.htm)** for details). 


 The **resultsets** method returns a list of all the result sets that have been returned by executing the statement and have not yet been closed. 


 The **allrows** object command executes the statement as with the **execute** object command, accepting an optional *dict* parameter giving bind variables. After executing the statement, it uses the *allrows* object command on the result set (see **[tdbc::resultset](tdbc_resultset.htm)**) to construct a list of the results. Finally, the result set is closed. The return value is the list of results. 


 The **[foreach](../tclcmd/foreach.htm)** object command executes the statement as with the **execute** object command, accepting an optional *dict* parameter giving bind variables. After executing the statement, it uses the *foreach* object command on the result set (see **[tdbc::resultset](tdbc_resultset.htm)**) to evaluate the given *script* for each row of the results. Finally, the result set is closed, even if the given *script* results in a **[return](../tclcmd/return.htm)**, an error, or an unusual return code. 


 The **[close](../tclcmd/close.htm)** object command removes a statement and any result sets that it has created. All system resources associated with the objects are freed. 


Examples
--------

 The following code would look up a telephone number in a directory, assuming an appropriate SQL schema: 

```
package require tdbc::sqlite3
tdbc::sqlite3::connection create db phonebook.sqlite3
set statement [db prepare {
    select phone_num from directory
    where first_name = :firstname and last_name = :lastname
}]
set firstname Fred
set lastname Flintstone
$statement foreach row {
    puts [dict get $row phone_num]
}
$statement close
db close
```
 See also
--------

 **[encoding](../tclcmd/encoding.htm)**, **[tdbc](tdbc.htm)**, **[tdbc::connection](tdbc_connection.htm)**, **[tdbc::resultset](tdbc_resultset.htm)**, **[tdbc::tokenize](tdbc_tokenize.htm)** Copyright
---------

 Copyright (c) 2008 by Kevin B. Kenny. Copyright © 2008 by Kevin B. Kenny. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcCmd/tdbc_statement.htm>

tdbc\_resultset
===============

 Name
----

 tdbc::resultset — TDBC result set object Synopsis
--------

 package require **tdbc 1.0**  
 package require **tdbc::***driver version*  
   
 **tdbc::***driver***::connection create** *db* *?-option value*...?  
   
 **[set](../tclcmd/set.htm)** *stmt* **[***db* **prepare** *sql-code***]**  
 **[set](../tclcmd/set.htm)** *resultset* **[***$stmt* **execute** ?*args...*?**]**  
   
 *$resultset* **columns**  
 *$resultset* **rowcount**  
 *$resultset* **nextrow** ?**-as** **lists**|**dicts**? ?**--**? *varname*  
 *$resultset* **nextlist** *varname*  
 *$resultset* **nextdict** *varname*  
 *$resultset* **nextresults**  
 *$resultset* **allrows** ?**-as lists|dicts**? ?**-columnsvariable** *name*? ?**--**?  
 *$resultset* **[foreach](../tclcmd/foreach.htm)** ?**-as lists|dicts**? ?**-columnsvariable** *name*? ?**--**? *varname* *script*  
 *$resultset* **[close](../tclcmd/close.htm)**  
 Description
-----------

 Every database driver for TDBC (Tcl DataBase Connectivity) implements a *result set* object that represents a the results returned from executing SQL statement in a database. Instances of this object are created by executing the **execute** object command on a statement object.  The **columns** obect command returns a list of the names of the columns in the result set. The columns will appear in the same order as they appeared in the SQL statement that performed the database query. If the SQL statement does not return a set of columns (for instance, if it is an INSERT, UPDATE, or DELETE statement), the **columns** command will return an empty list. 


 The **rowcount** object command returns the number of rows in the database that were affected by the execution of an INSERT, UPDATE or DELETE statement. For a SELECT statement, the row count is unspecified. 


 The **nextlist** object command sets the variable given by *varname* in the caller's scope to the next row of the results, expressed as a list of column values. NULL values are replaced by empty strings. The columns of the result row appear in the same order in which they appeared on the SELECT statement. The return of **nextlist** is **1** if the operation succeeded, and **0** if the end of the result set was reached. 


 The **nextdict** object command sets the variable given by *varname* in the caller's scope to the next row of the results, expressed as a dictionary. The dictionary's keys are column names, and the values are the values of those columns in the row. If a column's value in the row is NULL, its key is omitted from the dictionary. The keys appear in the dictionary in the same order in which the columns appeared on the SELECT statement. The return of **nextdict** is **1** if the operation succeeded, and **0** if the end of the result set was reached. 


 The **nextrow** object command is precisely equivalent to the **nextdict** or **nextlist** object command, depending on whether **-as dicts** (the default) or **-as lists** is specified. 


 Some databases support the idea of a single statement that returns multiple sets of results. The **nextresults** object command is executed, typically after the **nextlist** of **nextdict** object command has returned **0**, to advance to the next result set. It returns **1** if there is another result set to process, and **0** if the result set just processed was the last. After calling **nextresults** and getting the return value of **1**, the caller may once again call **columns** to get the column descriptions of the next result set, and then return to calling **nextdict** or **nextlist** to process the rows of the next result set. It is an error to call **columns**, **nextdict**, **nextlist** or **nextrow** after **nextresults** has returned **0**. 


 The **allrows** object command sets the variable designated by the **-columnsvariable** option (if present) to the result of the **columns** object command. It then executes the **nextrow** object command repeatedly until the end of the result set is reached. If **nextresults** returns a nonzero value, it executes the above two steps (**columns** followed by iterated **nextrow** calls) as long as further results are available. The rows returned by **nextrow** are assembled into a Tcl list and become the return value of the **allrows** command; the last value returned from **columns** is what the application will see in **-columnsvariable**. 


 The **[foreach](../tclcmd/foreach.htm)** object command sets the variable designated by the **-columnsvariable** option (if present) to the result of the **columns** object command. It then executes the **nextrow** object command repeatedly until the end of the result set is reached, storing the successive rows in the variable designated by *varName*. For each row, it executes the given *script*. If the script terminates with an error, the error is reported by the **[foreach](../tclcmd/foreach.htm)** command, and iteration stops. If the script performs a **[break](../tclcmd/break.htm)** operation, the iteration terminates prematurely. If the script performs a **[continue](../tclcmd/continue.htm)** operation, the iteration recommences with the next row. If the script performs a **[return](../tclcmd/return.htm)**, results are the same as if a script outside the control of **[foreach](../tclcmd/foreach.htm)** had returned. Any other unusual return code terminates the iteration and is reported from the **[foreach](../tclcmd/foreach.htm)**. 


 Once **nextrow** returns **0**, the **[foreach](../tclcmd/foreach.htm)** object command tries to advance to the next result set using **nextresults**. If **nextresults** returns **1**, the above steps (**columns** and **nextrow**, with script invocation) are repeated as long as more result sets remain. The *script* will always see the correct description of the columns of the current result set in the variable designated byt **-columnsvariable**. At the end of the call, the variable designated by **-columnsvariable** will have the description of the columns of the last result set. 


 The **[close](../tclcmd/close.htm)** object command deletes the result set and frees any associated system resources. 


See also
--------

 **[encoding](../tclcmd/encoding.htm)**, **[tdbc](tdbc.htm)**, **[tdbc::connection](tdbc_connection.htm)**, **[tdbc::statement](tdbc_statement.htm)**, **[tdbc::tokenize](tdbc_tokenize.htm)** Copyright
---------

 Copyright (c) 2008 by Kevin B. Kenny. Copyright © 2008 by Kevin B. Kenny. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcCmd/tdbc_resultset.htm>

tdbc\_mysql
===========

  
[NAME](tdbc_mysql.htm#M2) tdbc::mysql — TDBC-MYSQL bridge 
[SYNOPSIS](tdbc_mysql.htm#M3) 
[DESCRIPTION](tdbc_mysql.htm#M4) 
[CONNECTION OPTIONS](tdbc_mysql.htm#M5)  
[**-host** *hostname*](tdbc_mysql.htm#M6) 
[**-port** *number*](tdbc_mysql.htm#M7) 
[**-socket** *path*](tdbc_mysql.htm#M8) 
[**-user** *name*](tdbc_mysql.htm#M9) 
[**-passwd** *password*](tdbc_mysql.htm#M10) 
[**-password** *password*](tdbc_mysql.htm#M11) 
[**-database** *name*](tdbc_mysql.htm#M12) 
[**-db** *name*](tdbc_mysql.htm#M13) 
[**-interactive** *flag*](tdbc_mysql.htm#M14) 
[**-ssl\_ca** *string*](tdbc_mysql.htm#M15) 
[**-ssl\_capath** *string*](tdbc_mysql.htm#M16) 
[**-ssl\_cert** *string*](tdbc_mysql.htm#M17) 
[**-ssl\_cipher** *string*](tdbc_mysql.htm#M18) 
[**-ssl\_key** *string*](tdbc_mysql.htm#M19) 













 
[EXAMPLES](tdbc_mysql.htm#M20) 
[ADDITIONAL CONNECTION METHODS](tdbc_mysql.htm#M21)  
[*$connection* **evaldirect** *sqlStatement*](tdbc_mysql.htm#M22) 
 
[SEE ALSO](tdbc_mysql.htm#M23) 
[KEYWORDS](tdbc_mysql.htm#M24) 
[COPYRIGHT](tdbc_mysql.htm#M25) 








 Name
----

 tdbc::mysql — TDBC-MYSQL bridge Synopsis
--------

 package require **tdbc::mysql 1.0**  
 **tdbc::mysql::connection create** *db* ?*-option value...*?  
 **tdbc::mysql::connection new** ?*-option value...*?  
 **tdbc::mysql::datasources** ?**-system**|**-user**?  
 **tdbc::mysql::drivers**  
 **tdbc::mysql::datasource** *command* *driverName* ?*keyword*-*value*?...  
 Description
-----------

 The **tdbc::mysql** driver provides a database interface that conforms to Tcl DataBase Connectivity (TDBC) and allows a Tcl script to connect to a MySQL database.  Connection to an MYSQL database is established by invoking **tdbc::mysql::connection create**, passing it the name to give the database handle and a set of *-option-value* pairs. The available options are enumerated under CONNECTION OPTIONS below. As an alternative, **tdbc::mysql::connection new** may be used to create a database connection with an automatically assigned name. The return value from **tdbc::mysql::connection new** is the name that was chosen for the connection handle. 


 The side effect of **tdbc::mysql::connection create** is to create a new database connection.. See **tdbc::connection(n)** for the details of how to use the connection to manipulate a database. 


Connection options
------------------

 The **tdbc::mysql::connection create** object command supports the **-encoding**, **-isolation**, **-readonly** and **-timeout** options common to all TDBC drivers. The **-encoding** option will always fail unless the encoding is **utf-8**; the database connection always uses UTF-8 encoding to be able to transfer arbitrary Unicode characters. The **-readonly** option must be **0**, because MySQL does not offer read-only connections.  In addition, the following options are recognized: 


 
**-host** *hostname*

 Connects to the host specified by *hostname*. This option must be set on the initial creation of the connection; it cannot be changed after connecting. Default is to connect to the local host. 


**-port** *number*

 Connects to a MySQL server listening on the port specified by *number*. This option may not be changed after connecting. It is used only when *host* is specified and is not **localhost**. 


**-socket** *path*

 Connects to a MySQL server listening on the Unix socket or named pipe specified by *path* . This option may not be changed after connecting. It is used only when *-host* is not specified or is **localhost**. 


**-user** *name*

 Presents *name* as the user name to the MySQL server. Default is the current user ID. 


**-passwd** *password*


**-password** *password*

 These two options are synonymous. They present the given *password* as the user's password to the MySQL server. Default is not to present a password. 


**-database** *name*


**-db** *name*

 These two options are synonymous. They present the given *name* as the name of the default database to use in MySQL queries. If not specified, the default database for the current user is used. 


**-interactive** *flag*

 The *flag* value must be a Boolean value. If it is **true** (or any equivalent), the default timeout is set for an interactive user, otherwise, the default timeout is set for a batch user. This option is meaningful only on initial connection. When using the **configure** method on a MySQL connection use the **-timeout** option to set the timeout desired. 


**-ssl\_ca** *string*


**-ssl\_capath** *string*


**-ssl\_cert** *string*


**-ssl\_cipher** *string*


**-ssl\_key** *string*

 These five options set the certificate authority, certificate authority search path, SSL certificate, transfer cipher, and SSL key to the given *string* arguments. These options may be specified only on initial connection to a database, not in the **configure** method of an existing connection. Default is not to use SSL. 

 Examples
--------

 
```
tdbc::mysql::connection -user joe -passwd sesame -db joes_database
```
 Connects to the MySQL server on the local host using the default connection method, presenting user ID 'joe' and password 'sesame'. Uses 'joes\_database' as the default database name. Additional connection methods
-----------------------------

 In addition to the usual methods on the tdbc::connection(n) object, connections to a MySQL database support one additional method: 
 
*$connection* **evaldirect** *sqlStatement*

 This method takes the given *sqlStatement* and interprets as MySQL native SQL code and evaluates it without preparing it. The statement may not contain variable substitutions. The result set is returned as a list of lists, with each sublist being the list of columns of a result row formatted as character strings. Note that the string formatting is done by MySQL and not by Tcl, so details like the appearance of floating point numbers may differ. *This command is not recommended* for anything where the usual *prepare* or *preparecall* methods work correctly. It is provided so that data management language statements that are not implemented in MySQL's prepared statement API, such as **CREATE DATABASE** or **CREATE PROCEDURE**, can be executed. 

 See also
--------

 **[tdbc](../tdbccmd/tdbc.htm)**, **[tdbc::connection](../tdbccmd/tdbc_connection.htm)**, **[tdbc::resultset](../tdbccmd/tdbc_resultset.htm)**, **[tdbc::statement](../tdbccmd/tdbc_statement.htm)** Copyright
---------

 Copyright (c) 2009 by Kevin B. Kenny. 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcmysqlCmd/tdbc_mysql.htm>

tdbc\_odbc
==========

  
[NAME](tdbc_odbc.htm#M2) tdbc::odbc — TDBC-ODBC bridge 
[SYNOPSIS](tdbc_odbc.htm#M3) 
[DESCRIPTION](tdbc_odbc.htm#M4)  
[**add**](tdbc_odbc.htm#M5) 
[**add\_system**](tdbc_odbc.htm#M6) 
[**configure**](tdbc_odbc.htm#M7) 
[**configure\_system**](tdbc_odbc.htm#M8) 
[**remove**](tdbc_odbc.htm#M9) 
[**remove\_system**](tdbc_odbc.htm#M10) 





 
[CONNECTION OPTIONS](tdbc_odbc.htm#M11) 
[EXAMPLES](tdbc_odbc.htm#M12) 
[SEE ALSO](tdbc_odbc.htm#M13) 
[KEYWORDS](tdbc_odbc.htm#M14) 
[COPYRIGHT](tdbc_odbc.htm#M15) 







 Name
----

 tdbc::odbc — TDBC-ODBC bridge Synopsis
--------

 package require **tdbc::odbc 1.0**  
 **tdbc::odbc::connection create** *db* *connectionString* ?*-option value...*?  
 **tdbc::odbc::connection new** *connectionString* ?*-option value...*?  
 **tdbc::odbc::datasources** ?**-system**|**-user**?  
 **tdbc::odbc::drivers**  
 **tdbc::odbc::datasource** *command* *driverName* ?*keyword*-*value*?...  
 Description
-----------

 The **tdbc::odbc** driver provides a database interface that conforms to Tcl DataBase Connectivity (TDBC) and allows a Tcl script to connect to any SQL database presenting an ODBC interface. It is also provided as a worked example of how to write a database driver in C, so that driver authors have a starting point for further development.  Connection to an ODBC database is established by invoking **tdbc::odbc::connection create**, passing it the name to be used as a connection handle, followed by a standard ODBC connection string. As an alternative, **tdbc::odbc::connection new** may be used to create a database connection with an automatically assigned name. The return value from **tdbc::odbc::connection new** is the name that was chosen for the connection handle. 


 The connection string will include at least a **DRIVER** or **DSN** keyword, and may include others that are defined by a particular ODBC driver. (If the local ODBC system supports a graphical user interface, the **-parent** option (see below) may allow calling **tdbc::odbc::connection create** with an empty connection string.) 


 The side effect of **tdbc::odbc::connection create** is to create a new database connection.. See **tdbc::connection(n)** for the details of how to use the connection to manipulate a database. 


 In addition to a standard TDBC interface, **tdbc::odbc** supports three additional ccommands. The first of these, **tdbc::odbc::datasources**, which returns a Tcl list enumerating the named data sources available to the program (for connection with the **DSN** keyword in the connection string). The result of **tdbc::odbc::datasources** may be constrained to only system data sources or only user data sources by including the **-system** or **-user** options, respectively. 


 The **tdbc::odbc::drivers** command returns a dictionary whose keys are the names of drivers available for the **DRIVER** keyword in the connection string, and whose values are descriptions of the drivers. 


 The **tdbc::odbc::datasource** command allows configuration of named data sources on those systems that support the ODBC Installer application programming interface. It accepts a *command*, which specifies the operation to be performed, the name of a *driver* for the database in question, and a set of keyword-value pairs that are interpreted by the given driver. The *command* must be one of the following: 


 **add**
 Adds a user data source. The keyword-value pairs must include at least a **DSN** option naming the data source 

**add\_system**
 Adds a system data source. The keyword-value pairs must include at least a **DSN** option naming the data source 

**configure**
 Configures a user data source. The keyword-value pairs will usually include a **DSN** option naming the data source. Some drivers will support other options, such as the **CREATE\_DB** option to the Microsoft Access driver on Windows. 

**configure\_system**
 Configures a system data source. 

**remove**
 Removes a user data source. The keyword-value pairs must include a **DSN** option specifying the data source to remove. 

**remove\_system**
 Removes a system data source. The keyword-value pairs must include a **DSN** option specifying the data source to remove. 

 Connection options
------------------

 The **tdbc::odbc::connection create** object command supports the **-encoding**, **-isolation**, **-readonly** and **-timeout** options common to all TDBC drivers. The **-encoding** option will succeed only if the requested encoding is the same as the system encoding; **tdbc::odbc** does not attempt to specify alternative encodings to an ODBC driver. (Some drivers accept encoding specifications in the connection string.)  In addition, if Tk is present in the requesting interpreter, and the local system's ODBC driver manager supports a graphical user interface, the **tdbc::odbc::connection create** object command supports a **-parent** option, whose value is the path name of a Tk window. If this option is specified, and a connection string does not specify all the information needed to connect to an interface, the ODBC driver manager will display a dialog box to request whatever additional information is required. The requesting interpreter will block until the user dismisses the dialog, at which point the connection is made. 


Examples
--------

 Sincs ODBC connection strings are driver specific, it is often difficult to find the documentation needed to compose them. The following examples are known to work on most Windows systems and provide at least a few useful things that a program can do. 

```
tdbc::odbc::connection create db \
    "DSN={PAYROLL};UID={aladdin};PWD={Sesame}"
```
 Connects to a named data source "PAYROLL", providing "aladdin" as a user name and "Sesame" as a password. Uses **db** as the name of the connection. 

```
set connString {DRIVER={Microsoft Access Driver (*.mdb)};}
append connString {FIL={MS Access}\;}
append connString {DBQ=} \
    [file nativename [file normalize $fileName]]
tdbc::odbc::connection create db2 -readonly 1 $connString
```
 Opens a connection to a Microsoft Access database file whose name is in *$fileName*. The database is opened in read-only mode. The resulting connection is called "db2". 

```
tdbc::odbc::connection create db3 \
    "DRIVER=SQLite3;DATABASE=$fileName"
```
 Opens a connection to a SQLite3 database whose name is in "$fileName". 

```
tdbc::odbc::datasource add \
    {Microsoft Access Driver (*.mdb)} \
    DSN=MyTestDatabase \
    DBQ=[file native [file normalize $fileName]]
```
 Creates a new user data source with the name, "MyTestDatabase" bound to a Microsoft Access file whose path name is in "$fileName". No connection is made to the data source until the program calls **tdbc::odbc::connection create**. 

```
tdbc::odbc::datasource configure \
    {Microsoft Access Driver (*.mdb)} \
    CREATE_DB=[file native [file normalize $fileName]] \
    General
```
 Creates a new, empty Microsoft Access database in the file identified by "$fileName". No connection is made to the database until the program calls **tdbc::odbc::connection create**. See also
--------

 **[tdbc](../tdbccmd/tdbc.htm)**, **[tdbc::connection](../tdbccmd/tdbc_connection.htm)**, **[tdbc::resultset](../tdbccmd/tdbc_resultset.htm)**, **[tdbc::statement](../tdbccmd/tdbc_statement.htm)** Copyright
---------

 Copyright (c) 2008 by Kevin B. Kenny. 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcodbcCmd/tdbc_odbc.htm>

tdbc\_postgres
==============

  
[NAME](tdbc_postgres.htm#M2) tdbc::postgres — TDBC-POSTGRES bridge 
[SYNOPSIS](tdbc_postgres.htm#M3) 
[DESCRIPTION](tdbc_postgres.htm#M4) 
[CONNECTION OPTIONS](tdbc_postgres.htm#M5)  
[**-host** *hostname*](tdbc_postgres.htm#M6) 
[**-hostaddr** *address*](tdbc_postgres.htm#M7) 
[**-port** *number*](tdbc_postgres.htm#M8) 
[**-user** *name*](tdbc_postgres.htm#M9) 
[**-passwd** *password*](tdbc_postgres.htm#M10) 
[**-password** *password*](tdbc_postgres.htm#M11) 
[**-database** *name*](tdbc_postgres.htm#M12) 
[**-db** *name*](tdbc_postgres.htm#M13) 
[**-options** *opts*](tdbc_postgres.htm#M14) 
[**-tty** *file*](tdbc_postgres.htm#M15) 
[**-sslmode** *mode*](tdbc_postgres.htm#M16) 
[**-requiressl** *flag*](tdbc_postgres.htm#M17) 
[**-service** *name*](tdbc_postgres.htm#M18) 












 
[EXAMPLES](tdbc_postgres.htm#M19) 
[SEE ALSO](tdbc_postgres.htm#M20) 
[KEYWORDS](tdbc_postgres.htm#M21) 
[COPYRIGHT](tdbc_postgres.htm#M22) 







 Name
----

 tdbc::postgres — TDBC-POSTGRES bridge Synopsis
--------

 package require **tdbc::postgres 1.0**  
 **tdbc::postgres::connection create** *db* ?*-option value...*?  
 **tdbc::postgres::connection new** ?*-option value...*?  
 Description
-----------

 The **tdbc::postgres** driver provides a database interface that conforms to Tcl DataBase Connectivity (TDBC) and allows a Tcl script to connect to a Postgres database.  Connection to a POSTGRES database is established by invoking **tdbc::postgres::connection create**, passing it the name to give the database handle and a set of *-option-value* pairs. The available options are enumerated under CONNECTION OPTIONS below. As an alternative, **tdbc::postgres::connection new** may be used to create a database connection with an automatically assigned name. The return value from **tdbc::postgres::connection new** is the name that was chosen for the connection handle. 


 The side effect of **tdbc::postgres::connection create** is to create a new database connection.. See **tdbc::connection(n)** for the details of how to use the connection to manipulate a database. 


Connection options
------------------

 The **tdbc::postgres::connection create** object command supports the **-encoding**, **-isolation**, **-readonly** and **-timeout** options common to all TDBC drivers. The **-timeout** option will only affect connection process, once connected this value will be ignored and cannot be changed after connecting.  In addition, the following options are recognized (these options must be set on the initial creation of the connection; they cannot be changed after connecting) : 


 
**-host** *hostname*

 Connects to the host specified by *hostname*. Default is to connect using a local Unix domain socket. 


**-hostaddr** *address*

 Connects to the host specified by given IP *address*. If both **-host** and **-hostaddr** are given, the value of **-host** is ignored. Default is to connect using a local Unix domain socket. 


**-port** *number*

 Connects to a Postgres server listening on the port specified by *number*. It is used only when *host* or *hostaddr* is specified. 


**-user** *name*

 Presents *name* as the user name to the Postgres server. Default is the current user ID. 


**-passwd** *password*


**-password** *password*

 These two options are synonymous. They present the given *password* as the user's password to the Postgres server. Default is not to present a password. 


**-database** *name*


**-db** *name*

 These two options are synonymous. They present the given *name* as the name of the default database to use in Postgres queries. If not specified, the default database for the current user is used. 


**-options** *opts*

 This sets *opts* as additional command line options send to the server. 


**-tty** *file*

 This option is ignored on never servers. Formerly this specified where to send debug output. This option is left for compatibility with older servers. 


**-sslmode** *mode*

 This option determines whether or with what priority an SSL connection will be negotiated with the server. There are four *modes*: **disable** will attempt only an unencrypted SSL connection; **allow** will negotiate, trying first a non-SSL connection, then if that fails, trying an SSL connection; **prefer** (the default) will negotiate, trying first an SSL connection, then if that fails, trying a regular non-SSL connection; **require** will try only an SSL connection. If PostgreSQL is compiled without SSL support, using option **require** will cause an error, and options **allow** and **prefer** will be tolerated but the driver will be unable to negotiate an SSL connection. 


**-requiressl** *flag*

 This option is deprecated in favor of the **-sslmode** setting. The *flag* value must be a Boolean value. If it is **true** (or any equivalent), driver will then refuse to connect if the server does not accept an SSL connection. The default value is **false** (or any equivalent), and acts the same like **-sslmode** **preffered**


**-service** *name*

 It specifies a service *name* in pg\_service.conf file that holds additional connection parameters. This allows applications to specify only a service name so connection parameters can be centrally maintained. Refer to PostgreSQL Documentation or PREFIX/share/pg\_service.conf.sample file for details. 

 Examples
--------

 
```
tdbc::postgres::connection -user joe -passwd sesame -db joes_database
```
 Connects to the Postgres server on the local host using the default connection method, presenting user ID 'joe' and password 'sesame'. Uses 'joes\_database' as the default database name. See also
--------

 **[tdbc](../tdbccmd/tdbc.htm)**, **[tdbc::connection](../tdbccmd/tdbc_connection.htm)**, **[tdbc::resultset](../tdbccmd/tdbc_resultset.htm)**, **[tdbc::statement](../tdbccmd/tdbc_statement.htm)** Copyright
---------

 Copyright (c) 2009 by Slawomir Cygan 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcpostgresCmd/tdbc_postgres.htm>

rename
======

 Name
----

 rename — Rename or delete a command Synopsis
--------

 **rename** *oldName newName*  
 Description
-----------

 Rename the command that used to be called *oldName* so that it is now called *newName*. If *newName* is an empty string then *oldName* is deleted. *oldName* and *newName* may include namespace qualifiers (names of containing namespaces). If a command is renamed into a different namespace, future invocations of it will execute in the new namespace. The **rename** command returns an empty string as result. Example
-------

 The **rename** command can be used to wrap the standard Tcl commands with your own monitoring machinery. For example, you might wish to count how often the **[source](source.htm)** command is called: 

```
**rename** ::source ::theRealSource
set sourceCount 0
proc ::source args {
    global sourceCount
    puts "called source for the [incr sourceCount]'th time"
    uplevel 1 ::theRealSource $args
}
```
 See also
--------

 **[namespace](namespace.htm)**, **[proc](proc.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/rename.htm>

puts
====

 Name
----

 puts — Write to a channel Synopsis
--------

 **puts** ?**-nonewline**? ?*channelId*? *string*  
 Description
-----------

 Writes the characters given by *string* to the channel given by *channelId*.  *ChannelId* must be an identifier for an open channel such as a Tcl standard channel (**[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** or **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**), the return value from an invocation of **[open](open.htm)** or **[socket](socket.htm)**, or the result of a channel creation command provided by a Tcl extension. The channel must have been opened for output. 


 If no *channelId* is specified then it defaults to **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**. **Puts** normally outputs a newline character after *string*, but this feature may be suppressed by specifying the **-nonewline** switch. 


 Newline characters in the output are translated by **puts** to platform-specific end-of-line sequences according to the current value of the **-translation** option for the channel (for example, on PCs newlines are normally replaced with carriage-return-linefeed sequences. See the **[fconfigure](fconfigure.htm)** manual entry for a discussion on ways in which **[fconfigure](fconfigure.htm)** will alter output. 


 Tcl buffers output internally, so characters written with **puts** may not appear immediately on the output file or device; Tcl will normally delay output until the buffer is full or the channel is closed. You can force output to appear immediately with the **[flush](flush.htm)** command. 


 When the output buffer fills up, the **puts** command will normally block until all the buffered data has been accepted for output by the operating system. If *channelId* is in nonblocking mode then the **puts** command will not block even if the operating system cannot accept the data. Instead, Tcl continues to buffer the data and writes it in the background as fast as the underlying file or device can accept it. The application must use the Tcl event loop for nonblocking output to work; otherwise Tcl never finds out that the file or device is ready for more output data. It is possible for an arbitrarily large amount of data to be buffered for a channel in nonblocking mode, which could consume a large amount of memory. To avoid wasting memory, nonblocking I/O should normally be used in an event-driven fashion with the **[fileevent](fileevent.htm)** command (do not invoke **puts** unless you have recently been notified via a file event that the channel is ready for more output data). 


Examples
--------

 Write a short message to the console (or wherever **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** is directed): 

```
**puts** "Hello, World!"
```
  Print a message in several parts: 



```
**puts** -nonewline "Hello, "
**puts** "World!"
```
  Print a message to the standard error channel: 



```
**puts** stderr "Hello, World!"
```
  Append a log message to a file: 



```
set chan [open my.log a]
set timestamp [clock format [clock seconds]]
**puts** $chan "$timestamp - Hello, World!"
close $chan
```
 See also
--------

 **[file](file.htm)**, **[fileevent](fileevent.htm)**, **[Tcl\_StandardChannels](https://www.tcl.tk/man/tcl/TclLib/StdChannels.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/puts.htm>

list
====

 Name
----

 list — Create a list Synopsis
--------

 **list** ?*arg arg ...*?  
 Description
-----------

 This command returns a list comprised of all the *arg*s, or an empty string if no *arg*s are specified. Braces and backslashes get added as necessary, so that the **[lindex](lindex.htm)** command may be used on the result to re-extract the original arguments, and also so that **[eval](eval.htm)** may be used to execute the resulting list, with *arg1* comprising the command's name and the other *arg*s comprising its arguments. **List** produces slightly different results than **[concat](concat.htm)**: **[concat](concat.htm)** removes one level of grouping before forming the list, while **list** works directly from the original arguments. Example
-------

 The command 

```
**list** a b "c d e  " "  f {g h}"
```
  will return 



```
**a b {c d e } { f {g h}}**
```
  while **[concat](concat.htm)** with the same arguments will return 



```
**a b c d e f {g h}**
```
 See also
--------

 **[lappend](lappend.htm)**, **[lindex](lindex.htm)**, **[linsert](linsert.htm)**, **[llength](llength.htm)**, **[lrange](lrange.htm)**, **[lrepeat](lrepeat.htm)**, **[lreplace](lreplace.htm)**, **[lsearch](lsearch.htm)**, **[lset](lset.htm)**, **[lsort](lsort.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2001 Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/list.htm>

global
======

 Name
----

 global — Access global variables Synopsis
--------

 **global** ?*varname ...*?  
 Description
-----------

 This command has no effect unless executed in the context of a proc body. If the **global** command is executed in the context of a proc body, it creates local variables linked to the corresponding global variables (though these linked variables, like those created by **[upvar](upvar.htm)**, are not included in the list returned by **[info locals](info.htm)**).  If *varname* contains namespace qualifiers, the local variable's name is the unqualified name of the global variable, as determined by the **[namespace tail](namespace.htm)** command. 


 *varname* is always treated as the name of a variable, not an array element. An error is returned if the name looks like an array element, such as **a(b)**. 


Examples
--------

 This procedure sets the namespace variable *::a::x*

```
proc reset {} {
    **global** a::x
    set x 0
}
```
  This procedure accumulates the strings passed to it in a global buffer, separated by newlines. It is useful for situations when you want to build a message piece-by-piece (as if with **[puts](puts.htm)**) but send that full message in a single piece (e.g. over a connection opened with **[socket](socket.htm)** or as part of a counted HTTP response). 



```
proc accum {string} {
    **global** accumulator
    append accumulator $string \n
}
```
 See also
--------

 **[namespace](namespace.htm)**, **[upvar](upvar.htm)**, **[variable](variable.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/global.htm>

tclvars
=======

  
[NAME](tclvars.htm#M2) argc, argv, argv0, auto\_path, env, errorCode, errorInfo, tcl\_interactive, tcl\_library, tcl\_nonwordchars, tcl\_patchLevel, tcl\_pkgPath, tcl\_platform, tcl\_precision, tcl\_rcFileName, tcl\_traceCompile, tcl\_traceExec, tcl\_wordchars, tcl\_version — Variables used by Tcl 
[DESCRIPTION](tclvars.htm#M3)  
[**auto\_path**](tclvars.htm#M4) 
[**env**](tclvars.htm#M5)  
[**env(HOME)**](tclvars.htm#M6) 
[**env(TCL\_LIBRARY)**](tclvars.htm#M7) 
[**env(TCLLIBPATH)**](tclvars.htm#M8) 
[**env(TCL\_TZ)**, **env(TZ)**](tclvars.htm#M9) 
[**env(LC\_ALL)**, **env(LC\_MESSAGES)**, **env(LANG)**](tclvars.htm#M10) 
[**env(TCL\_INTERP\_DEBUG\_FRAME)**](tclvars.htm#M11) 





 
[**errorCode**](tclvars.htm#M12)  
[**ARITH** *code msg*](tclvars.htm#M13) 
[**CHILDKILLED** *pid sigName msg*](tclvars.htm#M14) 
[**CHILDSTATUS** *pid code*](tclvars.htm#M15) 
[**CHILDSUSP** *pid sigName msg*](tclvars.htm#M16) 
[**NONE**](tclvars.htm#M17) 
[**POSIX** *errName msg*](tclvars.htm#M18) 
[**TCL** ...](tclvars.htm#M19) 






 
[**errorInfo**](tclvars.htm#M20) 
[**tcl\_library**](tclvars.htm#M21) 
[**tcl\_patchLevel**](tclvars.htm#M22) 
[**tcl\_pkgPath**](tclvars.htm#M23) 
[**tcl\_platform**](tclvars.htm#M24)  
[**byteOrder**](tclvars.htm#M25) 
[**debug**](tclvars.htm#M26) 
[**engine**](tclvars.htm#M27) 
[**machine**](tclvars.htm#M28) 
[**os**](tclvars.htm#M29) 
[**osVersion**](tclvars.htm#M30) 
[**pathSeparator**](tclvars.htm#M31) 
[**platform**](tclvars.htm#M32) 
[**pointerSize**](tclvars.htm#M33) 
[**threaded**](tclvars.htm#M34) 
[**user**](tclvars.htm#M35) 
[**wordSize**](tclvars.htm#M36) 











 
[**tcl\_precision**](tclvars.htm#M37) 








  
[**tcl\_rcFileName**](tclvars.htm#M38) 
[**tcl\_traceCompile**](tclvars.htm#M39) 

  
[**tcl\_traceExec**](tclvars.htm#M40) 
  
[**tcl\_wordchars**](tclvars.htm#M41) 
[**tcl\_nonwordchars**](tclvars.htm#M42) 
[**tcl\_version**](tclvars.htm#M43) 


 
[OTHER GLOBAL VARIABLES](tclvars.htm#M44)  
[**argc**](tclvars.htm#M45) 
[**argv**](tclvars.htm#M46) 
[**argv0**](tclvars.htm#M47) 
[**tcl\_interactive**](tclvars.htm#M48) 



 
[EXAMPLES](tclvars.htm#M49) 
[SEE ALSO](tclvars.htm#M50) 
[KEYWORDS](tclvars.htm#M51) 





 Name
----

 argc, argv, argv0, auto\_path, env, errorCode, errorInfo, tcl\_interactive, tcl\_library, tcl\_nonwordchars, tcl\_patchLevel, tcl\_pkgPath, tcl\_platform, tcl\_precision, tcl\_rcFileName, tcl\_traceCompile, tcl\_traceExec, tcl\_wordchars, tcl\_version — Variables used by Tcl Description
-----------

 The following global variables are created and managed automatically by the Tcl library. Except where noted below, these variables should normally be treated as read-only by application-specific code and by users. 
 **auto\_path**
 If set, then it must contain a valid Tcl list giving directories to search during auto-load operations (including for package index files when using the default **[package unknown](package.htm)** handler). This variable is initialized during startup to contain, in order: the directories listed in the **TCLLIBPATH** environment variable, the directory named by the **tcl\_library** global variable, the parent directory of **tcl\_library**, the directories listed in the **tcl\_pkgPath** variable. Additional locations to look for files and package indices should normally be added to this variable using **[lappend](lappend.htm)**.  Additional variables relating to package management exist. More details are listed in the **VARIABLES** section of the **[library](library.htm)** manual page. 



**env**
 This variable is maintained by Tcl as an array whose elements are the environment variables for the process. Reading an element will return the value of the corresponding environment variable. Setting an element of the array will modify the corresponding environment variable or create a new one if it does not already exist. Unsetting an element of **env** will remove the corresponding environment variable. Changes to the **env** array will affect the environment passed to children by commands like **[exec](exec.htm)**. If the entire **env** array is unset then Tcl will stop monitoring **env** accesses and will not update environment variables.  Under Windows, the environment variables PATH and COMSPEC in any capitalization are converted automatically to upper case. For instance, the PATH variable could be exported by the operating system as “path”, “Path”, “PaTh”, etc., causing otherwise simple Tcl code to have to support many special cases. All other environment variables inherited by Tcl are left unmodified. Setting an env array variable to blank is the same as unsetting it as this is the behavior of the underlying Windows OS. It should be noted that relying on an existing and empty environment variable will not work on Windows and is discouraged for cross-platform usage. 


 The following elements of **env** are special to Tcl: 


 **env(HOME)**
 This environment variable, if set, gives the location of the directory considered to be the current user's home directory, and to which a call of **[cd](cd.htm)** without arguments or with just “~” as an argument will change into. Most platforms set this correctly by default; it does not normally need to be set by user code. 

**env(TCL\_LIBRARY)**
 If set, then it specifies the location of the directory containing library scripts (the value of this variable will be assigned to the **tcl\_library** variable and therefore returned by the command **[info library](info.htm)**). If this variable is not set then a default value is used.  Note that this environment variable should *not* normally be set. 



**env(TCLLIBPATH)**
 If set, then it must contain a valid Tcl list giving directories to search during auto-load operations. Directories must be specified in Tcl format, using “/” as the path separator, regardless of platform. This variable is only used when initializing the **auto\_path** variable. 


**env(TCL\_TZ)**, **env(TZ)**

 These specify the default timezone used for parsing and formatting times and dates in the **[clock](clock.htm)** command. On many platforms, the TZ environment variable is set up by the operating system. 


**env(LC\_ALL)**, **env(LC\_MESSAGES)**, **env(LANG)**

 These environment variables are used by the **[msgcat](msgcat.htm)** package to determine what locale to format messages using. 

**env(TCL\_INTERP\_DEBUG\_FRAME)**
 If existing, it has the same effect as running **[interp debug](interp.htm)** **{} -frame 1** as the very first command of each new Tcl interpreter. 



**errorCode**
 This variable holds the value of the **-errorcode** return option set by the most recent error that occurred in this interpreter. This list value represents additional information about the error in a form that is easy to process with programs. The first element of the list identifies a general class of errors, and determines the format of the rest of the list. The following formats for **-errorcode** return options are used by the Tcl core; individual applications may define additional formats. 
 
**ARITH** *code msg*

 This format is used when an arithmetic error occurs (e.g. an attempt to divide zero by zero in the **[expr](expr.htm)** command). *Code* identifies the precise error and *msg* provides a human-readable description of the error. *Code* will be either DIVZERO (for an attempt to divide by zero), DOMAIN (if an argument is outside the domain of a function, such as acos(-3)), IOVERFLOW (for integer overflow), OVERFLOW (for a floating-point overflow), or UNKNOWN (if the cause of the error cannot be determined).  Detection of these errors depends in part on the underlying hardware and system libraries. 




**CHILDKILLED** *pid sigName msg*

 This format is used when a child process has been killed because of a signal. The *pid* element will be the process's identifier (in decimal). The *sigName* element will be the symbolic name of the signal that caused the process to terminate; it will be one of the names from the include file signal.h, such as **SIGPIPE**. The *msg* element will be a short human-readable message describing the signal, such as “write on pipe with no readers” for **SIGPIPE**. 


**CHILDSTATUS** *pid code*

 This format is used when a child process has exited with a non-zero exit status. The *pid* element will be the process's identifier (in decimal) and the *code* element will be the exit code returned by the process (also in decimal). 


**CHILDSUSP** *pid sigName msg*

 This format is used when a child process has been suspended because of a signal. The *pid* element will be the process's identifier, in decimal. The *sigName* element will be the symbolic name of the signal that caused the process to suspend; this will be one of the names from the include file signal.h, such as **SIGTTIN**. The *msg* element will be a short human-readable message describing the signal, such as “background tty read” for **SIGTTIN**. 

**NONE**
 This format is used for errors where no additional information is available for an error besides the message returned with the error. In these cases the **-errorcode** return option will consist of a list containing a single element whose contents are **NONE**. 


**POSIX** *errName msg*

 If the first element is **POSIX**, then the error occurred during a POSIX kernel call. The *errName* element will contain the symbolic name of the error that occurred, such as **ENOENT**; this will be one of the values defined in the include file errno.h. The *msg* element will be a human-readable message corresponding to *errName*, such as “no such file or directory” for the **ENOENT** case. 


**TCL** ...
 Indicates some sort of problem generated in relation to Tcl itself, e.g. a failure to look up a channel or variable. 

To set the **-errorcode** return option, applications should use library procedures such as **[Tcl\_SetObjErrorCode](https://www.tcl.tk/man/tcl/TclLib/AddErrInfo.htm)**, **[Tcl\_SetReturnOptions](https://www.tcl.tk/man/tcl/TclLib/AddErrInfo.htm)**, and **[Tcl\_PosixError](https://www.tcl.tk/man/tcl/TclLib/AddErrInfo.htm)**, or they may invoke the **-errorcode** option of the **[return](return.htm)** command. If none of these methods for setting the error code has been used, the Tcl interpreter will reset the variable to **NONE** after the next error.



**errorInfo**
 This variable holds the value of the **-errorinfo** return option set by the most recent error that occurred in this interpreter. This string value will contain one or more lines identifying the Tcl commands and procedures that were being executed when the most recent error occurred. Its contents take the form of a stack trace showing the various nested Tcl commands that had been invoked at the time of the error. 

**tcl\_library**
 This variable holds the name of a directory containing the system library of Tcl scripts, such as those used for auto-loading. The value of this variable is returned by the **[info library](info.htm)** command. See the **[library](library.htm)** manual entry for details of the facilities provided by the Tcl script library. Normally each application or package will have its own application-specific script library in addition to the Tcl script library; each application should set a global variable with a name like **$***app***\_library** (where *app* is the application's name) to hold the network file name for that application's library directory. The initial value of **tcl\_library** is set when an interpreter is created by searching several different directories until one is found that contains an appropriate Tcl startup script. If the **TCL\_LIBRARY** environment variable exists, then the directory it names is checked first. If **TCL\_LIBRARY** is not set or doesn't refer to an appropriate directory, then Tcl checks several other directories based on a compiled-in default location, the location of the binary containing the application, and the current working directory. 

**tcl\_patchLevel**
 When an interpreter is created Tcl initializes this variable to hold a string giving the current patch level for Tcl, such as **8.4.16** for Tcl 8.4 with the first sixteen official patches, or **8.5b3** for the third beta release of Tcl 8.5. The value of this variable is returned by the **[info patchlevel](info.htm)** command. 

**tcl\_pkgPath**
 This variable holds a list of directories indicating where packages are normally installed. It is not used on Windows. It typically contains either one or two entries; if it contains two entries, the first is normally a directory for platform-dependent packages (e.g., shared library binaries) and the second is normally a directory for platform-independent packages (e.g., script files). Typically a package is installed as a subdirectory of one of the entries in the **tcl\_pkgPath** variable. The directories in the **tcl\_pkgPath** variable are included by default in the **auto\_path** variable, so they and their immediate subdirectories are automatically searched for packages during **[package require](package.htm)** commands. Note: **tcl\_pkgPath** is not intended to be modified by the application. Its value is added to **auto\_path** at startup; changes to **tcl\_pkgPath** are not reflected in **auto\_path**. If you want Tcl to search additional directories for packages you should add the names of those directories to **auto\_path**, not **tcl\_pkgPath**. 

**tcl\_platform**
 This is an associative array whose elements contain information about the platform on which the application is running, such as the name of the operating system, its current release number, and the machine's instruction set. The elements listed below will always be defined, but they may have empty strings as values if Tcl could not retrieve any relevant information. In addition, extensions and applications may add additional values to the array. The predefined elements are: 
 **byteOrder**
 The native byte order of this machine: either **littleEndian** or **bigEndian**. 

**debug**
 If this variable exists, then the interpreter was compiled with and linked to a debug-enabled C run-time. This variable will only exist on Windows, so extension writers can specify which package to load depending on the C run-time library that is in use. This is not an indication that this core contains symbols. 

**engine**
 The name of the Tcl language implementation. When the interpreter is first created, this is always set to the string **[Tcl](tcl.htm)**. 

**machine**
 The instruction set executed by this machine, such as **intel**, **PPC**, **68k**, or **sun4m**. On UNIX machines, this is the value returned by **uname -m**. 

**os**
 The name of the operating system running on this machine, such as **Windows NT** or **SunOS**. On UNIX machines, this is the value returned by **uname -s**. 

**osVersion**
 The version number for the operating system running on this machine. On UNIX machines, this is the value returned by **uname -r**. 

**pathSeparator**
 The character that should be used to **[split](split.htm)** PATH-like environment variables into their corresponding list of directory names. 

**platform**
 Either **windows**, or **unix**. This identifies the general operating environment of the machine. 

**pointerSize**
 This gives the size of the native-machine pointer in bytes (strictly, it is same as the result of evaluating *sizeof(void\*)* in C.) 

**threaded**
 If this variable exists, then the interpreter was compiled with threads enabled. 

**user**
 This identifies the current user based on the login information available on the platform. This value comes from the getuid() and getpwuid() system calls on Unix, and the value from the GetUserName() system call on Windows. 

**wordSize**
 This gives the size of the native-machine word in bytes (strictly, it is same as the result of evaluating *sizeof(long)* in C.) 



**tcl\_precision**
 This variable controls the number of digits to generate when converting floating-point values to strings. It defaults to 0. *Applications should not change this value;* it is provided for compatibility with legacy code. 


 The default value of 0 is special, meaning that Tcl should convert numbers using as few digits as possible while still distinguishing any floating point number from its nearest neighbours. It differs from using an arbitrarily high value for *tcl\_precision* in that an inexact number like *1.4* will convert as *1.4* rather than *1.3999999999999999* even though the latter is nearer to the exact value of the binary number. 
 If **tcl\_precision** is not zero, then when Tcl converts a floating point number, it creates a decimal representation of at most **tcl\_precision** significant digits; the result may be shorter if the shorter result represents the original number exactly. If no result of at most **tcl\_precision** digits is an exact representation of the original number, the one that is closest to the original number is chosen. If the original number lies precisely between two equally accurate decimal representations, then the one with an even value for the least significant digit is chosen; for instance, if **tcl\_precision** is 3, then 0.3125 will convert to 0.312, not 0.313, while 0.6875 will convert to 0.688, not 0.687. Any string of trailing zeroes that remains is trimmed. 
 a **tcl\_precision** value of 17 digits is “perfect” for IEEE floating-point in that it allows double-precision values to be converted to strings and back to binary with no loss of information. For this reason, you will often see it as a value in legacy code that must run on Tcl versions before 8.5. It is no longer recommended; as noted above, a zero value is the preferred method. 
 All interpreters in a thread share a single **tcl\_precision** value: changing it in one interpreter will affect all other interpreters as well. Safe interpreters are not allowed to modify the variable. 
 Valid values for **tcl\_precision** range from 0 to 17. 
 **tcl\_rcFileName**
 This variable is used during initialization to indicate the name of a user-specific startup file. If it is set by application-specific initialization, then the Tcl startup code will check for the existence of this file and **[source](source.htm)** it if it exists. For example, for **[wish](../usercmd/wish.htm)** the variable is set to **~/.wishrc** for Unix and **~/wishrc.tcl** for Windows. 

**tcl\_traceCompile**
 The value of this variable can be set to control how much tracing information is displayed during bytecode compilation. By default, **tcl\_traceCompile** is zero and no information is displayed. Setting **tcl\_traceCompile** to 1 generates a one-line summary in **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** whenever a procedure or top-level command is compiled. Setting it to 2 generates a detailed listing in **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** of the bytecode instructions emitted during every compilation. This variable is useful in tracking down suspected problems with the Tcl compiler. 


 This variable and functionality only exist if **TCL\_COMPILE\_DEBUG** was defined during Tcl's compilation. 
 **tcl\_traceExec**
 The value of this variable can be set to control how much tracing information is displayed during bytecode execution. By default, **tcl\_traceExec** is zero and no information is displayed. Setting **tcl\_traceExec** to 1 generates a one-line trace in **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** on each call to a Tcl procedure. Setting it to 2 generates a line of output whenever any Tcl command is invoked that contains the name of the command and its arguments. Setting it to 3 produces a detailed trace showing the result of executing each bytecode instruction. Note that when **tcl\_traceExec** is 2 or 3, commands such as **[set](set.htm)** and **[incr](incr.htm)** that have been entirely replaced by a sequence of bytecode instructions are not shown. Setting this variable is useful in tracking down suspected problems with the bytecode compiler and interpreter. 


 This variable and functionality only exist if **TCL\_COMPILE\_DEBUG** was defined during Tcl's compilation. 
 **tcl\_wordchars**
 The value of this variable is a regular expression that can be set to control what are considered “word” characters, for instances like selecting a word by double-clicking in text in Tk. It is platform dependent. On Windows, it defaults to **\S**, meaning anything but a Unicode space character. Otherwise it defaults to **\w**, which is any Unicode word character (number, letter, or underscore). 

**tcl\_nonwordchars**
 The value of this variable is a regular expression that can be set to control what are considered “non-word” characters, for instances like selecting a word by double-clicking in text in Tk. It is platform dependent. On Windows, it defaults to **\s**, meaning any Unicode space character. Otherwise it defaults to **\W**, which is anything but a Unicode word character (number, letter, or underscore). 

**tcl\_version**
 When an interpreter is created Tcl initializes this variable to hold the version number for this version of Tcl in the form *x.y*. Changes to *x* represent major changes with probable incompatibilities and changes to *y* represent small enhancements and bug fixes that retain backward compatibility. The value of this variable is returned by the **[info tclversion](info.htm)** command. 

 Other global variables
----------------------

 The following variables are only guaranteed to exist in **[tclsh](../usercmd/tclsh.htm)** and **[wish](../usercmd/wish.htm)** executables; the Tcl library does not define them itself but many Tcl environments do. 
 **argc**
 The number of arguments to **[tclsh](../usercmd/tclsh.htm)** or **[wish](../usercmd/wish.htm)**. 

**argv**
 Tcl list of arguments to **[tclsh](../usercmd/tclsh.htm)** or **[wish](../usercmd/wish.htm)**. 

**argv0**
 The script that **[tclsh](../usercmd/tclsh.htm)** or **[wish](../usercmd/wish.htm)** started executing (if it was specified) or otherwise the name by which **[tclsh](../usercmd/tclsh.htm)** or **[wish](../usercmd/wish.htm)** was invoked. 

**tcl\_interactive**
 Contains 1 if **[tclsh](../usercmd/tclsh.htm)** or **[wish](../usercmd/wish.htm)** is running interactively (no script was specified and standard input is a terminal-like device), 0 otherwise. 

 Examples
--------

 To add a directory to the collection of locations searched by **[package require](package.htm)**, e.g., because of some application-specific packages that are used, the **auto\_path** variable needs to be updated: 

```
lappend ::**auto\_path** [file join [pwd] "theLibDir"]
```
  A simple though not very robust way to handle command line arguments of the form “-foo 1 -bar 2” is to load them into an array having first loaded in the default settings: 



```
array set arguments {-foo 0 -bar 0 -grill 0}
array set arguments $::**argv**
puts "foo is $arguments(-foo)"
puts "bar is $arguments(-bar)"
puts "grill is $arguments(-grill)"
```
  The **argv0** global variable can be used (in conjunction with the **[info script](info.htm)** command) to determine whether the current script is being executed as the main script or loaded as a library. This is useful because it allows a single script to be used as both a library and a demonstration of that library: 



```
if {$::**argv0** eq [info script]} {
    # running as: tclsh example.tcl
} else {
    package provide Example 1.0
}
```
 See also
--------

 **[eval](eval.htm)**, **[library](library.htm)**, **[tclsh](../usercmd/tclsh.htm)**, **tkvars**, **[wish](../usercmd/wish.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/tclvars.htm>

tdbc\_connection
================

  
[NAME](tdbc_connection.htm#M2) tdbc::connection — TDBC connection object 
[SYNOPSIS](tdbc_connection.htm#M3) 
[DESCRIPTION](tdbc_connection.htm#M4)  
[**type**](tdbc_connection.htm#M5) 
[**precision**](tdbc_connection.htm#M6) 
[**scale**](tdbc_connection.htm#M7) 
[**nullable**](tdbc_connection.htm#M8) 



  
[**tableCatalog**](tdbc_connection.htm#M9) 
[**tableSchema**](tdbc_connection.htm#M10) 
[**tableName**](tdbc_connection.htm#M11) 
[**constraintCatalog**](tdbc_connection.htm#M12) 
[**constraintSchema**](tdbc_connection.htm#M13) 
[**constraintName**](tdbc_connection.htm#M14) 
[**columnName**](tdbc_connection.htm#M15) 
[**ordinalPosition**](tdbc_connection.htm#M16) 







  
[**foreignConstraintCatalog**](tdbc_connection.htm#M17) 
[**foreignConstraintSchema**](tdbc_connection.htm#M18) 
[**foreignConstraintName**](tdbc_connection.htm#M19) 
[**primaryConstraintCatalog**](tdbc_connection.htm#M20) 
[**primaryConstraintSchema**](tdbc_connection.htm#M21) 
[**primaryConstraintName**](tdbc_connection.htm#M22) 
[**updateAction**](tdbc_connection.htm#M23) 
[**deleteAction**](tdbc_connection.htm#M24) 
[**primaryCatalog**](tdbc_connection.htm#M25) 
[**primarySchema**](tdbc_connection.htm#M26) 









  
[**primaryTable**](tdbc_connection.htm#M27) 
[**primaryColumn**](tdbc_connection.htm#M28) 
[**foreignCatalog**](tdbc_connection.htm#M29) 
[**foreignSchema**](tdbc_connection.htm#M30) 
[**foreignTable**](tdbc_connection.htm#M31) 
[**foreignColumn**](tdbc_connection.htm#M32) 
[**ordinalPosition**](tdbc_connection.htm#M33) 






 
[CONFIGURATION OPTIONS](tdbc_connection.htm#M34)  
[**-encoding** *name*](tdbc_connection.htm#M35) 
[**-isolation** *level*](tdbc_connection.htm#M36) 
[**-timeout** *ms*](tdbc_connection.htm#M37) 
[**-readonly** *flag*](tdbc_connection.htm#M38) 



 
[TRANSACTION ISOLATION LEVELS](tdbc_connection.htm#M39)  
[**readuncommitted**](tdbc_connection.htm#M40) 
[**readcommitted**](tdbc_connection.htm#M41) 
[**repeatableread**](tdbc_connection.htm#M42) 
[**serializable**](tdbc_connection.htm#M43) 
[**readonly**](tdbc_connection.htm#M44) 




 
[SEE ALSO](tdbc_connection.htm#M45) 
[KEYWORDS](tdbc_connection.htm#M46) 
[COPYRIGHT](tdbc_connection.htm#M47) 







 Name
----

 tdbc::connection — TDBC connection object Synopsis
--------

 package require **tdbc 1.0**  
 package require **tdbc::***driver version*  
   
 **tdbc::***driver***::connection create** *db* ?*-option value*...?  
   
 *db* **configure** ?*-option value*...?  
 *db* **[close](../tclcmd/close.htm)**  
 *db* **foreignkeys** ?*-primary tableName*? ?*-foreign tableName*?  
 *db* **prepare** *sql-code*  
 *db* **preparecall** *call*  
 *db* **primarykeys** *tableName*  
 *db* **statements**  
 *db* **resultsets**  
 *db* **tables** ?*pattern*?  
 *db* **columns** *table* ?*pattern*?  
 *db* **begintransaction**  
 *db* **commit**  
 *db* **rollback**  
 *db* **transaction** *script*  
 *db* **allrows** ?**-as lists**|**dicts**? ?**-columnsvariable** *name*? ?**--**? *sql-code* ?*dictionary*?  
 *db* **[foreach](../tclcmd/foreach.htm)** ?**-as lists**|**dicts**? ?**-columnsvariable** *name*? ?--? *varName sqlcode* ?*dictionary*? *script*  
 Description
-----------

 Every database driver for TDBC (Tcl DataBase Connectivity) implements a *connection* object that represents a connection to a database. By convention, this object is created by the command, **tdbc::***driver***::connection create**. This command accepts the name of a Tcl command that will represent the connection and a possible set of options (see **CONFIGURATION OPTIONS**). It establishes a connection to the database and returns the name of the newly-created Tcl command.  The **configure** object command on a database connection, if presented with no arguments, returns a list of alternating keywords and values representing the connection's current configuration. If presented with a single argument *-option*, it returns the configured value of the given option. Otherwise, it must be given an even number of arguments which are alternating options and values. The specified options receive the specified values, and nothing is returned. 


 The **[close](../tclcmd/close.htm)** object command on a database connection closes the connection. All active statements and result sets on the connection are closed. Any uncommitted transaction is rolled back. The object command is deleted. 


 The **prepare** object command on a database connection prepares a SQL statement for execution. The *sql-code* argument must contain a single SQL statement to be executed. Bound variables may be included. The return value is a newly-created Tcl command that represents the statement. See **[tdbc::statement](tdbc_statement.htm)** for more detailed discussion of the SQL accepted by the **prepare** object command and the interface accepted by a statement. 


 On a database connection where the underlying database and driver support stored procedures, the **preparecall** object command prepares a call to a stored procedure for execution. The syntax of the stored procedure call is: 



```
?*resultvar* =? *procname*(?*arg* ?, *arg*...?)
```
  The return value is a newly-created Tcl command that represents the statement. See **[tdbc::statement](tdbc_statement.htm)** for the interface accepted by a statement. 


 The **statements** object command returns a list of statements that have been created by **prepare** and **preparecall** statements against the given connection and have not yet been closed. 


 The **resultsets** object command returns a list of result sets that have been obtained by executing statements prepared using the given connection and not yet closed. 


 The **tables** object command allows the program to query the connection for the names of tables that exist in the database. The optional *pattern* parameter is a pattern to match the name of a table. It may contain the SQL wild-card characters '**%**' and and whose values are subdictionaries. See the documentation for the individual database driver for the interpretation of the values. 


 The **columns** object command allows the program to query the connection for the names of columns that exist in a given table. The optional **pattern** parameter is a pattern to match the name of a column. It may contain the SQL wild-card characters '**%**' and and whose values are dictionaries. Each of the subdictionaries will contain at least the following keys and values (and may contain others whose usage is determined by a specific database driver). 


 **type**
 Contains the data type of the column, and will generally be chosen from the set, **bigint**, **[binary](../tclcmd/binary.htm)**, **bit**, **char**, **date**, **decimal**, **double**, **float**, **integer**, **longvarbinary**, **longvarchar**, **numeric**, **real**, **[time](../tclcmd/time.htm)**, **timestamp**, **smallint**, **tinyint**, **varbinary**, and **varchar**. (If the column has a type that cannot be represented as one of the above, **type** will contain a driver-dependent description of the type.) 

**precision**
 Contains the precision of the column in bits, decimal digits, or the width in characters, according to the type. 

**scale**
 Contains the scale of the column (the number of digits after the radix point), for types that support the concept. 

**nullable**
 Contains 1 if the column can contain NULL values, and 0 otherwise. 

  The **primarykeys** object command allows the program to query the connection for the primary keys belonging to a given table. The *tableName* parameter identifies the table being interrogated. The result is a list of dictionaries enumerating the keys (in a similar format to the list returned by *$connection* **allrows -as dicts**). The keys of the dictionary may include at least the following. Values that are NULL or meaningless in a given database are omitted. 


 **tableCatalog**
 Name of the catalog in which the table appears. 

**tableSchema**
 Name of the schema in which the table appears. 

**tableName**
 Name of the table owning the primary key. 

**constraintCatalog**
 Name of the catalog in which the primary key constraint appears. In some database systems, this may not be the same as the table's catalog. 

**constraintSchema**
 Name of the schema in which the primary key constraint appears. In some database systems, this may not be the same as the table's schema. 

**constraintName**
 Name of the primary key constraint, 

**columnName**
 Name of a column that is a member of the primary key. 

**ordinalPosition**
 Ordinal position of the column within the primary key. 

  To these columns may be added additional ones that are specific to a particular database system. 


 The **foreignkeys** object command allows the program to query the connection for foreign key relationships that apply to a particular table. The relationships may be constrained to the keys that appear in a particular table (**-foreign** *tableName*), the keys that refer to a particular table (**-primary** *tableName*), or both. At least one of **-primary** and **-foreign** should be specified, although some drivers will enumerate all foreign keys in the current catalog if both options are omitted. The result of the **foreignkeys** object command is a list of dictionaries, with one list element per key (in a similar format to the list returned by *$connection* **allrows -as dicts**). The keys of the dictionary may include at least the following. Values that are NULL or meaningless in a given database are omitted. 


 **foreignConstraintCatalog**
 Catalog in which the foreign key constraint appears. 

**foreignConstraintSchema**
 Schema in which the foreign key constraint appears. 

**foreignConstraintName**
 Name of the foreign key constraint. 

**primaryConstraintCatalog**
 Catalog holding the primary key constraint (or unique key constraint) on the column to which the foreign key refers. 

**primaryConstraintSchema**
 Schema holding the primary key constraint (or unique key constraint) on the column to which the foreign key refers. 

**primaryConstraintName**
 Name of the primary key constraint (or unique key constraint) on the column to which the foreign key refers. 

**updateAction**
 Action to take when an UPDATE statement invalidates the constraint. The value will be **CASCADE**, **SET DEFAULT**, **SET NULL**, **RESTRICT**, or **NO ACTION**. 

**deleteAction**
 Action to take when a DELETE statement invalidates the constraint. The value will be **CASCADE**, **SET DEFAULT**, **SET NULL**, **RESTRICT**, or **NO ACTION**. 

**primaryCatalog**
 Catalog name in which the primary table (the one to which the foreign key refers) appears. 

**primarySchema**
 Schema name in which the primary table (the one to which the foreign key refers) appears. 


 **primaryTable**
 Table name of the primary table (the one to which the foreign key refers). 

**primaryColumn**
 Name of the column to which the foreign key refers. 

**foreignCatalog**
 Name of the catalog in which the table containing the foreign key appears. 

**foreignSchema**
 Name of the schema in which the table containing the foreign key appears. 

**foreignTable**
 Name of the table containing the foreign key. 

**foreignColumn**
 Name of the column appearing in the foreign key. 

**ordinalPosition**
 Position of the column in the foreign key, if the key is a compound key. 

  The **begintransaction** object command on a database connection begins a transaction on the database. If the underlying database does not support atomic, consistent, isolated, durable transactions, the **begintransaction** object command returns an error reporting the fact. Similarly, if multiple **begintransaction** commands are executed withough an intervening **commit** or **rollback** command, an error is returned unless the underlying database supports nested transactions. 


 The **commit** object command on a database connection ends the most recent transaction started by **begintransaction** and commits changes to the database. 


 The **rollback** object command on a database connection rolls back the most recent transaction started by **begintransaction**. The state of the database is as if nothing happened during the transaction. 


 The **transaction** object command on a database connection presents a simple way of bundling a database transaction. It begins a transaction, and evaluates the supplied *script* argument as a Tcl script in the caller's scope. If *script* terminates normally, or by **[break](../tclcmd/break.htm)**, **[continue](../tclcmd/continue.htm)**, or **[return](../tclcmd/return.htm)**, the transaction is committed (and any action requested by **[break](../tclcmd/break.htm)**, **[continue](../tclcmd/continue.htm)**, or **[return](../tclcmd/return.htm)** takes place). If the commit fails for any reason, the error in the commit is treated as an error in the *script*. In the case of an error in *script* or in the commit, the transaction is rolled back and the error is rethrown. Any nonstandard return code from the script causes the transaction to be rolled back and then is rethrown. 


 The **allrows** object command prepares a SQL statement (given by the *sql-code* parameter) to execute against the database. It then executes it (see **[tdbc::statement](tdbc_statement.htm)** for details) with the optional *dictionary* parameter giving bind variables. Finally, it uses the *allrows* object command on the result set (see **[tdbc::resultset](tdbc_resultset.htm)**) to construct a list of the results. Finally, both result set and statement are closed. The return value is the list of results. 


 The **[foreach](../tclcmd/foreach.htm)** object command prepares a SQL statement (given by the *sql-code* parameter) to execute against the database. It then executes it (see **[tdbc::statement](tdbc_statement.htm)** for details) with the optional *dictionary* parameter giving bind variables. Finally, it uses the *foreach* object command on the result set (see **[tdbc::resultset](tdbc_resultset.htm)**) to evaluate the given *script* for each row of the results. Finally, both result set and statement are closed, even if the given *script* results in a **[return](../tclcmd/return.htm)**, an error, or an unusual return code. 


Configuration options
---------------------

 The configuration options accepted when the connection is created and on the connection's **configure** object command include the following, and may include others specific to a database driver. 
 
**-encoding** *name*

 Specifies the encoding to be used in connecting to the database. The *name* should be one of the names accepted by the **[encoding](../tclcmd/encoding.htm)** command. This option is usually unnecessary; most database drivers can figure out the encoding in use by themselves. 


**-isolation** *level*

 Specifies the transaction isolation level needed for transactions on the database. The acceptable values for *level* are shown under **[TRANSACTION ISOLATION LEVELS](#M39)**. 


**-timeout** *ms*

 Specifies the maximum time to wait for a an operation database engine before reporting an error to the caller. The *ms* argument gives the maximum time in milliseconds. A value of zero (the default) specifies that the calling process is to wait indefinitely for database operations. 


**-readonly** *flag*

 Specifies that the connection will not modify the database (if the Boolean parameter *flag* is true), or that it may modify the database (if *flag* is false). If *flag* is true, this option may have the effect of raising the transaction isolation level to *readonly*. 

 ### Transaction isolation levels

 The acceptable values for the **-isolation** configuration option are as follows: 
 **readuncommitted**
 Allows the transaction to read "dirty", that is, uncommitted data. This isolation level may compromise data integrity, does not guarantee that foreign keys or uniqueness constraints are satisfied, and in general does not guarantee data consistency. 

**readcommitted**
 Forbids the transaction from reading "dirty" data, but does not guarantee repeatable reads; if a transaction reads a row of a database at a given time, there is no guarantee that the same row will be available at a later time in the same transaction. 

**repeatableread**
 Guarantees that any row of the database, once read, will have the same values for the life of a transaction. Still permits "phantom reads" (that is, newly-added rows appearing if a table is queried a second time). 

**serializable**
 The most restrictive (and most expensive) level of transaction isolation. Any query to the database, if repeated, will return precisely the same results for the life of the transaction, exactly as if the transaction is the only user of the database. 

**readonly**
 Behaves like **serializable** in that the only results visible to the transaction are those that were committed prior to the start of the transaction, but forbids the transaction from modifying the database. 

  A database that does not implement one of these isolation levels will instead use the next more restrictive isolation level. If the given level of isolation cannot be obtained, the database interface throws an error reporting the fact. The default isolation level is **readcommitted**. 


 A script should not the isolation level when a transaction is in progress. 


See also
--------

 **[encoding](../tclcmd/encoding.htm)**, **[tdbc](tdbc.htm)**, **[tdbc::resultset](tdbc_resultset.htm)**, **[tdbc::statement](tdbc_statement.htm)**, **[tdbc::tokenize](tdbc_tokenize.htm)** Copyright
---------

 Copyright (c) 2008 by Kevin B. Kenny. Copyright © 2008 by Kevin B. Kenny. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TdbcCmd/tdbc_connection.htm>

eval
====

 Name
----

 eval — Evaluate a Tcl script Synopsis
--------

 **eval** *arg* ?*arg ...*?  
 Description
-----------

 **Eval** takes one or more arguments, which together comprise a Tcl script containing one or more commands. **Eval** concatenates all its arguments in the same fashion as the **[concat](concat.htm)** command, passes the concatenated string to the Tcl interpreter recursively, and returns the result of that evaluation (or any error generated by it). Note that the **[list](list.htm)** command quotes sequences of words in such a way that they are not further expanded by the **eval** command. Examples
--------

 Often, it is useful to store a fragment of a script in a variable and execute it later on with extra values appended. This technique is used in a number of places throughout the Tcl core (e.g. in **[fcopy](fcopy.htm)**, **[lsort](lsort.htm)** and **[trace](trace.htm)** command callbacks). This example shows how to do this using core Tcl commands: 

```
set script {
    puts "logging now"
    lappend $myCurrentLogVar
}
set myCurrentLogVar log1
# Set up a switch of logging variable part way through!
after 20000 set myCurrentLogVar log2

for {set i 0} {$i<10} {incr i} {
    # Introduce a random delay
    after [expr {int(5000 * rand())}]
    update    ;# Check for the asynch log switch
    **eval** $script $i [clock clicks]
}
```
  Note that in the most common case (where the script fragment is actually just a list of words forming a command prefix), it is better to use **{\*}$script** when doing this sort of invocation pattern. It is less general than the **eval** command, and hence easier to make robust in practice. The following procedure acts in a way that is analogous to the **[lappend](lappend.htm)** command, except it inserts the argument values at the start of the list in the variable: 



```
proc lprepend {varName args} {
    upvar 1 $varName var
    # Ensure that the variable exists and contains a list
    lappend var
    # Now we insert all the arguments in one go
    set var [**eval** [list linsert $var 0] $args]
}
```
  However, the last line would now normally be written without **eval**, like this: 



```
set var [linsert $var 0 {*}$args]
```
 See also
--------

 **[catch](catch.htm)**, **[concat](concat.htm)**, **[error](error.htm)**, **[errorCode](tclvars.htm)**, **[errorInfo](tclvars.htm)**, **[interp](interp.htm)**, **[list](list.htm)**, **[namespace](namespace.htm)**, **[subst](subst.htm)**, **[uplevel](uplevel.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/eval.htm>

tpool
=====

  
[NAME](tpool.htm#M2) tpool — Part of the Tcl threading extension implementing pools of worker threads . 
[SYNOPSIS](tpool.htm#M3) 
[DESCRIPTION](tpool.htm#M4) 
[COMMANDS](tpool.htm#M5)  
[**tpool::create** ?options?](tpool.htm#M6)  
[**-minworkers** *number*](tpool.htm#M7) 
[**-maxworkers** *number*](tpool.htm#M8) 
[**-idletime** *seconds*](tpool.htm#M9) 
[**-initcmd** *script*](tpool.htm#M10) 
[**-exitcmd** *script*](tpool.htm#M11) 




 
[**tpool::names**](tpool.htm#M12) 
[**tpool::post** ?-detached? ?-nowait? *tpool* *script*](tpool.htm#M13) 
[**tpool::wait** *tpool* *joblist* ?varname?](tpool.htm#M14) 
[**tpool::cancel** *tpool* *joblist* ?varname?](tpool.htm#M15) 
[**tpool::get** *tpool* *job*](tpool.htm#M16) 
[**tpool::preserve** *tpool*](tpool.htm#M17) 
[**tpool::release** *tpool*](tpool.htm#M18) 
[**tpool::suspend** *tpool*](tpool.htm#M19) 
[**tpool::resume** *tpool*](tpool.htm#M20) 









 
[DISCUSSION](tpool.htm#M21) 
[SEE ALSO](tpool.htm#M22) 
[KEYWORDS](tpool.htm#M23) 






 Name
----

 tpool — Part of the Tcl threading extension implementing pools of worker threads . Synopsis
--------

 package require **Tcl 8 .4**  
 package require **Thread ?2 .8?**  
 **tpool::create** ?options?  
 **tpool::names**  
 **tpool::post** ?-detached? ?-nowait? *tpool* *script*  
 **tpool::wait** *tpool* *joblist* ?varname?  
 **tpool::cancel** *tpool* *joblist* ?varname?  
 **tpool::get** *tpool* *job*  
 **tpool::preserve** *tpool*  
 **tpool::release** *tpool*  
 **tpool::suspend** *tpool*  
 **tpool::resume** *tpool*  
 Description
-----------

 This package creates and manages pools of worker threads . It allows you to post jobs to worker threads and wait for their completion . The threadpool implementation is Tcl event-loop aware . That means that any time a caller is forced to wait for an event (job being completed or a worker thread becoming idle or initialized), the implementation will enter the event loop and allow for servicing of other pending file or timer (or any other supported) events . Commands
--------

  
**tpool::create** ?options?
 This command creates new threadpool . It accepts several options as key-value pairs . Options are used to tune some threadpool parameters . The command returns the ID of the newly created threadpool .  Following options are supported: 


 
**-minworkers** *number*

 Minimum number of worker threads needed for this threadpool instance . During threadpool creation, the implementation will create somany worker threads upfront and will keep at least number of them alive during the lifetime of the threadpool instance . Default value of this parameter is 0 (zero) . which means that a newly threadpool will have no worker threads initialy . All worker threads will be started on demand by callers running **tpool::post** command and posting jobs to the job queue . 


**-maxworkers** *number*

 Maximum number of worker threads allowed for this threadpool instance . If a new job is pending and there are no idle worker threads available, the implementation will try to create new worker thread . If the number of available worker threads is lower than the given number, new worker thread will start . The caller will automatically enter the event loop and wait until the worker thread has initialized . If . however, the number of available worker threads is equal to the given number, the caller will enter the event loop and wait for the first worker thread to get idle, thus ready to run the job . Default value of this parameter is 4 (four), which means that the threadpool instance will allow maximum of 4 worker threads running jobs or being idle waiting for new jobs to get posted to the job queue . 


**-idletime** *seconds*

 Time in seconds an idle worker thread waits for the job to get posted to the job queue . If no job arrives during this interval and the time expires, the worker thread will check the number of currently available worker threads and if the number is higher than the number set by the **minthreads** option, it will exit . If an **exitscript** has been defined, the exiting worker thread will first run the script and then exit . Errors from the exit script, if any, are ignored .  The idle worker thread is not servicing the event loop . If you, however, put the worker thread into the event loop, by evaluating the **[vwait](../tclcmd/vwait.htm)** or other related Tcl commands, the worker thread will not be in the idle state, hence the idle timer will not be taken into account . Default value for this option is unspecified . 




**-initcmd** *script*

 Sets a Tcl script used to initialize new worker thread . This is usually used to load packages and commands in the worker, set default variables, create namespaces, and such . If the passed script runs into a Tcl error, the worker will not be created and the initiating command (either the **tpool::create** or **tpool::post**) will throw error . Default value for this option is unspecified, hence, the Tcl interpreter of the worker thread will contain just the initial set of Tcl commands . 


**-exitcmd** *script*

 Sets a Tcl script run when the idle worker thread exits . This is normaly used to cleanup the state of the worker thread, release reserved resources, cleanup memory and such . Default value for this option is unspecified, thus no Tcl script will run on the worker thread exit . 



**tpool::names**
 This command returns a list of IDs of threadpools created with the **tpool::create** command . If no threadpools were found, the command will return empty list . 


**tpool::post** ?-detached? ?-nowait? *tpool* *script*

 This command sends a *script* to the target *tpool* threadpool for execution . The script will be executed in the first available idle worker thread . If there are no idle worker threads available, the command will create new one, enter the event loop and service events until the newly created thread is initialized . If the current number of worker threads is equal to the maximum number of worker threads, as defined during the threadpool creation, the command will enter the event loop and service events while waiting for one of the worker threads to become idle . If the optional ?-nowait? argument is given, the command will not wait for one idle worker . It will just place the job in the pool's job queue and return immediately .  The command returns the ID of the posted job . This ID is used for subsequent **tpool::wait**, **tpool::get** and **tpool::cancel** commands to wait for and retrieve result of the posted script, or cancel the posted job respectively . If the optional ?-detached? argument is specified, the command will post a detached job . A detached job can not be cancelled or waited upon and is not identified by the job ID . 


 If the threadpool *tpool* is not found in the list of active thread pools, the command will throw error . The error will also be triggered if the newly created worker thread fails to initialize . 




**tpool::wait** *tpool* *joblist* ?varname?
 This command waits for one or many jobs, whose job IDs are given in the *joblist* to get processed by the worker thread(s) . If none of the specified jobs are ready, the command will enter the event loop, service events and wait for the first job to get ready .  The command returns the list of completed job IDs . If the optional variable ?varname? is given, it will be set to the list of jobs in the *joblist* which are still pending . If the threadpool *tpool* is not found in the list of active thread pools, the command will throw error . 




**tpool::cancel** *tpool* *joblist* ?varname?
 This command cancels the previously posted jobs given by the *joblist* to the pool *tpool* . Job cancellation succeeds only for job still waiting to be processed . If the job is already being executed by one of the worker threads, the job will not be cancelled . The command returns the list of cancelled job IDs . If the optional variable ?varname? is given, it will be set to the list of jobs in the *joblist* which were not cancelled . If the threadpool *tpool* is not found in the list of active thread pools, the command will throw error . 


**tpool::get** *tpool* *job*

 This command retrieves the result of the previously posted *job* . Only results of jobs waited upon with the **tpool::wait** command can be retrieved . If the execution of the script resulted in error, the command will throw the error and update the **[errorInfo](../tclcmd/tclvars.htm)** and **[errorCode](../tclcmd/tclvars.htm)** variables correspondingly . If the pool *tpool* is not found in the list of threadpools, the command will throw error . If the job *job* is not ready for retrieval, because it is currently being executed by the worker thread, the command will throw error . 


**tpool::preserve** *tpool*

 Each call to this command increments the reference counter of the threadpool *tpool* by one (1) . Command returns the value of the reference counter after the increment . By incrementing the reference counter, the caller signalizes that he/she wishes to use the resource for a longer period of time . 


**tpool::release** *tpool*

 Each call to this command decrements the reference counter of the threadpool *tpool* by one (1) .Command returns the value of the reference counter after the decrement . When the reference counter reaches zero (0), the threadpool *tpool* is marked for termination . You should not reference the threadpool after the **tpool::release** command returns zero . The *tpool* handle goes out of scope and should not be used any more . Any following reference to the same threadpool handle will result in Tcl error . 


**tpool::suspend** *tpool*

 Suspends processing work on this queue . All pool workers are paused but additional work can be added to the pool . Note that adding the additional work will not increase the number of workers dynamically as the pool processing is suspended . Number of workers is maintained to the count that was found prior suspending worker activity . If you need to assure certain number of worker threads, use the **minworkers** option of the **tpool::create** command . 


**tpool::resume** *tpool*

 Resume processing work on this queue . All paused (suspended) workers are free to get work from the pool . Note that resuming pool operation will just let already created workers to proceed . It will not create additional worker threads to handle the work posted to the pool's work queue . 


Discussion
----------

 Threadpool is one of the most common threading paradigm when it comes to server applications handling a large number of relatively small tasks . A very simplistic model for building a server application would be to create a new thread each time a request arrives and service the request in the new thread . One of the disadvantages of this approach is that the overhead of creating a new thread for each request is significant; a server that created a new thread for each request would spend more time and consume more system resources in creating and destroying threads than in processing actual user requests . In addition to the overhead of creating and destroying threads, active threads consume system resources . Creating too many threads can cause the system to run out of memory or trash due to excessive memory consumption .  A thread pool offers a solution to both the problem of thread life-cycle overhead and the problem of resource trashing . By reusing threads for multiple tasks, the thread-creation overhead is spread over many tasks . As a bonus, because the thread already exists when a request arrives, the delay introduced by thread creation is eliminated . Thus, the request can be serviced immediately . Furthermore, by properly tuning the number of threads in the thread pool, resource thrashing may also be eliminated by forcing any request to wait until a thread is available to process it . 


See also
--------

 **[thread](thread.htm)**, **[tsv](tsv.htm)**, **[ttrace](ttrace.htm)** 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ThreadCmd/tpool.htm>

ttrace
======

  
[NAME](ttrace.htm#M2) ttrace — Trace-based interpreter initialization 
[SYNOPSIS](ttrace.htm#M3) 
[DESCRIPTION](ttrace.htm#M4) 
[USER COMMANDS](ttrace.htm#M5)  
[**ttrace::eval** *arg* ?arg . . .?](ttrace.htm#M6) 
[**ttrace::enable**](ttrace.htm#M7) 
[**ttrace::disable**](ttrace.htm#M8) 
[**ttrace::cleanup**](ttrace.htm#M9) 
[**ttrace::update** ?epoch?](ttrace.htm#M10) 
[**ttrace::getscript**](ttrace.htm#M11) 





 
[CALLBACK COMMANDS](ttrace.htm#M12)  
[**ttrace::atenable** *cmd* *arglist* *body*](ttrace.htm#M13) 
[**ttrace::atdisable** *cmd* *arglist* *body*](ttrace.htm#M14) 
[**ttrace::addtrace** *cmd* *arglist* *body*](ttrace.htm#M15) 
[**ttrace::addscript** *name* *body*](ttrace.htm#M16) 
[**ttrace::addresolver** *cmd* *arglist* *body*](ttrace.htm#M17) 
[**ttrace::addcleanup** *body*](ttrace.htm#M18) 
[**ttrace::addentry** *cmd* *var* *val*](ttrace.htm#M19) 
[**ttrace::getentry** *cmd* *var*](ttrace.htm#M20) 
[**ttrace::getentries** *cmd* ?pattern?](ttrace.htm#M21) 
[**ttrace::delentry** *cmd*](ttrace.htm#M22) 
[**ttrace::preload** *cmd*](ttrace.htm#M23) 










 
[DISCUSSION](ttrace.htm#M24) 
[SEE ALSO](ttrace.htm#M25) 
[KEYWORDS](ttrace.htm#M26) 







 Name
----

 ttrace — Trace-based interpreter initialization Synopsis
--------

 package require **Tcl 8 .4**  
 package require **Thread ?2 .8?**  
 **ttrace::eval** *arg* ?arg . . .?  
 **ttrace::enable**  
 **ttrace::disable**  
 **ttrace::cleanup**  
 **ttrace::update** ?epoch?  
 **ttrace::getscript**  
 **ttrace::atenable** *cmd* *arglist* *body*  
 **ttrace::atdisable** *cmd* *arglist* *body*  
 **ttrace::addtrace** *cmd* *arglist* *body*  
 **ttrace::addscript** *name* *body*  
 **ttrace::addresolver** *cmd* *arglist* *body*  
 **ttrace::addcleanup** *body*  
 **ttrace::addentry** *cmd* *var* *val*  
 **ttrace::getentry** *cmd* *var*  
 **ttrace::getentries** *cmd* ?pattern?  
 **ttrace::delentry** *cmd*  
 **ttrace::preload** *cmd*  
 Description
-----------

 This package creates a framework for on-demand replication of the interpreter state accross threads in an multithreading application . It relies on the mechanics of Tcl command tracing and the Tcl **[unknown](../tclcmd/unknown.htm)** command and mechanism .  The package requires Tcl threading extension but can be alternatively used stand-alone within the AOLserver, a scalable webserver from America Online . 


 In a nutshell, a short sample illustrating the usage of the ttrace with the Tcl threading extension: 



```
% package require Ttrace
    2	.8	.0

    % set t1 [thread::create {package require Ttrace; thread::wait}]
    tid0x1802800

    % ttrace::eval {proc test args {return test-[thread::id]}}
    % thread::send $t1 test
    test-tid0x1802800

    % set t2 [thread::create {package require Ttrace; thread::wait}]
    tid0x1804000

    % thread::send $t2 test
    test-tid0x1804000
```
  As seen from above, the **ttrace::eval** and **ttrace::update** commands are used to create a thread-wide definition of a simple Tcl procedure and replicate that definition to all, already existing or later created, threads . 


User commands
-------------

 This section describes user-level commands . Those commands can be used by script writers to control the execution of the tracing framework . 
 
**ttrace::eval** *arg* ?arg . . .?
 This command concatenates given arguments and evaluates the resulting Tcl command with trace framework enabled . If the command execution was ok, it takes necessary steps to automatically propagate the trace epoch change to all threads in the application . For AOLserver, only newly created threads actually receive the epoch change . For the Tcl threading extension, all threads created by the extension are automatically updated . If the command execution resulted in Tcl error, no state propagation takes place .  This is the most important user-level command of the package as it wraps most of the commands described below . This greatly simplifies things, because user need to learn just this (one) command in order to effectively use the package . Other commands, as desribed below, are included mostly for the sake of completeness . 



**ttrace::enable**
 Activates all registered callbacks in the framework and starts a new trace epoch . The trace epoch encapsulates all changes done to the interpreter during the time traces are activated . 

**ttrace::disable**
 Deactivates all registered callbacks in the framework and closes the current trace epoch . 

**ttrace::cleanup**
 Used to clean-up all on-demand loaded resources in the interpreter . It effectively brings Tcl interpreter to its pristine state . 


**ttrace::update** ?epoch?
 Used to refresh the state of the interpreter to match the optional trace ?epoch? . If the optional ?epoch? is not given, it takes the most recent trace epoch . 

**ttrace::getscript**
 Returns a synthetized Tcl script which may be sourced in any interpreter . This script sets the stage for the Tcl **[unknown](../tclcmd/unknown.htm)** command so it can load traced resources from the in-memory database . Normally, this command is automatically invoked by other higher-level commands like **ttrace::eval** and **ttrace::update** . 


Callback commands
-----------------

 A word upfront: the package already includes callbacks for tracing following Tcl commands: **[proc](../tclcmd/proc.htm)**, **[namespace](../tclcmd/namespace.htm)**, **[variable](../tclcmd/variable.htm)**, **[load](../tclcmd/load.htm)**, and **[rename](../tclcmd/rename.htm)** . Additionaly, a set of callbacks for tracing resources (object, clasess) for the XOTcl v1 .3 .8+, an OO-extension to Tcl, is also provided . This gives a solid base for solving most of the real-life needs and serves as an example for people wanting to customize the package to cover their specific needs .  Below, you can find commands for registering callbacks in the framework and for writing callback scripts . These callbacks are invoked by the framework in order to gather interpreter state changes, build in-memory database, perform custom-cleanups and various other tasks . 


 
**ttrace::atenable** *cmd* *arglist* *body*

 Registers Tcl callback to be activated at **ttrace::enable** . Registered callbacks are activated on FIFO basis . The callback definition includes the name of the callback, *cmd*, a list of callback arguments, *arglist* and the *body* of the callback . Effectively, this actually resembles the call interface of the standard Tcl **[proc](../tclcmd/proc.htm)** command . 


**ttrace::atdisable** *cmd* *arglist* *body*

 Registers Tcl callback to be activated at **ttrace::disable** . Registered callbacks are activated on FIFO basis . The callback definition includes the name of the callback, *cmd*, a list of callback arguments, *arglist* and the *body* of the callback . Effectively, this actually resembles the call interface of the standard Tcl **[proc](../tclcmd/proc.htm)** command . 


**ttrace::addtrace** *cmd* *arglist* *body*

 Registers Tcl callback to be activated for tracing the Tcl **cmd** command . The callback definition includes the name of the Tcl command to trace, *cmd*, a list of callback arguments, *arglist* and the *body* of the callback . Effectively, this actually resembles the call interface of the standard Tcl **[proc](../tclcmd/proc.htm)** command . 


**ttrace::addscript** *name* *body*

 Registers Tcl callback to be activated for building a Tcl script to be passed to other interpreters . This script is used to set the stage for the Tcl **[unknown](../tclcmd/unknown.htm)** command . Registered callbacks are activated on FIFO basis . The callback definition includes the name of the callback, *name* and the *body* of the callback . 


**ttrace::addresolver** *cmd* *arglist* *body*

 Registers Tcl callback to be activated by the overloaded Tcl **[unknown](../tclcmd/unknown.htm)** command . Registered callbacks are activated on FIFO basis . This callback is used to resolve the resource and load the resource in the current interpreter . 


**ttrace::addcleanup** *body*

 Registers Tcl callback to be activated by the **trace::cleanup** . Registered callbacks are activated on FIFO basis . 


**ttrace::addentry** *cmd* *var* *val*

 Adds one entry to the named in-memory database . 


**ttrace::getentry** *cmd* *var*

 Returns the value of the entry from the named in-memory database . 


**ttrace::getentries** *cmd* ?pattern?
 Returns names of all entries from the named in-memory database . 


**ttrace::delentry** *cmd*

 Deletes an entry from the named in-memory database . 


**ttrace::preload** *cmd*

 Registers the Tcl command to be loaded in the interpreter . Commands registered this way will always be the part of the interpreter and not be on-demand loaded by the Tcl **[unknown](../tclcmd/unknown.htm)** command . 


Discussion
----------

 Common introspective state-replication approaches use a custom Tcl script to introspect the running interpreter and synthesize another Tcl script to replicate this state in some other interpreter . This package, on the contrary, uses Tcl command traces . Command traces are registered on selected Tcl commands, like **[proc](../tclcmd/proc.htm)**, **[namespace](../tclcmd/namespace.htm)**, **[load](../tclcmd/load.htm)** and other standard (and/or user-defined) Tcl commands . When activated, those traces build an in-memory database of created resources . This database is used as a resource repository for the (overloaded) Tcl **[unknown](../tclcmd/unknown.htm)** command which creates the requested resource in the interpreter on demand . This way, users can update just one interpreter (master) in one thread and replicate that interpreter state (or part of it) to other threads/interpreters in the process .  Immediate benefit of such approach is the much smaller memory footprint of the application and much faster thread creation . By not actually loading all necessary procedures (and other resources) in every thread at the thread initialization time, but by deffering this to the time the resource is actually referenced, significant improvements in both memory consumption and thread initialization time can be achieved . Some tests have shown that memory footprint of an multithreading Tcl application went down more than three times and thread startup time was reduced for about 50 times . Note that your mileage may vary . Other benefits include much finer control about what (and when) gets replicated from the master to other Tcl thread/interpreters . 


See also
--------

 **[thread](thread.htm)**, **[tpool](tpool.htm)**, **[tsv](tsv.htm)** 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ThreadCmd/ttrace.htm>

bell
====

 Name
----

 bell — Ring a display's bell Synopsis
--------

 **bell** ?**-displayof** *window*? ?**-nice**?  
 Description
-----------

 This command rings the bell on the display for *window* and returns an empty string. If the **-displayof** option is omitted, the display of the application's main window is used by default. The command uses the current bell-related settings for the display, which may be modified with programs such as **xset**.  If **-nice** is not specified, this command also resets the screen saver for the screen. Some screen savers will ignore this, but others will reset so that the screen becomes visible again. 

 Copyright © 1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2000 Ajuba Solutions. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/bell.htm>

optionMenu
==========

 Name
----

 tk\_optionMenu — Create an option menubutton and its menu Synopsis
--------

 **tk\_optionMenu** *pathName varName value* ?*value value ...*?  
 Description
-----------

 This procedure creates an option menubutton whose name is *pathName*, plus an associated menu. Together they allow the user to select one of the values given by the *value* arguments. The current value will be stored in the global variable whose name is given by *varName* and it will also be displayed as the label in the option menubutton. The user can click on the menubutton to display a menu containing all of the *value*s and thereby select a new value. Once a new value is selected, it will be stored in the variable and appear in the option menubutton. The current value can also be changed by setting the variable.  The return value from **tk\_optionMenu** is the name of the menu associated with *pathName*, so that the caller can change its configuration options or manipulate it in other ways. 


Example
-------

 
```
tk_optionMenu .foo myVar Foo Bar Boo Spong Wibble
pack .foo
```
 Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/optionMenu.htm>

binary
======

  
[NAME](binary.htm#M2) binary — Insert and extract fields from binary strings 
[SYNOPSIS](binary.htm#M3) 
[DESCRIPTION](binary.htm#M4) 
[BINARY ENCODE AND DECODE](binary.htm#M5)  
[**base64**](binary.htm#M6)  
[**-maxlen** *length*](binary.htm#M7) 
[**-wrapchar** *character*](binary.htm#M8) 

  
[**-strict**](binary.htm#M9) 
 
[**hex**](binary.htm#M10)  
[**-strict**](binary.htm#M11) 
 
[**uuencode**](binary.htm#M12)  
[**-maxlen** *length*](binary.htm#M13) 
[**-wrapchar** *character*](binary.htm#M14) 

  
[**-strict**](binary.htm#M15) 
 


 
[BINARY FORMAT](binary.htm#M16)  
[**a**](binary.htm#M17) 
[**A**](binary.htm#M18) 
[**b**](binary.htm#M19) 
[**B**](binary.htm#M20) 
[**H**](binary.htm#M21) 
[**h**](binary.htm#M22) 
[**c**](binary.htm#M23) 
[**s**](binary.htm#M24) 
[**S**](binary.htm#M25) 
[**t**](binary.htm#M26) 
[**i**](binary.htm#M27) 
[**I**](binary.htm#M28) 
[**n**](binary.htm#M29) 
[**w**](binary.htm#M30) 
[**W**](binary.htm#M31) 
[**m**](binary.htm#M32) 
[**f**](binary.htm#M33) 
[**r**](binary.htm#M34) 
[**R**](binary.htm#M35) 
[**d**](binary.htm#M36) 
[**q**](binary.htm#M37) 
[**Q**](binary.htm#M38) 
[**x**](binary.htm#M39) 
[**X**](binary.htm#M40) 
[**@**](binary.htm#M41) 
























 
[BINARY SCAN](binary.htm#M42)  
[**a**](binary.htm#M43) 
[**A**](binary.htm#M44) 
[**b**](binary.htm#M45) 
[**B**](binary.htm#M46) 
[**H**](binary.htm#M47) 
[**h**](binary.htm#M48) 
[**c**](binary.htm#M49) 
[**s**](binary.htm#M50) 
[**S**](binary.htm#M51) 
[**t**](binary.htm#M52) 
[**i**](binary.htm#M53) 
[**I**](binary.htm#M54) 
[**n**](binary.htm#M55) 
[**w**](binary.htm#M56) 
[**W**](binary.htm#M57) 
[**m**](binary.htm#M58) 
[**f**](binary.htm#M59) 
[**r**](binary.htm#M60) 
[**R**](binary.htm#M61) 
[**d**](binary.htm#M62) 
[**q**](binary.htm#M63) 
[**Q**](binary.htm#M64) 
[**x**](binary.htm#M65) 
[**X**](binary.htm#M66) 
[**@**](binary.htm#M67) 
























 
[PORTABILITY ISSUES](binary.htm#M68) 
[EXAMPLES](binary.htm#M69) 
[SEE ALSO](binary.htm#M70) 
[KEYWORDS](binary.htm#M71) 









 Name
----

 binary — Insert and extract fields from binary strings Synopsis
--------

 **binary decode** *format* ?*-option value ...*? *data*  
 **binary encode** *format* ?*-option value ...*? *data*  
 **binary format** *formatString* ?*arg arg ...*?  
 **binary scan** *string formatString* ?*varName varName ...*?  
 Description
-----------

 This command provides facilities for manipulating binary data. The subcommand **binary format** creates a binary string from normal Tcl values. For example, given the values 16 and 22, on a 32-bit architecture, it might produce an 8-byte binary string consisting of two 4-byte integers, one for each of the numbers. The subcommand **binary scan**, does the opposite: it extracts data from a binary string and returns it as ordinary Tcl string values. The **binary encode** and **binary decode** subcommands convert binary data to or from string encodings such as base64 (used in MIME messages for example).  Note that other operations on binary data, such as taking a subsequence of it, getting its length, or reinterpreting it as a string in some encoding, are done by other Tcl commands (respectively **[string range](string.htm)**, **[string length](string.htm)** and **[encoding convertfrom](encoding.htm)** in the example cases). A binary string in Tcl is merely one where all the characters it contains are in the range \u0000-\u00FF. 


Binary encode and decode
------------------------

 When encoding binary data as a readable string, the starting binary data is passed to the **binary encode** command, together with the name of the encoding to use and any encoding-specific options desired. Data which has been encoded can be converted back to binary form using **binary decode**. The following formats and options are supported. 
 **base64**
 The **base64** binary encoding is commonly used in mail messages and XML documents, and uses mostly upper and lower case letters and digits. It has the distinction of being able to be rewrapped arbitrarily without losing information.  During encoding, the following options are supported: 


 
**-maxlen** *length*

 Indicates that the output should be split into lines of no more than *length* characters. By default, lines are not split. 


**-wrapchar** *character*

 Indicates that, when lines are split because of the **-maxlen** option, *character* should be used to separate lines. By default, this is a newline character, “\n”. 

  During decoding, the following options are supported: 


 **-strict**
 Instructs the decoder to throw an error if it encounters whitespace characters. Otherwise it ignores them. 



**hex**
 The **hex** binary encoding converts each byte to a pair of hexadecimal digits in big-endian form.  No options are supported during encoding. During decoding, the following options are supported: 


 **-strict**
 Instructs the decoder to throw an error if it encounters whitespace characters. Otherwise it ignores them. 



**uuencode**
 The **uuencode** binary encoding used to be common for transfer of data between Unix systems and on USENET, but is less common these days, having been largely superseded by the **base64** binary encoding.  During encoding, the following options are supported (though changing them may produce files that other implementations of decoders cannot process): 


 
**-maxlen** *length*

 Indicates that the output should be split into lines of no more than *length* characters. By default, lines are split every 61 characters, and this must be in the range 3 to 85 due to limitations in the encoding. 


**-wrapchar** *character*

 Indicates that, when lines are split because of the **-maxlen** option, *character* should be used to separate lines. By default, this is a newline character, “\n”. 

  During decoding, the following options are supported: 


 **-strict**
 Instructs the decoder to throw an error if it encounters unexpected whitespace characters. Otherwise it ignores them. 

Note that neither the encoder nor the decoder handle the header and footer of the uuencode format.



 Binary format
-------------

 The **binary format** command generates a binary string whose layout is specified by the *formatString* and whose contents come from the additional arguments. The resulting binary value is returned.  The *formatString* consists of a sequence of zero or more field specifiers separated by zero or more spaces. Each field specifier is a single type character followed by an optional flag character followed by an optional numeric *count*. Most field specifiers consume one argument to obtain the value to be formatted. The type character specifies how the value is to be formatted. The *count* typically indicates how many items of the specified type are taken from the value. If present, the *count* is a non-negative decimal integer or **\***, which normally indicates that all of the items in the value are to be used. If the number of arguments does not match the number of fields in the format string that consume arguments, then an error is generated. The flag character is ignored for **binary format**. 


 Here is a small example to clarify the relation between the field specifiers and the arguments: 



```
**binary format** d3d {1.0 2.0 3.0 4.0} 0.1
```
  The first argument is a list of four numbers, but because of the count of 3 for the associated field specifier, only the first three will be used. The second argument is associated with the second field specifier. The resulting binary string contains the four numbers 1.0, 2.0, 3.0 and 0.1. 


 Each type-count pair moves an imaginary cursor through the binary data, storing bytes at the current position and advancing the cursor to just after the last byte stored. The cursor is initially at position 0 at the beginning of the data. The type may be any one of the following characters: 


 **a**
 Stores a byte string of length *count* in the output string. Every character is taken as modulo 256 (i.e. the low byte of every character is used, and the high byte discarded) so when storing character strings not wholly expressible using the characters \u0000-\u00ff, the **[encoding convertto](encoding.htm)** command should be used first to change the string into an external representation if this truncation is not desired (i.e. if the characters are not part of the ISO 8859-1 character set.) If *arg* has fewer than *count* bytes, then additional zero bytes are used to pad out the field. If *arg* is longer than the specified length, the extra characters will be ignored. If *count* is **\***, then all of the bytes in *arg* will be formatted. If *count* is omitted, then one character will be formatted. For example, 
```
**binary format** a7a*a alpha bravo charlie
```
 will return a string equivalent to **alpha\000\000bravoc**, 
```
**binary format** a* [encoding convertto utf-8 \u20ac]
```
 will return a string equivalent to **\342\202\254** (which is the UTF-8 byte sequence for a Euro-currency character) and 
```
**binary format** a* [encoding convertto iso8859-15 \u20ac]
```
 will return a string equivalent to **\244** (which is the ISO 8859-15 byte sequence for a Euro-currency character). Contrast these last two with: 
```
**binary format** a* \u20ac
```
 which returns a string equivalent to **\254** (i.e. **\xac**) by truncating the high-bits of the character, and which is probably not what is desired. 

**A**
 This form is the same as **a** except that spaces are used for padding instead of nulls. For example, 
```
**binary format** A6A*A alpha bravo charlie
```
 will return **alpha bravoc**. 

**b**
 Stores a string of *count* binary digits in low-to-high order within each byte in the output string. *Arg* must contain a sequence of **1** and **0** characters. The resulting bytes are emitted in first to last order with the bits being formatted in low-to-high order within each byte. If *arg* has fewer than *count* digits, then zeros will be used for the remaining bits. If *arg* has more than the specified number of digits, the extra digits will be ignored. If *count* is **\***, then all of the digits in *arg* will be formatted. If *count* is omitted, then one digit will be formatted. If the number of bits formatted does not end at a byte boundary, the remaining bits of the last byte will be zeros. For example, 
```
**binary format** b5b* 11100 111000011010
```
 will return a string equivalent to **\x07\x87\x05**. 

**B**
 This form is the same as **b** except that the bits are stored in high-to-low order within each byte. For example, 
```
**binary format** B5B* 11100 111000011010
```
 will return a string equivalent to **\xe0\xe1\xa0**. 

**H**
 Stores a string of *count* hexadecimal digits in high-to-low within each byte in the output string. *Arg* must contain a sequence of characters in the set “0123456789abcdefABCDEF”. The resulting bytes are emitted in first to last order with the hex digits being formatted in high-to-low order within each byte. If *arg* has fewer than *count* digits, then zeros will be used for the remaining digits. If *arg* has more than the specified number of digits, the extra digits will be ignored. If *count* is **\***, then all of the digits in *arg* will be formatted. If *count* is omitted, then one digit will be formatted. If the number of digits formatted does not end at a byte boundary, the remaining bits of the last byte will be zeros. For example, 
```
**binary format** H3H*H2 ab DEF 987
```
 will return a string equivalent to **\xab\x00\xde\xf0\x98**. 

**h**
 This form is the same as **H** except that the digits are stored in low-to-high order within each byte. This is seldom required. For example, 
```
**binary format** h3h*h2 AB def 987
```
 will return a string equivalent to **\xba\x00\xed\x0f\x89**. 

**c**
 Stores one or more 8-bit integer values in the output string. If no *count* is specified, then *arg* must consist of an integer value. If *count* is specified, *arg* must consist of a list containing at least that many integers. The low-order 8 bits of each integer are stored as a one-byte value at the cursor position. If *count* is **\***, then all of the integers in the list are formatted. If the number of elements in the list is greater than *count*, then the extra elements are ignored. For example, 
```
**binary format** c3cc* {3 -3 128 1} 260 {2 5}
```
 will return a string equivalent to **\x03\xfd\x80\x04\x02\x05**, whereas 
```
**binary format** c {2 5}
```
 will generate an error. 

**s**
 This form is the same as **c** except that it stores one or more 16-bit integers in little-endian byte order in the output string. The low-order 16-bits of each integer are stored as a two-byte value at the cursor position with the least significant byte stored first. For example, 
```
**binary format** s3 {3 -3 258 1}
```
 will return a string equivalent to **\x03\x00\xfd\xff\x02\x01**. 

**S**
 This form is the same as **s** except that it stores one or more 16-bit integers in big-endian byte order in the output string. For example, 
```
**binary format** S3 {3 -3 258 1}
```
 will return a string equivalent to **\x00\x03\xff\xfd\x01\x02**. 

**t**
 This form (mnemonically *tiny*) is the same as **s** and **S** except that it stores the 16-bit integers in the output string in the native byte order of the machine where the Tcl script is running. To determine what the native byte order of the machine is, refer to the **byteOrder** element of the **[tcl\_platform](tclvars.htm)** array. 

**i**
 This form is the same as **c** except that it stores one or more 32-bit integers in little-endian byte order in the output string. The low-order 32-bits of each integer are stored as a four-byte value at the cursor position with the least significant byte stored first. For example, 
```
**binary format** i3 {3 -3 65536 1}
```
 will return a string equivalent to **\x03\x00\x00\x00\xfd\xff\xff\xff\x00\x00\x01\x00**

**I**
 This form is the same as **i** except that it stores one or more one or more 32-bit integers in big-endian byte order in the output string. For example, 
```
**binary format** I3 {3 -3 65536 1}
```
 will return a string equivalent to **\x00\x00\x00\x03\xff\xff\xff\xfd\x00\x01\x00\x00**

**n**
 This form (mnemonically *number* or *normal*) is the same as **i** and **I** except that it stores the 32-bit integers in the output string in the native byte order of the machine where the Tcl script is running. To determine what the native byte order of the machine is, refer to the **byteOrder** element of the **[tcl\_platform](tclvars.htm)** array. 

**w**
 This form is the same as **c** except that it stores one or more 64-bit integers in little-endian byte order in the output string. The low-order 64-bits of each integer are stored as an eight-byte value at the cursor position with the least significant byte stored first. For example, 
```
**binary format** w 7810179016327718216
```
 will return the string **HelloTcl**

**W**
 This form is the same as **w** except that it stores one or more one or more 64-bit integers in big-endian byte order in the output string. For example, 
```
**binary format** Wc 4785469626960341345 110
```
 will return the string **BigEndian**

**m**
 This form (mnemonically the mirror of **w**) is the same as **w** and **W** except that it stores the 64-bit integers in the output string in the native byte order of the machine where the Tcl script is running. To determine what the native byte order of the machine is, refer to the **byteOrder** element of the **[tcl\_platform](tclvars.htm)** array. 

**f**
 This form is the same as **c** except that it stores one or more one or more single-precision floating point numbers in the machine's native representation in the output string. This representation is not portable across architectures, so it should not be used to communicate floating point numbers across the network. The size of a floating point number may vary across architectures, so the number of bytes that are generated may vary. If the value overflows the machine's native representation, then the value of FLT\_MAX as defined by the system will be used instead. Because Tcl uses double-precision floating point numbers internally, there may be some loss of precision in the conversion to single-precision. For example, on a Windows system running on an Intel Pentium processor, 
```
**binary format** f2 {1.6 3.4}
```
 will return a string equivalent to **\xcd\xcc\xcc\x3f\x9a\x99\x59\x40**. 

**r**
 This form (mnemonically *real*) is the same as **f** except that it stores the single-precision floating point numbers in little-endian order. This conversion only produces meaningful output when used on machines which use the IEEE floating point representation (very common, but not universal.) 

**R**
 This form is the same as **r** except that it stores the single-precision floating point numbers in big-endian order. 

**d**
 This form is the same as **f** except that it stores one or more one or more double-precision floating point numbers in the machine's native representation in the output string. For example, on a Windows system running on an Intel Pentium processor, 
```
**binary format** d1 {1.6}
```
 will return a string equivalent to **\x9a\x99\x99\x99\x99\x99\xf9\x3f**. 

**q**
 This form (mnemonically the mirror of **d**) is the same as **d** except that it stores the double-precision floating point numbers in little-endian order. This conversion only produces meaningful output when used on machines which use the IEEE floating point representation (very common, but not universal.) 

**Q**
 This form is the same as **q** except that it stores the double-precision floating point numbers in big-endian order. 

**x**
 Stores *count* null bytes in the output string. If *count* is not specified, stores one null byte. If *count* is **\***, generates an error. This type does not consume an argument. For example, 
```
**binary format** a3xa3x2a3 abc def ghi
```
 will return a string equivalent to **abc\000def\000\000ghi**. 

**X**
 Moves the cursor back *count* bytes in the output string. If *count* is **\*** or is larger than the current cursor position, then the cursor is positioned at location 0 so that the next byte stored will be the first byte in the result string. If *count* is omitted then the cursor is moved back one byte. This type does not consume an argument. For example, 
```
**binary format** a3X*a3X2a3 abc def ghi
```
 will return **dghi**. 

**@**
 Moves the cursor to the absolute location in the output string specified by *count*. Position 0 refers to the first byte in the output string. If *count* refers to a position beyond the last byte stored so far, then null bytes will be placed in the uninitialized locations and the cursor will be placed at the specified location. If *count* is **\***, then the cursor is moved to the current end of the output string. If *count* is omitted, then an error will be generated. This type does not consume an argument. For example, 
```
**binary format** a5@2a1@*a3@10a1 abcde f ghi j
```
 will return **abfdeghi\000\000j**. 

 Binary scan
-----------

 The **binary scan** command parses fields from a binary string, returning the number of conversions performed. *String* gives the input bytes to be parsed (one byte per character, and characters not representable as a byte have their high bits chopped) and *formatString* indicates how to parse it. Each *varName* gives the name of a variable; when a field is scanned from *string* the result is assigned to the corresponding variable.  As with **binary format**, the *formatString* consists of a sequence of zero or more field specifiers separated by zero or more spaces. Each field specifier is a single type character followed by an optional flag character followed by an optional numeric *count*. Most field specifiers consume one argument to obtain the variable into which the scanned values should be placed. The type character specifies how the binary data is to be interpreted. The *count* typically indicates how many items of the specified type are taken from the data. If present, the *count* is a non-negative decimal integer or **\***, which normally indicates that all of the remaining items in the data are to be used. If there are not enough bytes left after the current cursor position to satisfy the current field specifier, then the corresponding variable is left untouched and **binary scan** returns immediately with the number of variables that were set. If there are not enough arguments for all of the fields in the format string that consume arguments, then an error is generated. The flag character “u” may be given to cause some types to be read as unsigned values. The flag is accepted for all field types but is ignored for non-integer fields. 


 A similar example as with **binary format** should explain the relation between field specifiers and arguments in case of the binary scan subcommand: 



```
**binary scan** $bytes s3s first second
```
  This command (provided the binary string in the variable *bytes* is long enough) assigns a list of three integers to the variable *first* and assigns a single value to the variable *second*. If *bytes* contains fewer than 8 bytes (i.e. four 2-byte integers), no assignment to *second* will be made, and if *bytes* contains fewer than 6 bytes (i.e. three 2-byte integers), no assignment to *first* will be made. Hence: 



```
puts [**binary scan** abcdefg s3s first second]
puts $first
puts $second
```
 will print (assuming neither variable is set previously): 
```
1
25185 25699 26213
can't read "second": no such variable
```
  It is *important* to note that the **c**, **s**, and **S** (and **i** and **I** on 64bit systems) will be scanned into long data size values. In doing this, values that have their high bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints), will be sign extended. Thus the following will occur: 



```
set signShort [**binary format** s1 0x8000]
**binary scan** $signShort s1 val; *# val == 0xFFFF8000*
```
 If you require unsigned values you can include the “u” flag character following the field type. For example, to read an unsigned short value: 
```
set signShort [**binary format** s1 0x8000]
**binary scan** $signShort su1 val; *# val == 0x00008000*
```
  Each type-count pair moves an imaginary cursor through the binary data, reading bytes from the current position. The cursor is initially at position 0 at the beginning of the data. The type may be any one of the following characters: 


 **a**
 The data is a byte string of length *count*. If *count* is **\***, then all of the remaining bytes in *string* will be scanned into the variable. If *count* is omitted, then one byte will be scanned. All bytes scanned will be interpreted as being characters in the range \u0000-\u00ff so the **[encoding convertfrom](encoding.htm)** command will be needed if the string is not a binary string or a string encoded in ISO 8859-1. For example, 
```
**binary scan** abcde\000fghi a6a10 var1 var2
```
 will return **1** with the string equivalent to **abcde\000** stored in *var1* and *var2* left unmodified, and 
```
**binary scan** \342\202\254 a* var1
set var2 [encoding convertfrom utf-8 $var1]
```
 will store a Euro-currency character in *var2*. 

**A**
 This form is the same as **a**, except trailing blanks and nulls are stripped from the scanned value before it is stored in the variable. For example, 
```
**binary scan** "abc efghi  \000" A* var1
```
 will return **1** with **abc efghi** stored in *var1*. 

**b**
 The data is turned into a string of *count* binary digits in low-to-high order represented as a sequence of “1” and “0” characters. The data bytes are scanned in first to last order with the bits being taken in low-to-high order within each byte. Any extra bits in the last byte are ignored. If *count* is **\***, then all of the remaining bits in *string* will be scanned. If *count* is omitted, then one bit will be scanned. For example, 
```
**binary scan** \x07\x87\x05 b5b* var1 var2
```
 will return **2** with **11100** stored in *var1* and **1110000110100000** stored in *var2*. 

**B**
 This form is the same as **b**, except the bits are taken in high-to-low order within each byte. For example, 
```
**binary scan** \x70\x87\x05 B5B* var1 var2
```
 will return **2** with **01110** stored in *var1* and **1000011100000101** stored in *var2*. 

**H**
 The data is turned into a string of *count* hexadecimal digits in high-to-low order represented as a sequence of characters in the set “0123456789abcdef”. The data bytes are scanned in first to last order with the hex digits being taken in high-to-low order within each byte. Any extra bits in the last byte are ignored. If *count* is **\***, then all of the remaining hex digits in *string* will be scanned. If *count* is omitted, then one hex digit will be scanned. For example, 
```
**binary scan** \x07\xC6\x05\x1f\x34 H3H* var1 var2
```
 will return **2** with **07c** stored in *var1* and **051f34** stored in *var2*. 

**h**
 This form is the same as **H**, except the digits are taken in reverse (low-to-high) order within each byte. For example, 
```
**binary scan** \x07\x86\x05\x12\x34 h3h* var1 var2
```
 will return **2** with **706** stored in *var1* and **502143** stored in *var2*. Note that most code that wishes to parse the hexadecimal digits from multiple bytes in order should use the **H** format. 



**c**
 The data is turned into *count* 8-bit signed integers and stored in the corresponding variable as a list. If *count* is **\***, then all of the remaining bytes in *string* will be scanned. If *count* is omitted, then one 8-bit integer will be scanned. For example, 
```
**binary scan** \x07\x86\x05 c2c* var1 var2
```
 will return **2** with **7 -122** stored in *var1* and **5** stored in *var2*. Note that the integers returned are signed, but they can be converted to unsigned 8-bit quantities using an expression like: 
```
set num [expr { $num & 0xff }]
```


**s**
 The data is interpreted as *count* 16-bit signed integers represented in little-endian byte order. The integers are stored in the corresponding variable as a list. If *count* is **\***, then all of the remaining bytes in *string* will be scanned. If *count* is omitted, then one 16-bit integer will be scanned. For example, 
```
**binary scan** \x05\x00\x07\x00\xf0\xff s2s* var1 var2
```
 will return **2** with **5 7** stored in *var1* and **-16** stored in *var2*. Note that the integers returned are signed, but they can be converted to unsigned 16-bit quantities using an expression like: 
```
set num [expr { $num & 0xffff }]
```


**S**
 This form is the same as **s** except that the data is interpreted as *count* 16-bit signed integers represented in big-endian byte order. For example, 
```
**binary scan** \x00\x05\x00\x07\xff\xf0 S2S* var1 var2
```
 will return **2** with **5 7** stored in *var1* and **-16** stored in *var2*. 

**t**
 The data is interpreted as *count* 16-bit signed integers represented in the native byte order of the machine running the Tcl script. It is otherwise identical to **s** and **S**. To determine what the native byte order of the machine is, refer to the **byteOrder** element of the **[tcl\_platform](tclvars.htm)** array. 

**i**
 The data is interpreted as *count* 32-bit signed integers represented in little-endian byte order. The integers are stored in the corresponding variable as a list. If *count* is **\***, then all of the remaining bytes in *string* will be scanned. If *count* is omitted, then one 32-bit integer will be scanned. For example, 
```
set str \x05\x00\x00\x00\x07\x00\x00\x00\xf0\xff\xff\xff
**binary scan** $str i2i* var1 var2
```
 will return **2** with **5 7** stored in *var1* and **-16** stored in *var2*. Note that the integers returned are signed, but they can be converted to unsigned 32-bit quantities using an expression like: 
```
set num [expr { $num & 0xffffffff }]
```


**I**
 This form is the same as **I** except that the data is interpreted as *count* 32-bit signed integers represented in big-endian byte order. For example, 
```
set str \x00\x00\x00\x05\x00\x00\x00\x07\xff\xff\xff\xf0
**binary scan** $str I2I* var1 var2
```
 will return **2** with **5 7** stored in *var1* and **-16** stored in *var2*. 

**n**
 The data is interpreted as *count* 32-bit signed integers represented in the native byte order of the machine running the Tcl script. It is otherwise identical to **i** and **I**. To determine what the native byte order of the machine is, refer to the **byteOrder** element of the **[tcl\_platform](tclvars.htm)** array. 

**w**
 The data is interpreted as *count* 64-bit signed integers represented in little-endian byte order. The integers are stored in the corresponding variable as a list. If *count* is **\***, then all of the remaining bytes in *string* will be scanned. If *count* is omitted, then one 64-bit integer will be scanned. For example, 
```
set str \x05\x00\x00\x00\x07\x00\x00\x00\xf0\xff\xff\xff
**binary scan** $str wi* var1 var2
```
 will return **2** with **30064771077** stored in *var1* and **-16** stored in *var2*. Note that the integers returned are signed and cannot be represented by Tcl as unsigned values. 

**W**
 This form is the same as **w** except that the data is interpreted as *count* 64-bit signed integers represented in big-endian byte order. For example, 
```
set str \x00\x00\x00\x05\x00\x00\x00\x07\xff\xff\xff\xf0
**binary scan** $str WI* var1 var2
```
 will return **2** with **21474836487** stored in *var1* and **-16** stored in *var2*. 

**m**
 The data is interpreted as *count* 64-bit signed integers represented in the native byte order of the machine running the Tcl script. It is otherwise identical to **w** and **W**. To determine what the native byte order of the machine is, refer to the **byteOrder** element of the **[tcl\_platform](tclvars.htm)** array. 

**f**
 The data is interpreted as *count* single-precision floating point numbers in the machine's native representation. The floating point numbers are stored in the corresponding variable as a list. If *count* is **\***, then all of the remaining bytes in *string* will be scanned. If *count* is omitted, then one single-precision floating point number will be scanned. The size of a floating point number may vary across architectures, so the number of bytes that are scanned may vary. If the data does not represent a valid floating point number, the resulting value is undefined and compiler dependent. For example, on a Windows system running on an Intel Pentium processor, 
```
**binary scan** \x3f\xcc\xcc\xcd f var1
```
 will return **1** with **1.6000000238418579** stored in *var1*. 

**r**
 This form is the same as **f** except that the data is interpreted as *count* single-precision floating point number in little-endian order. This conversion is not portable to the minority of systems not using IEEE floating point representations. 

**R**
 This form is the same as **f** except that the data is interpreted as *count* single-precision floating point number in big-endian order. This conversion is not portable to the minority of systems not using IEEE floating point representations. 

**d**
 This form is the same as **f** except that the data is interpreted as *count* double-precision floating point numbers in the machine's native representation. For example, on a Windows system running on an Intel Pentium processor, 
```
**binary scan** \x9a\x99\x99\x99\x99\x99\xf9\x3f d var1
```
 will return **1** with **1.6000000000000001** stored in *var1*. 

**q**
 This form is the same as **d** except that the data is interpreted as *count* double-precision floating point number in little-endian order. This conversion is not portable to the minority of systems not using IEEE floating point representations. 

**Q**
 This form is the same as **d** except that the data is interpreted as *count* double-precision floating point number in big-endian order. This conversion is not portable to the minority of systems not using IEEE floating point representations. 

**x**
 Moves the cursor forward *count* bytes in *string*. If *count* is **\*** or is larger than the number of bytes after the current cursor position, then the cursor is positioned after the last byte in *string*. If *count* is omitted, then the cursor is moved forward one byte. Note that this type does not consume an argument. For example, 
```
**binary scan** \x01\x02\x03\x04 x2H* var1
```
 will return **1** with **0304** stored in *var1*. 

**X**
 Moves the cursor back *count* bytes in *string*. If *count* is **\*** or is larger than the current cursor position, then the cursor is positioned at location 0 so that the next byte scanned will be the first byte in *string*. If *count* is omitted then the cursor is moved back one byte. Note that this type does not consume an argument. For example, 
```
**binary scan** \x01\x02\x03\x04 c2XH* var1 var2
```
 will return **2** with **1 2** stored in *var1* and **020304** stored in *var2*. 

**@**
 Moves the cursor to the absolute location in the data string specified by *count*. Note that position 0 refers to the first byte in *string*. If *count* refers to a position beyond the end of *string*, then the cursor is positioned after the last byte. If *count* is omitted, then an error will be generated. For example, 
```
**binary scan** \x01\x02\x03\x04 c2@1H* var1 var2
```
 will return **2** with **1 2** stored in *var1* and **020304** stored in *var2*. 

 Portability issues
------------------

 The **r**, **R**, **q** and **Q** conversions will only work reliably for transferring data between computers which are all using IEEE floating point representations. This is very common, but not universal. To transfer floating-point numbers portably between all architectures, use their textual representation (as produced by **[format](format.htm)**) instead. Examples
--------

 This is a procedure to write a Tcl string to a binary-encoded channel as UTF-8 data preceded by a length word: 

```
proc *writeString* {channel string} {
    set data [encoding convertto utf-8 $string]
    puts -nonewline [**binary format** Ia* \
            [string length $data] $data]
}
```
  This procedure reads a string from a channel that was written by the previously presented *writeString* procedure: 



```
proc *readString* {channel} {
    if {![**binary scan** [read $channel 4] I length]} {
        error "missing length"
    }
    set data [read $channel $length]
    return [encoding convertfrom utf-8 $data]
}
```
  This converts the contents of a file (named in the variable *filename*) to base64 and prints them: 



```
set f [open $filename rb]
set data [read $f]
close $f
puts [**binary encode** base64 -maxlen 64 $data]
```
 See also
--------

 **[encoding](encoding.htm)**, **[format](format.htm)**, **[scan](scan.htm)**, **[string](string.htm)**, **[tcl\_platform](tclvars.htm)** Copyright © 1997 by Sun Microsystems, Inc.  
 Copyright © 2008 by Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/binary.htm>

ttk\_menubutton
===============

  
[NAME](ttk_menubutton.htm#M2) ttk::menubutton — Widget that pops down a menu when pressed 
[SYNOPSIS](ttk_menubutton.htm#M3) 
[DESCRIPTION](ttk_menubutton.htm#M4) 
[STANDARD OPTIONS](ttk_menubutton.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-compound, compound, Compound](ttk_widget.htm#M-compound) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-image, image, Image](ttk_widget.htm#M-image) 
[-state, state, State](ttk_widget.htm#M-state) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 
[-text, text, Text](ttk_widget.htm#M-text) 
[-textvariable, textVariable, Variable](ttk_widget.htm#M-textvariable) 
[-underline, underline, Underline](ttk_widget.htm#M-underline) 
[-width, width, Width](ttk_widget.htm#M-width) 










 
[WIDGET-SPECIFIC OPTIONS](ttk_menubutton.htm#M6)  
[-direction, direction, Direction](ttk_menubutton.htm#M7) 
[-menu, menu, Menu](ttk_menubutton.htm#M8) 

 
[WIDGET COMMAND](ttk_menubutton.htm#M9) 
[STANDARD STYLES](ttk_menubutton.htm#M10) 
[SEE ALSO](ttk_menubutton.htm#M11) 
[KEYWORDS](ttk_menubutton.htm#M12) 








 Name
----

 ttk::menubutton — Widget that pops down a menu when pressed Synopsis
--------

 **ttk::menubutton** *pathName* ?*options*?  
 Description
-----------

 A **ttk::menubutton** widget displays a textual label and/or image, and displays a menu when pressed. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-compound, compound, Compound](ttk_widget.htm#M-compound)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-image, image, Image](ttk_widget.htm#M-image)** 
**[-state, state, State](ttk_widget.htm#M-state)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 
**[-text, text, Text](ttk_widget.htm#M-text)** 
**[-textvariable, textVariable, Variable](ttk_widget.htm#M-textvariable)** 
**[-underline, underline, Underline](ttk_widget.htm#M-underline)** 
**[-width, width, Width](ttk_widget.htm#M-width)** 










 Widget-specific options
-----------------------

  Command-Line Name: **-direction** Database Name: **direction** Database Class: **Direction** 


Specifies where the menu is to be popped up relative to the menubutton. One of: **above**, **below**, **left**, **right**, or **flush**. The default is **below**. **flush** pops the menu up directly over the menubutton. 

Command-Line Name: **-menu** Database Name: **[menu](menu.htm)** Database Class: **[Menu](menu.htm)** 


Specifies the path name of the menu associated with the menubutton. To be on the safe side, the menu ought to be a direct child of the menubutton. 
 Widget command
--------------

 Menubutton widgets support the standard **cget**, **configure**, **identify**, **instate**, and **state** methods. No other widget methods are used. Standard styles
---------------

 **Ttk::menubutton** widgets support the **Toolbutton** style in all standard themes, which is useful for creating widgets for toolbars. See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[menu](menu.htm)**, **[menubutton](menubutton.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_menubutton.htm>

tkvars
======

  
[NAME](tkvars.htm#M2) geometry, tk\_library, tk\_patchLevel, tk\_strictMotif, tk\_version — Variables used or set by Tk 
[DESCRIPTION](tkvars.htm#M3)  
[**tk\_library**](tkvars.htm#M4) 
[**tk\_patchLevel**](tkvars.htm#M5) 
[**tk\_strictMotif**](tkvars.htm#M6) 
[**tk\_version**](tkvars.htm#M7) 



 
[INTERNAL AND DEBUGGING VARIABLES](tkvars.htm#M8)  
[**tk::Priv**](tkvars.htm#M9) 
[**tk\_textRedraw**](tkvars.htm#M10) 
[**tk\_textRelayout**](tkvars.htm#M11) 


 
[OTHER GLOBAL VARIABLES](tkvars.htm#M12)  
[**geometry**](tkvars.htm#M13) 
 
[SEE ALSO](tkvars.htm#M14) 
[KEYWORDS](tkvars.htm#M15) 





 Name
----

 geometry, tk\_library, tk\_patchLevel, tk\_strictMotif, tk\_version — Variables used or set by Tk Description
-----------

 The following Tcl variables are either set or used by Tk at various times in its execution: 
 **tk\_library**
 This variable holds the file name for a directory containing a library of Tcl scripts related to Tk. These scripts include an initialization file that is normally processed whenever a Tk application starts up, plus other files containing procedures that implement default behaviors for widgets.  The initial value of **[tcl\_library](../tclcmd/tclvars.htm)** is set when Tk is added to an interpreter; this is done by searching several different directories until one is found that contains an appropriate Tk startup script. If the **TK\_LIBRARY** environment variable exists, then the directory it names is checked first. If **TK\_LIBRARY** is not set or does not refer to an appropriate directory, then Tk checks several other directories based on a compiled-in default location, the location of the Tcl library directory, the location of the binary containing the application, and the current working directory. 


The variable can be modified by an application to switch to a different library. 



**tk\_patchLevel**
 Contains a dot-separated sequence of decimal integers giving the current patch level for Tk. The patch level is incremented for each new release or patch, and it uniquely identifies an official version of Tk.  This value is normally the same as the result of “**[package require](../tclcmd/package.htm)** **Tk**”. 



**tk\_strictMotif**
 This variable is set to zero by default. If an application sets it to one, then Tk attempts to adhere as closely as possible to Motif look-and-feel standards. For example, active elements such as buttons and scrollbar sliders will not change color when the pointer passes over them. Modern applications should not normally set this variable. 

**tk\_version**
 Tk sets this variable in the interpreter for each application. The variable holds the current version number of the Tk library in the form *major*.*minor*. *Major* and *minor* are integers. The major version number increases in any Tk release that includes changes that are not backward compatible (i.e. whenever existing Tk applications and scripts may have to change to work with the new release). The minor version number increases with each new release of Tk, except that it resets to zero whenever the major version number changes. 

 ### Internal and debugging variables

 These variables should not normally be set by user code. 
 **tk::Priv**
 This variable is an array containing several pieces of information that are private to Tk. The elements of **tk::Priv** are used by Tk library procedures and default bindings. They should not be accessed by any code outside Tk. 

**tk\_textRedraw**
**tk\_textRelayout**
 These variables are set by text widgets when they have debugging turned on. The values written to these variables can be used to test or debug text widget operations. These variables are mostly used by Tk's test suite. 

 Other global variables
----------------------

 The following variables are only guaranteed to exist in **[wish](../usercmd/wish.htm)** executables; the Tk library does not define them itself but many Tk environments do. 
 **geometry**
 If set, contains the user-supplied geometry specification to use for the main Tk window. 

 See also
--------

 **[package](../tclcmd/package.htm)**, **[tclvars](../tclcmd/tclvars.htm)**, **[wish](../usercmd/wish.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/tkvars.htm>

tsv
===

  
[NAME](tsv.htm#M2) tsv — Part of the Tcl threading extension allowing script level manipulation of data shared between threads . 
[SYNOPSIS](tsv.htm#M3) 
[DESCRIPTION](tsv.htm#M4) 
[ELEMENT COMMANDS](tsv.htm#M5)  
[**tsv::names** ?pattern?](tsv.htm#M6) 
[**tsv::object** *varname* *element*](tsv.htm#M7) 
[**tsv::set** *varname* *element* ?value?](tsv.htm#M8) 
[**tsv::get** *varname* *element* ?namedvar?](tsv.htm#M9) 
[**tsv::unset** *varname* ?element?](tsv.htm#M10) 
[**tsv::exists** *varname* *element*](tsv.htm#M11) 
[**tsv::pop** *varname* *element*](tsv.htm#M12) 
[**tsv::move** *varname* *oldname* *newname*](tsv.htm#M13) 
[**tsv::incr** *varname* *element* ?count?](tsv.htm#M14) 
[**tsv::append** *varname* *element* *value* ?value . . .?](tsv.htm#M15) 
[**tsv::lock** *varname* *arg* ?arg . . .?](tsv.htm#M16) 
[**tsv::handlers**](tsv.htm#M17) 











 
[LIST COMMANDS](tsv.htm#M18)  
[**tsv::lappend** *varname* *element* *value* ?value . . .?](tsv.htm#M19) 
[**tsv::linsert** *varname* *element* *index* *value* ?value . . .?](tsv.htm#M20) 
[**tsv::lreplace** *varname* *element* *first* *last* ?value . . .?](tsv.htm#M21) 
[**tsv::llength** *varname* *element*](tsv.htm#M22) 
[**tsv::lindex** *varname* *element* ?index?](tsv.htm#M23) 
[**tsv::lrange** *varname* *element* *from* *to*](tsv.htm#M24) 
[**tsv::lsearch** *varname* *element* ?options? *pattern*](tsv.htm#M25) 
[**tsv::lset** *varname* *element* *index* ?index . . .? *value*](tsv.htm#M26) 
[**tsv::lpop** *varname* *element* ?index?](tsv.htm#M27) 
[**tsv::lpush** *varname* *element* ?index?](tsv.htm#M28) 









 
[ARRAY COMMANDS](tsv.htm#M29)  
[**tsv::array set** *varname* *list*](tsv.htm#M30) 
[**tsv::array get** *varname* ?pattern?](tsv.htm#M31) 
[**tsv::array names** *varname* ?pattern?](tsv.htm#M32) 
[**tsv::array size** *varname*](tsv.htm#M33) 
[**tsv::array reset** *varname* *list*](tsv.htm#M34) 
[**tsv::array bind** *varname* *handle*](tsv.htm#M35) 
[**tsv::array unbind** *varname*](tsv.htm#M36) 
[**tsv::array isbound** *varname*](tsv.htm#M37) 







 
[KEYED LIST COMMANDS](tsv.htm#M38)  
[**tsv::keyldel** *varname* *keylist* *key*](tsv.htm#M39) 
[**tsv::keylget** *varname* *keylist* *key* ?retvar?](tsv.htm#M40) 
[**tsv::keylkeys** *varname* *keylist* ?key?](tsv.htm#M41) 
[**tsv::keylset** *varname* *keylist* *key* *value* ?key value . .?](tsv.htm#M42) 



 
[DISCUSSION](tsv.htm#M43) 
[CREDITS](tsv.htm#M44) 
[SEE ALSO](tsv.htm#M45) 
[KEYWORDS](tsv.htm#M46) 










 Name
----

 tsv — Part of the Tcl threading extension allowing script level manipulation of data shared between threads . Synopsis
--------

 package require **Tcl 8 .4**  
 package require **Thread ?2 .8?**  
 **tsv::names** ?pattern?  
 **tsv::object** *varname* *element*  
 **tsv::set** *varname* *element* ?value?  
 **tsv::get** *varname* *element* ?namedvar?  
 **tsv::unset** *varname* ?element?  
 **tsv::exists** *varname* *element*  
 **tsv::pop** *varname* *element*  
 **tsv::move** *varname* *oldname* *newname*  
 **tsv::incr** *varname* *element* ?count?  
 **tsv::append** *varname* *element* *value* ?value . . .?  
 **tsv::lock** *varname* *arg* ?arg . . .?  
 **tsv::handlers**  
 **tsv::lappend** *varname* *element* *value* ?value . . .?  
 **tsv::linsert** *varname* *element* *index* *value* ?value . . .?  
 **tsv::lreplace** *varname* *element* *first* *last* ?value . . .?  
 **tsv::llength** *varname* *element*  
 **tsv::lindex** *varname* *element* ?index?  
 **tsv::lrange** *varname* *element* *from* *to*  
 **tsv::lsearch** *varname* *element* ?options? *pattern*  
 **tsv::lset** *varname* *element* *index* ?index . . .? *value*  
 **tsv::lpop** *varname* *element* ?index?  
 **tsv::lpush** *varname* *element* ?index?  
 **tsv::array set** *varname* *list*  
 **tsv::array get** *varname* ?pattern?  
 **tsv::array names** *varname* ?pattern?  
 **tsv::array size** *varname*  
 **tsv::array reset** *varname* *list*  
 **tsv::array bind** *varname* *handle*  
 **tsv::array unbind** *varname*  
 **tsv::array isbound** *varname*  
 **tsv::keyldel** *varname* *keylist* *key*  
 **tsv::keylget** *varname* *keylist* *key* ?retvar?  
 **tsv::keylkeys** *varname* *keylist* ?key?  
 **tsv::keylset** *varname* *keylist* *key* *value* ?key value . .?  
 Description
-----------

 This section describes commands implementing thread shared variables . A thread shared variable is very similar to a Tcl array but in contrast to a Tcl array it is created in shared memory and can be accessed from many threads at the same time . Important feature of thread shared variable is that each access to the variable is internaly protected by a mutex so script programmer does not have to take care about locking the variable himself .  Thread shared variables are not bound to any thread explicitly . That means that when a thread which created any of thread shared variables exits, the variable and associated memory is not unset/reclaimed . User has to explicitly unset the variable to reclaim the memory consumed by the variable . 


Element commands
----------------

  
**tsv::names** ?pattern?
 Returns names of shared variables matching optional ?pattern? or all known variables if pattern is ommited . 


**tsv::object** *varname* *element*

 Creates object accessor command for the *element* in the shared variable *varname* . Using this command, one can apply most of the other shared variable commands as method functions of the element object command . The object command is automatically deleted when the element which this command is pointing to is unset . 
```
% tsv::set foo bar "A shared string"
    % set string [tsv::object foo bar]
    % $string append " appended"
    => A shared string appended
```



**tsv::set** *varname* *element* ?value?
 Sets the value of the *element* in the shared variable *varname* to *value* and returns the value to caller . The *value* may be ommited, in which case the command will return the current value of the element . If the element cannot be found, error is triggered . 


**tsv::get** *varname* *element* ?namedvar?
 Retrieves the value of the *element* from the shared variable *varname* . If the optional argument *namedvar* is given, the value is stored in the named variable . Return value of the command depends of the existence of the optional argument *namedvar* . If the argument is ommited and the requested element cannot be found in the shared array, the command triggers error . If, however, the optional argument is given on the command line, the command returns true (1) if the element is found or false (0) if the element is not found . 


**tsv::unset** *varname* ?element?
 Unsets the *element* from the shared variable *varname* . If the optional element is not given, it deletes the variable . 


**tsv::exists** *varname* *element*

 Checks wether the *element* exists in the shared variable *varname* and returns true (1) if it does or false (0) if it doesn't . 


**tsv::pop** *varname* *element*

 Returns value of the *element* in the shared variable *varname* and unsets the element, all in one atomic operation . 


**tsv::move** *varname* *oldname* *newname*

 Renames the element *oldname* to the *newname* in the shared variable *varname* . This effectively performs an get/unset/set sequence of operations but all in one atomic step . 


**tsv::incr** *varname* *element* ?count?
 Similar to standard Tcl **[incr](../tclcmd/incr.htm)** command but increments the value of the *element* in shared variaboe *varname* instead of the Tcl variable . 


**tsv::append** *varname* *element* *value* ?value . . .?
 Similar to standard Tcl **[append](../tclcmd/append.htm)** command but appends one or more values to the *element* in shared variable *varname* instead of the Tcl variable . 


**tsv::lock** *varname* *arg* ?arg . . .?
 This command concatenates passed arguments and evaluates the resulting script under the internal mutex protection . During the script evaluation, the entire shared variable is locked . For shared variable commands within the script, internal locking is disabled so no deadlock can occur . It is also allowed to unset the shared variable from within the script . The shared variable is automatically created if it did not exists at the time of the first lock operation . 
```
% tsv::lock foo {
        tsv::lappend foo bar 1
        tsv::lappend foo bar 2
        puts stderr [tsv::set foo bar]
        tsv::unset foo
    }
```


**tsv::handlers**
 Returns the names of all persistent storage handlers enabled at compile time . See **[ARRAY COMMANDS](#M29)** for details . 


List commands
-------------

 Those command are similar to the equivalently named Tcl command . The difference is that they operate on elements of shared arrays . 
 
**tsv::lappend** *varname* *element* *value* ?value . . .?
 Similar to standard Tcl **[lappend](../tclcmd/lappend.htm)** command but appends one or more values to the *element* in shared variable *varname* instead of the Tcl variable . 


**tsv::linsert** *varname* *element* *index* *value* ?value . . .?
 Similar to standard Tcl **[linsert](../tclcmd/linsert.htm)** command but inserts one or more values at the *index* list position in the *element* in the shared variable *varname* instead of the Tcl variable . 


**tsv::lreplace** *varname* *element* *first* *last* ?value . . .?
 Similar to standard Tcl **[lreplace](../tclcmd/lreplace.htm)** command but replaces one or more values between the *first* and *last* position in the *element* of the shared variable *varname* instead of the Tcl variable . 


**tsv::llength** *varname* *element*

 Similar to standard Tcl **[llength](../tclcmd/llength.htm)** command but returns length of the *element* in the shared variable *varname* instead of the Tcl variable . 


**tsv::lindex** *varname* *element* ?index?
 Similar to standard Tcl **[lindex](../tclcmd/lindex.htm)** command but returns the value at the *index* list position of the *element* from the shared variable *varname* instead of the Tcl variable . 


**tsv::lrange** *varname* *element* *from* *to*

 Similar to standard Tcl **[lrange](../tclcmd/lrange.htm)** command but returns values between *from* and *to* list positions from the *element* in the shared variable *varname* instead of the Tcl variable . 


**tsv::lsearch** *varname* *element* ?options? *pattern*

 Similar to standard Tcl **[lsearch](../tclcmd/lsearch.htm)** command but searches the *element* in the shared variable *varname* instead of the Tcl variable . 


**tsv::lset** *varname* *element* *index* ?index . . .? *value*

 Similar to standard Tcl **[lset](../tclcmd/lset.htm)** command but sets the *element* in the shared variable *varname* instead of the Tcl variable . 


**tsv::lpop** *varname* *element* ?index?
 Similar to the standard Tcl **[lindex](../tclcmd/lindex.htm)** command but in addition to returning, it also splices the value out of the *element* from the shared variable *varname* in one atomic operation . In contrast to the Tcl **[lindex](../tclcmd/lindex.htm)** command, this command returns no value to the caller . 


**tsv::lpush** *varname* *element* ?index?
 This command performes the opposite of the **tsv::lpop** command . As its counterpart, it returns no value to the caller . 


Array commands
--------------

 This command supports most of the options of the standard Tcl **[array](../tclcmd/array.htm)** command . In addition to those, it allows binding a shared variable to some persisten storage databases . Currently the persistent options supported are the famous GNU Gdbm and LMDB . These options have to be selected during the package compilation time . The implementation provides hooks for defining other persistency layers, if needed . 
 
**tsv::array set** *varname* *list*

 Does the same as standard Tcl **[array set](../tclcmd/array.htm)** . 


**tsv::array get** *varname* ?pattern?
 Does the same as standard Tcl **[array get](../tclcmd/array.htm)** . 


**tsv::array names** *varname* ?pattern?
 Does the same as standard Tcl **[array names](../tclcmd/array.htm)** . 


**tsv::array size** *varname*

 Does the same as standard Tcl **[array size](../tclcmd/array.htm)** . 


**tsv::array reset** *varname* *list*

 Does the same as standard Tcl **[array set](../tclcmd/array.htm)** but it clears the *varname* and sets new values from the list atomically . 


**tsv::array bind** *varname* *handle*

 Binds the *varname* to the persistent storage *handle* . The format of the *handle* is <handler>:<address>, where <handler> is "gdbm" for GNU Gdbm and "lmdb" for LMDB and <address> is the path to the database file . 


**tsv::array unbind** *varname*

 Unbinds the shared *array* from its bound persistent storage . 


**tsv::array isbound** *varname*

 Returns true (1) if the shared *varname* is bound to some persistent storage or zero (0) if not . 


Keyed list commands
-------------------

 Keyed list commands are borrowed from the TclX package . Keyed lists provide a structured data type built upon standard Tcl lists . This is a functionality similar to structs in the C programming language .  A keyed list is a list in which each element contains a key and value pair . These element pairs are stored as lists themselves, where the key is the first element of the list, and the value is the second . The key-value pairs are referred to as fields . This is an example of a keyed list: 



```
{{NAME  {Frank  Zappa}} {JOB {musician and composer}}}
```
 Fields may contain subfields; ` .' is the separator character . Subfields are actually fields where the value is another keyed list . Thus the following list has the top level fields ID and NAME, and subfields NAME .FIRST and NAME .LAST: 
```
{ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}
```
 There is no limit to the recursive depth of subfields, allowing one to build complex data structures . Keyed lists are constructed and accessed via a number of commands . All keyed list management commands take the name of the variable containing the keyed list as an argument (i .e . passed by reference), rather than passing the list directly . 
 
**tsv::keyldel** *varname* *keylist* *key*

 Delete the field specified by *key* from the keyed list *keylist* in the shared variable *varname* . This removes both the key and the value from the keyed list . 


**tsv::keylget** *varname* *keylist* *key* ?retvar?
 Return the value associated with *key* from the keyed list *keylist* in the shared variable *varname* . If the optional *retvar* is not specified, then the value will be returned as the result of the command . In this case, if key is not found in the list, an error will result .  If *retvar* is specified and *key* is in the list, then the value is returned in the variable *retvar* and the command returns 1 if the key was present within the list . If *key* isn't in the list, the command will return 0, and *retvar* will be left unchanged . If {} is specified for *retvar*, the value is not returned, allowing the Tcl programmer to determine if a *key* is present in a keyed list without setting a variable as a side-effect . 




**tsv::keylkeys** *varname* *keylist* ?key?
 Return the a list of the keys in the keyed list *keylist* in the shared variable *varname* . If *key* is specified, then it is the name of a key field who's subfield keys are to be retrieved . 


**tsv::keylset** *varname* *keylist* *key* *value* ?key value . .?
 Set the value associated with *key*, in the keyed list *keylist* to *value* . If the *keylist* does not exists, it is created . If *key* is not currently in the list, it will be added . If it already exists, *value* replaces the existing value . Multiple keywords and values may be specified, if desired . 


Discussion
----------

 The current implementation of thread shared variables allows for easy and convenient access to data shared between different threads . Internally, the data is stored in Tcl objects and all package commands operate on internal data representation, thus minimizing shimmering and improving performance . Special care has been taken to assure that all object data is properly locked and deep-copied when moving objects between threads .  Due to the internal design of the Tcl core, there is no provision of full integration of shared variables within the Tcl syntax, unfortunately . All access to shared data must be performed with the supplied package commands . Also, variable traces are not supported . But even so, benefits of easy, simple and safe shared data manipulation outweights imposed limitations . 


Credits
-------

 Thread shared variables are inspired by the nsv interface found in AOLserver, a highly scalable Web server from America Online . See also
--------

 **[thread](thread.htm)**, **[tpool](tpool.htm)**, **[ttrace](ttrace.htm)** 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ThreadCmd/tsv.htm>

button
======

  
[NAME](button.htm#M2) button — Create and manipulate 'button' action widgets 
[SYNOPSIS](button.htm#M3) 
[STANDARD OPTIONS](button.htm#M4)  
[-activebackground, activeBackground, Foreground](options.htm#M-activebackground) 
[-activeforeground, activeForeground, Background](options.htm#M-activeforeground) 
[-anchor, anchor, Anchor](options.htm#M-anchor) 
[-background or -bg, background, Background](options.htm#M-background) 
[-bitmap, bitmap, Bitmap](options.htm#M-bitmap) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-compound, compound, Compound](options.htm#M-compound) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-image, image, Image](options.htm#M-image) 
[-justify, justify, Justify](options.htm#M-justify) 
[-padx, padX, Pad](options.htm#M-padx) 
[-pady, padY, Pad](options.htm#M-pady) 
[-relief, relief, Relief](options.htm#M-relief) 
[-repeatdelay, repeatDelay, RepeatDelay](options.htm#M-repeatdelay) 
[-repeatinterval, repeatInterval, RepeatInterval](options.htm#M-repeatinterval) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-text, text, Text](options.htm#M-text) 
[-textvariable, textVariable, Variable](options.htm#M-textvariable) 
[-underline, underline, Underline](options.htm#M-underline) 
[-wraplength, wrapLength, WrapLength](options.htm#M-wraplength) 

























 
[WIDGET-SPECIFIC OPTIONS](button.htm#M5)  
[-command, command, Command](button.htm#M6) 
[-default, default, Default](button.htm#M7) 
[-height, height, Height](button.htm#M8) 
[-overrelief, overRelief, OverRelief](button.htm#M9) 
[-state, state, State](button.htm#M10) 
[-width, width, Width](button.htm#M11) 





 
[DESCRIPTION](button.htm#M12) 
[WIDGET COMMAND](button.htm#M13)  
[*pathName* **cget** *option*](button.htm#M14) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](button.htm#M15) 
[*pathName* **flash**](button.htm#M16) 
[*pathName* **invoke**](button.htm#M17) 



 
[DEFAULT BINDINGS](button.htm#M18) 
[PLATFORM NOTES](button.htm#M19) 
[EXAMPLES](button.htm#M20) 
[SEE ALSO](button.htm#M21) 
[KEYWORDS](button.htm#M22) 










 Name
----

 button — Create and manipulate 'button' action widgets Synopsis
--------

 **button** *pathName* ?*options*?  
 Standard options
----------------

  
**[-activebackground, activeBackground, Foreground](options.htm#M-activebackground)** 
**[-activeforeground, activeForeground, Background](options.htm#M-activeforeground)** 
**[-anchor, anchor, Anchor](options.htm#M-anchor)** 
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-bitmap, bitmap, Bitmap](options.htm#M-bitmap)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-compound, compound, Compound](options.htm#M-compound)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-image, image, Image](options.htm#M-image)** 
**[-justify, justify, Justify](options.htm#M-justify)** 
**[-padx, padX, Pad](options.htm#M-padx)** 
**[-pady, padY, Pad](options.htm#M-pady)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-repeatdelay, repeatDelay, RepeatDelay](options.htm#M-repeatdelay)** 
**[-repeatinterval, repeatInterval, RepeatInterval](options.htm#M-repeatinterval)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-text, text, Text](options.htm#M-text)** 
**[-textvariable, textVariable, Variable](options.htm#M-textvariable)** 
**[-underline, underline, Underline](options.htm#M-underline)** 
**[-wraplength, wrapLength, WrapLength](options.htm#M-wraplength)** 

























 Widget-specific options
-----------------------

  Command-Line Name: **-command** Database Name: **command** Database Class: **Command** 


Specifies a Tcl command to associate with the button. This command is typically invoked when mouse button 1 is released over the button window. 

Command-Line Name: **-default** Database Name: **default** Database Class: **Default** 


Specifies one of three states for the default ring: **normal**, **active**, or **disabled**. In active state, the button is drawn with the platform specific appearance for a default button. In normal state, the button is drawn with the platform specific appearance for a non-default button, leaving enough space to draw the default button appearance. The normal and active states will result in buttons of the same size. In disabled state, the button is drawn with the non-default button appearance without leaving space for the default appearance. The disabled state may result in a smaller button than the active state. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies a desired height for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**); for text it is in lines of text. If this option is not specified, the button's desired height is computed from the size of the image or bitmap or text being displayed in it. 

Command-Line Name: **-overrelief** Database Name: **overRelief** Database Class: **OverRelief** 


Specifies an alternative relief for the button, to be used when the mouse cursor is over the widget. This option can be used to make toolbar buttons, by configuring **-relief flat -overrelief raised**. If the value of this option is the empty string, then no alternative relief is used when the mouse cursor is over the button. The empty string is the default value. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Specifies one of three states for the button: **normal**, **active**, or **disabled**. In normal state the button is displayed using the **-foreground** and **-background** options. The active state is typically used when the pointer is over the button. In active state the button is displayed using the **-activeforeground** and **-activebackground** options. Disabled state means that the button should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the **-disabledforeground** and **-background** options determine how the button is displayed. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies a desired width for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**). For a text button (no image or with **-compound none**) then the width specifies how much space in characters to allocate for the text label. If the width is negative then this specifies a minimum width. If this option is not specified, the button's desired width is computed from the size of the image or bitmap or text being displayed in it. 
 Description
-----------

 The **button** command creates a new window (given by the *pathName* argument) and makes it into a button widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the button such as its colors, font, text, and initial relief. The **button** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  A button is a widget that displays a textual string, bitmap or image. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the **-wraplength** option) and one of the characters may optionally be underlined using the **-underline** option. It can display itself in either of three different ways, according to the **-state** option; it can be made to appear raised, sunken, or flat; and it can be made to flash. When a user invokes the button (by pressing mouse button 1 with the cursor over the button), then the Tcl command specified in the **-command** option is invoked. 


Widget command
--------------

 The **button** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for button widgets: 
 
*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **button** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **button** command. 


*pathName* **flash**

 Flash the button. This is accomplished by redisplaying the button several times, alternating between the configured activebackground and background colors. At the end of the flash the button is left in the same normal/active state as when the command was invoked. This command is ignored if the button's state is **disabled**. 


*pathName* **invoke**

 Invoke the Tcl command associated with the button, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the button. This command is ignored if the button's state is **disabled**. 

 Default bindings
----------------

 Tk automatically creates class bindings for buttons that give them default behavior: 
1. A button activates whenever the mouse passes over it and deactivates whenever the mouse leaves the button. Under Windows, this binding is only active when mouse button 1 has been pressed over the button.
2. A button's relief is changed to sunken whenever mouse button 1 is pressed over the button, and the relief is restored to its original value when button 1 is later released.
3. If mouse button 1 is pressed over a button and later released over the button, the button is invoked. However, if the mouse is not over the button when button 1 is released, then no invocation occurs.
4. When a button has the input focus, the space key causes the button to be invoked.

  If the button's state is **disabled** then none of the above actions occur: the button is completely non-responsive. 


 The behavior of buttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. 


Platform notes
--------------

 On Aqua/Mac OS X, some configuration options are ignored for the purpose of drawing of the widget because they would otherwise conflict with platform guidelines. The **configure** and **cget** subcommands can still manipulate the values, but do not cause any variation to the look of the widget. The options affected notably include **-background** and **-relief**. Examples
--------

 This is the classic Tk “Hello, World!” demonstration: 

```
**button** .b -text "Hello, World!" -command exit
pack .b
```
  This example demonstrates how to handle button accelerators: 



```
**button** .b1 -text Hello -underline 0
**button** .b2 -text World -underline 0
bind . <Key-h> {.b1 flash; .b1 invoke}
bind . <Key-w> {.b2 flash; .b2 invoke}
pack .b1 .b2
```
 See also
--------

 **[ttk::button](ttk_button.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/button.htm>

grab
====

  
[NAME](grab.htm#M2) grab — Confine pointer and keyboard events to a window sub-tree 
[SYNOPSIS](grab.htm#M3) 
[DESCRIPTION](grab.htm#M4)  
[**grab** ?**-global**? *window*](grab.htm#M5) 
[**grab current** ?*window*?](grab.htm#M6) 
[**grab release** *window*](grab.htm#M7) 
[**grab set** ?**-global**? *window*](grab.htm#M8) 
[**grab status** *window*](grab.htm#M9) 




 
[WARNING](grab.htm#M10) 
[BUGS](grab.htm#M11) 
[EXAMPLE](grab.htm#M12) 
[SEE ALSO](grab.htm#M13) 
[KEYWORDS](grab.htm#M14) 







 Name
----

 grab — Confine pointer and keyboard events to a window sub-tree Synopsis
--------

 **grab** ?**-global**? *window*  
 **grab** *option* ?*arg arg* ...?  
 Description
-----------

 This command implements simple pointer and keyboard grabs for Tk. Tk's grabs are different than the grabs described in the Xlib documentation. When a grab is set for a particular window, Tk restricts all pointer events to the grab window and its descendants in Tk's window hierarchy. Whenever the pointer is within the grab window's subtree, the pointer will behave exactly the same as if there had been no grab at all and all events will be reported in the normal fashion. When the pointer is outside *window*'s tree, button presses and releases and mouse motion events are reported to *window*, and window entry and window exit events are ignored. The grab subtree “owns” the pointer: windows outside the grab subtree will be visible on the screen but they will be insensitive until the grab is released. The tree of windows underneath the grab window can include top-level windows, in which case all of those top-level windows and their descendants will continue to receive mouse events during the grab.  Two forms of grabs are possible: local and global. A local grab affects only the grabbing application: events will be reported to other applications as if the grab had never occurred. Grabs are local by default. A global grab locks out all applications on the screen, so that only the given subtree of the grabbing application will be sensitive to pointer events (mouse button presses, mouse button releases, pointer motions, window entries, and window exits). During global grabs the window manager will not receive pointer events either. 


 During local grabs, keyboard events (key presses and key releases) are delivered as usual: the window manager controls which application receives keyboard events, and if they are sent to any window in the grabbing application then they are redirected to the focus window. During a global grab Tk grabs the keyboard so that all keyboard events are always sent to the grabbing application. The **[focus](focus.htm)** command is still used to determine which window in the application receives the keyboard events. The keyboard grab is released when the grab is released. 


 Grabs apply to particular displays. If an application has windows on multiple displays then it can establish a separate grab on each display. The grab on a particular display affects only the windows on that display. It is possible for different applications on a single display to have simultaneous local grabs, but only one application can have a global grab on a given display at once. 


 The **grab** command can take any of the following forms: 


 
**grab** ?**-global**? *window*

 Same as **grab set**, described below. 


**grab current** ?*window*?
 If *window* is specified, returns the name of the current grab window in this application for *window*'s display, or an empty string if there is no such window. If *window* is omitted, the command returns a list whose elements are all of the windows grabbed by this application for all displays, or an empty string if the application has no grabs. 


**grab release** *window*

 Releases the grab on *window* if there is one, otherwise does nothing. Returns an empty string. 


**grab set** ?**-global**? *window*

 Sets a grab on *window*. If **-global** is specified then the grab is global, otherwise it is local. If a grab was already in effect for this application on *window*'s display then it is automatically released. If there is already a grab on *window* and it has the same global/local form as the requested grab, then the command does nothing. Returns an empty string. 


**grab status** *window*

 Returns **none** if no grab is currently set on *window*, **local** if a local grab is set on *window*, and **global** if a global grab is set. 

 Warning
-------

 It is very easy to use global grabs to render a display completely unusable (e.g. by setting a grab on a widget which does not respond to events and not providing any mechanism for releasing the grab). Take *extreme* care when using them! Bugs
----

 It took an incredibly complex and gross implementation to produce the simple grab effect described above. Given the current implementation, it is not safe for applications to use the Xlib grab facilities at all except through the Tk grab procedures. If applications try to manipulate X's grab mechanisms directly, things will probably break.  If a single process is managing several different Tk applications, only one of those applications can have a local grab for a given display at any given time. If the applications are in different processes, this restriction does not exist. 


Example
-------

 Set a grab so that only one button may be clicked out of a group. The other buttons are unresponsive to the mouse until the middle button is clicked. 
```
pack [button .b1 -text "Click me! #1" -command {destroy .b1}]
pack [button .b2 -text "Click me! #2" -command {destroy .b2}]
pack [button .b3 -text "Click me! #3" -command {destroy .b3}]
**grab** .b2
```
 See also
--------

 **[busy](busy.htm)** Copyright © 1992 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/grab.htm>

image
=====

  
[NAME](image.htm#M2) image — Create and manipulate images 
[SYNOPSIS](image.htm#M3) 
[DESCRIPTION](image.htm#M4)  
[**image create** *type* ?*name*? ?*option value ...*?](image.htm#M5) 
[**image delete** ?*name name* ...?](image.htm#M6) 
[**image height** *name*](image.htm#M7) 
[**image inuse** *name*](image.htm#M8) 
[**image names**](image.htm#M9) 
[**image type** *name*](image.htm#M10) 
[**image types**](image.htm#M11) 
[**image width** *name*](image.htm#M12) 







 
[BUILT-IN IMAGE TYPES](image.htm#M13)  
[**bitmap**](image.htm#M14) 
[**photo**](image.htm#M15) 

 
[SEE ALSO](image.htm#M16) 
[KEYWORDS](image.htm#M17) 





 Name
----

 image — Create and manipulate images Synopsis
--------

 **image** *option* ?*arg arg ...*?  
 Description
-----------

 The **image** command is used to create, delete, and query images. It can take several different forms, depending on the *option* argument. The legal forms are: 
 
**image create** *type* ?*name*? ?*option value ...*?
 Creates a new image and a command with the same name and returns its name. *type* specifies the type of the image, which must be one of the types currently defined (e.g., **[bitmap](bitmap.htm)**). *name* specifies the name for the image; if it is omitted then Tk picks a name of the form **image***x*, where *x* is an integer. There may be any number of *option*-*value* pairs, which provide configuration options for the new image. The legal set of options is defined separately for each image type; see below for details on the options for built-in image types. If an image already exists by the given name then it is replaced with the new image and any instances of that image will redisplay with the new contents. It is important to note that the image command will silently overwrite any procedure that may currently be defined by the given name, so choose the name wisely. It is recommended to use a separate namespace for image names (e.g., **::img::logo**, **::img::large**). 


**image delete** ?*name name* ...?
 Deletes each of the named images and returns an empty string. If there are instances of the images displayed in widgets, the images will not actually be deleted until all of the instances are released. However, the association between the instances and the image manager will be dropped. Existing instances will retain their sizes but redisplay as empty areas. If a deleted image is recreated with another call to **image create**, the existing instances will use the new image. 


**image height** *name*

 Returns a decimal string giving the height of image *name* in pixels. 


**image inuse** *name*

 Returns a boolean value indicating whether or not the image given by *name* is in use by any widgets. 

**image names**
 Returns a list containing the names of all existing images. 


**image type** *name*

 Returns the type of image *name* (the value of the *type* argument to **image create** when the image was created). 

**image types**
 Returns a list whose elements are all of the valid image types (i.e., all of the values that may be supplied for the *type* argument to **image create**). 


**image width** *name*

 Returns a decimal string giving the width of image *name* in pixels. 

  Additional operations (e.g. writing the image to a file) may be available as subcommands of the image instance command. See the manual page for the particular image type for details. 


Built-in image types
--------------------

 The following image types are defined by Tk so they will be available in any Tk application. Individual applications or extensions may define additional types. 
 **bitmap**
 Each pixel in the image displays a foreground color, a background color, or nothing. See the **[bitmap](bitmap.htm)** manual entry for more information. 

**photo**
 Displays a variety of full-color images, using dithering to approximate colors on displays with limited color capabilities. See the **[photo](photo.htm)** manual entry for more information. 

 See also
--------

 **[bitmap](bitmap.htm)**, **[options](options.htm)**, **[photo](photo.htm)** Copyright © 1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/image.htm>

popup
=====

 Name
----

 tk\_popup — Post a popup menu Synopsis
--------

 **tk\_popup** *menu x y* ?*entry*?  
 Description
-----------

 This procedure posts a menu at a given position on the screen and configures Tk so that the menu and its cascaded children can be traversed with the mouse or the keyboard. *Menu* is the name of a menu widget and *x* and *y* are the root coordinates at which to display the menu. If *entry* is omitted or an empty string, the menu's upper left corner is positioned at the given point. Otherwise *entry* gives the index of an entry in *menu* and the menu will be positioned so that the entry is positioned over the given point. Example
-------

 How to attach a simple popup menu to a widget. 
```
# Create a menu
set m [menu .popupMenu]
$m add command -label "Example 1" -command bell
$m add command -label "Example 2" -command bell

# Create something to attach it to
pack [label .l -text "Click me!"]

# Arrange for the menu to pop up when the label is clicked
bind .l <1> {**tk\_popup** .popupMenu %X %Y}
```
 See also
--------

 **[bind](bind.htm)**, **[menu](menu.htm)**, **tk\_optionMenu** Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/popup.htm>

thread
======

  
[NAME](thread.htm#M2) thread — Extension for script access to Tcl threading 
[SYNOPSIS](thread.htm#M3) 
[DESCRIPTION](thread.htm#M4) 
[COMMANDS](thread.htm#M5)  
[**thread::create** ?-joinable? ?-preserved? ?script?](thread.htm#M6) 

[**thread::preserve** ?id?](thread.htm#M8) 
[**thread::release** ?-wait? ?id?](thread.htm#M9) 
[**thread::id**](thread.htm#M10) 
[**thread::errorproc** ?procname?](thread.htm#M11) 
[**thread::cancel** ?-unwind? *id* ?result?](thread.htm#M12) 
[**thread::unwind**](thread.htm#M13) 
[**thread::exit** ?status?](thread.htm#M14) 
[**thread::names**](thread.htm#M15) 
[**thread::exists** *id*](thread.htm#M16) 
[**thread::send** ?-async? ?-head? *id* *script* ?varname?](thread.htm#M17) 

[**thread::broadcast** *script*](thread.htm#M19) 
[**thread::wait**](thread.htm#M20) 
[**thread::eval** ?-lock mutex? *arg* ?arg . . .?](thread.htm#M21) 
[**thread::join** *id*](thread.htm#M22) 
[**thread::configure** *id* ?option? ?value? ? . . .?](thread.htm#M23) 
[**thread::transfer** *id* *channel*](thread.htm#M24) 
[**thread::detach** *channel*](thread.htm#M25) 
[**thread::attach** *channel*](thread.htm#M26) 
[**thread::mutex**](thread.htm#M27)  
[**thread::mutex** **create** ?-recursive?](thread.htm#M28) 
[**thread::mutex** **destroy** *mutex*](thread.htm#M29) 
[**thread::mutex** **lock** *mutex*](thread.htm#M30) 
[**thread::mutex** **unlock** *mutex*](thread.htm#M31) 



 
[**thread::rwmutex**](thread.htm#M32)  
[**thread::rwmutex** **create**](thread.htm#M33) 
[**thread::rwmutex** **destroy** *mutex*](thread.htm#M34) 
[**thread::rwmutex** **rlock** *mutex*](thread.htm#M35) 
[**thread::rwmutex** **wlock** *mutex*](thread.htm#M36) 
[**thread::rwmutex** **unlock** *mutex*](thread.htm#M37) 




 
[**thread::cond**](thread.htm#M38)  
[**thread::cond** **create**](thread.htm#M39) 
[**thread::cond** **destroy** *cond*](thread.htm#M40) 
[**thread::cond** **notify** *cond*](thread.htm#M41) 
[**thread::cond** **wait** *cond* *mutex* ?ms?](thread.htm#M42)




 























 
[DISCUSSION](thread.htm#M44) 
[SEE ALSO](thread.htm#M45) 
[KEYWORDS](thread.htm#M46) 






 Name
----

 thread — Extension for script access to Tcl threading Synopsis
--------

 package require **Tcl 8 .4**  
 package require **Thread ?2 .8?**  
 **thread::create** ?-joinable? ?-preserved? ?script?  
 **thread::preserve** ?id?  
 **thread::release** ?-wait? ?id?  
 **thread::id**  
 **thread::errorproc** ?procname?  
 **thread::cancel** ?-unwind? *id* ?result?  
 **thread::unwind**  
 **thread::exit** ?status?  
 **thread::names**  
 **thread::exists** *id*  
 **thread::send** ?-async? ?-head? *id* *script* ?varname?  
 **thread::broadcast** *script*  
 **thread::wait**  
 **thread::eval** ?-lock mutex? *arg* ?arg . . .?  
 **thread::join** *id*  
 **thread::configure** *id* ?option? ?value? ? . . .?  
 **thread::transfer** *id* *channel*  
 **thread::detach** *channel*  
 **thread::attach** *channel*  
 **thread::mutex**  
 **thread::mutex** **create** ?-recursive?  
 **thread::mutex** **[destroy](../tkcmd/destroy.htm)** *mutex*  
 **thread::mutex** **lock** *mutex*  
 **thread::mutex** **unlock** *mutex*  
 **thread::rwmutex**  
 **thread::rwmutex** **create**  
 **thread::rwmutex** **[destroy](../tkcmd/destroy.htm)** *mutex*  
 **thread::rwmutex** **rlock** *mutex*  
 **thread::rwmutex** **wlock** *mutex*  
 **thread::rwmutex** **unlock** *mutex*  
 **thread::cond**  
 **thread::cond** **create**  
 **thread::cond** **[destroy](../tkcmd/destroy.htm)** *cond*  
 **thread::cond** **notify** *cond*  
 **thread::cond** **wait** *cond* *mutex* ?ms?  
 Description
-----------

 The **thread** extension creates threads that contain Tcl interpreters, and it lets you send scripts to those threads for evaluation . Additionaly, it provides script-level access to basic thread synchronization primitives, like mutexes and condition variables . Commands
--------

 This section describes commands for creating and destroying threads and sending scripts to threads for evaluation . 
 
**thread::create** ?-joinable? ?-preserved? ?script?
 This command creates a thread that contains a Tcl interpreter . The Tcl interpreter either evaluates the optional **script**, if specified, or it waits in the event loop for scripts that arrive via the **thread::send** command . The result, if any, of the optional **script** is never returned to the caller . The result of **thread::create** is the ID of the thread . This is the opaque handle which identifies the newly created thread for all other package commands . The handle of the thread goes out of scope automatically when thread is marked for exit (see the **thread::release** command below) .  If the optional **script** argument contains the **thread::wait** command the thread will enter into the event loop . If such command is not found in the **script** the thread will run the **script** to the end and exit . In that case, the handle may be safely ignored since it refers to a thread which does not exists any more at the time when the command returns . 


 Using flag **-joinable** it is possible to create a joinable thread, i .e . one upon whose exit can be waited upon by using **thread::join** command . Note that failure to join a thread created with **-joinable** flag results in resource and memory leaks . 


 Threads created by the **thread::create** cannot be destroyed forcefully . Consequently, there is no corresponding thread destroy command . A thread may only be released using the **thread::release** and if its internal reference count drops to zero, the thread is marked for exit . This kicks the thread out of the event loop servicing and the thread continues to execute commands passed in the **script** argument, following the **thread::wait** command . If this was the last command in the script, as usualy the case, the thread will exit . 


 It is possible to create a situation in which it may be impossible to terminate the thread, for example by putting some endless loop after the **thread::wait** or entering the event loop again by doing an vwait-type of command . In such cases, the thread may never exit . This is considered to be a bad practice and should be avoided if possible . This is best illustrated by the example below: 



```
# You should never do 	.	.	.
    set tid [thread::create {
        package require Http
        thread::wait
        vwait forever ; # <-- this!
    }]
```


 The thread created in the above example will never be able to exit . After it has been released with the last matching **thread::release** call, the thread will jump out of the **thread::wait** and continue to execute commands following . It will enter **[vwait](../tclcmd/vwait.htm)** command and wait endlessly for events . There is no way one can terminate such thread, so you wouldn't want to do this!  Each newly created has its internal reference counter set to 0 (zero), i .e . it is unreserved . This counter gets incremented by a call to **thread::preserve** and decremented by a call to **thread::release** command . These two commands implement simple but effective thread reservation system and offer predictable and controllable thread termination capabilities . It is however possible to create initialy preserved threads by using flag **-preserved** of the **thread::create** command . Threads created with this flag have the initial value of the reference counter of 1 (one), and are thus initially marked reserved . 




**thread::preserve** ?id?
 This command increments the thread reference counter . Each call to this command increments the reference counter by one (1) . Command returns the value of the reference counter after the increment . If called with the optional thread **id**, the command preserves the given thread . Otherwise the current thread is preserved .  With reference counting, one can implement controlled access to a shared Tcl thread . By incrementing the reference counter, the caller signalizes that he/she wishes to use the thread for a longer period of time . By decrementing the counter, caller signalizes that he/she has finished using the thread . 




**thread::release** ?-wait? ?id?
 This command decrements the thread reference counter . Each call to this command decrements the reference counter by one (1) . If called with the optional thread **id**, the command releases the given thread . Otherwise, the current thread is released . Command returns the value of the reference counter after the decrement . When the reference counter reaches zero (0), the target thread is marked for termination . You should not reference the thread after the **thread::release** command returns zero or negative integer . The handle of the thread goes out of scope and should not be used any more . Any following reference to the same thread handle will result in Tcl error .  Optional flag **-wait** instructs the caller thread to wait for the target thread to exit, if the effect of the command would result in termination of the target thread, i .e . if the return result would be zero (0) . Without the flag, the caller thread does not wait for the target thread to exit . Care must be taken when using the **-wait**, since this may block the caller thread indefinitely . This option has been implemented for some special uses of the extension and is deprecated for regular use . Regular users should create joinable threads by using the **-joinable** option of the **thread::create** command and the **thread::join** to wait for thread to exit . 



**thread::id**
 This command returns the ID of the current thread . 


**thread::errorproc** ?procname?
 This command sets a handler for errors that occur in scripts sent asynchronously, using the **-async** flag of the **thread::send** command, to other threads . If no handler is specified, the current handler is returned . The empty string resets the handler to default (unspecified) value . An uncaught error in a thread causes an error message to be sent to the standard error channel . This default reporting scheme can be changed by registering a procedure which is called to report the error . The *procname* is called in the interpreter that invoked the **thread::errorproc** command . The *procname* is called like this: 
```
myerrorproc thread_id errorInfo
```



**thread::cancel** ?-unwind? *id* ?result?
 This command requires Tcl version 8 .6 or higher .  Cancels the script being evaluated in the thread given by the *id* parameter . Without the **-unwind** switch the evaluation stack for the interpreter is unwound until an enclosing catch command is found or there are no further invocations of the interpreter left on the call stack . With the **-unwind** switch the evaluation stack for the interpreter is unwound without regard to any intervening catch command until there are no further invocations of the interpreter left on the call stack . If *result* is present, it will be used as the error message string; otherwise, a default error message string will be used . 



**thread::unwind**
 Use of this command is deprecated in favour of more advanced thread reservation system implemented with **thread::preserve** and **thread::release** commands . Support for **thread::unwind** command will dissapear in some future major release of the extension .  This command stops a prior **thread::wait** command . Execution of the script passed to newly created thread will continue from the **thread::wait** command . If **thread::wait** was the last command in the script, the thread will exit . The command returns empty result but may trigger Tcl error with the message "target thread died" in some situations . 




**thread::exit** ?status?
 Use of this command is deprecated in favour of more advanced thread reservation system implemented with **thread::preserve** and **thread::release** commands . Support for **thread::exit** command will dissapear in some future major release of the extension .  This command forces a thread stuck in the **thread::wait** command to unconditionaly exit . The thread's exit status defaults to 666 and can be specified using the optional *status* argument . The execution of **thread::exit** command is guaranteed to leave the program memory in the unconsistent state, produce memory leaks and otherwise affect other subsytem(s) of the Tcl application in an unpredictable manner . The command returns empty result but may trigger Tcl error with the message "target thread died" in some situations . 



**thread::names**
 This command returns a list of thread IDs . These are only for threads that have been created via **thread::create** command . If your application creates other threads at the C level, they are not reported by this command . 


**thread::exists** *id*

 Returns true (1) if thread given by the *id* parameter exists, false (0) otherwise . This applies only for threads that have been created via **thread::create** command . 


**thread::send** ?-async? ?-head? *id* *script* ?varname?
 This command passes a *script* to another thread and, optionally, waits for the result . If the **-async** flag is specified, the command does not wait for the result and it returns empty string . The target thread must enter it's event loop in order to receive scripts sent via this command . This is done by default for threads created without a startup script . Threads can enter the event loop explicitly by calling **thread::wait** or any other relevant Tcl/Tk command, like **[update](../tclcmd/update.htm)**, **[vwait](../tclcmd/vwait.htm)**, etc .  Optional **varname** specifies name of the variable to store the result of the *script* . Without the **-async** flag, the command returns the evaluation code, similarily to the standard Tcl **[catch](../tclcmd/catch.htm)** command . If, however, the **-async** flag is specified, the command returns immediately and caller can later **[vwait](../tclcmd/vwait.htm)** on ?varname? to get the result of the passed *script* 



```
set t1 [thread::create]
    set t2 [thread::create]
    thread::send -async $t1 "set a 1" result
    thread::send -async $t2 "set b 2" result
    for {set i 0} {$i < 2} {incr i} {
        vwait result
    }
```


 In the above example, two threads were fed work and both of them were instructed to signalize the same variable "result" in the calling thread . The caller entered the event loop twice to get both results . Note, however, that the order of the received results may vary, depending on the current system load, type of work done, etc, etc .  Many threads can simultaneously send scripts to the target thread for execution . All of them are entered into the event queue of the target thread and executed on the FIFO basis, intermingled with optional other events pending in the event queue of the target thread . Using the optional ?-head? switch, scripts posted to the thread's event queue can be placed on the head, instead on the tail of the queue, thus being executed in the LIFO fashion . 




**thread::broadcast** *script*

 This command passes a *script* to all threads created by the package for execution . It does not wait for response from any of the threads . 

**thread::wait**
 This enters the event loop so a thread can receive messages from the **thread::send** command . This command should only be used within the script passed to the **thread::create** . It should be the very last command in the script . If this is not the case, the exiting thread will continue executing the script lines past the **thread::wait** which is usually not what you want and/or expect . 
```
set t1 [thread::create {
        #
        # Do some initialization work here
        #
        thread::wait ; # Enter the event loop
    }]
```



**thread::eval** ?-lock mutex? *arg* ?arg . . .?
 This command concatenates passed arguments and evaluates the resulting script under the mutex protection . If no mutex is specified by using the ?-lock mutex? optional argument, the internal static mutex is used . 


**thread::join** *id*

 This command waits for the thread with ID *id* to exit and then returns it's exit code . Errors will be returned for threads which are not joinable or already waited upon by another thread . Upon the join the handle of the thread has gone out of scope and should not be used any more . 


**thread::configure** *id* ?option? ?value? ? . . .?
 This command configures various low-level aspects of the thread with ID *id* in the similar way as the standard Tcl command **[fconfigure](../tclcmd/fconfigure.htm)** configures some Tcl channel options . Options currently supported are: **-eventmark** and **-unwindonerror** .  The **-eventmark** option, when set, limits the number of asynchronously posted scripts to the thread event loop . The **thread::send -async** command will block until the number of pending scripts in the event loop does not drop below the value configured with **-eventmark** . Default value for the **-eventmark** is 0 (zero) which effectively disables the checking, i .e . allows for unlimited number of posted scripts . 


 The **-unwindonerror** option, when set, causes the target thread to unwind if the result of the script processing resulted in error . Default value for the **-unwindonerror** is 0 (false), i .e . thread continues to process scripts after one of the posted scripts fails . 




**thread::transfer** *id* *channel*

 This moves the specified *channel* from the current thread and interpreter to the main interpreter of the thread with the given *id* . After the move the current interpreter has no access to the channel any more, but the main interpreter of the target thread will be able to use it from now on . The command waits until the other thread has incorporated the channel . Because of this it is possible to deadlock the participating threads by commanding the other through a synchronous **thread::send** to transfer a channel to us . This easily extends into longer loops of threads waiting for each other . Other restrictions: the channel in question must not be shared among multiple interpreters running in the sending thread . This automatically excludes the special channels for standard input, output and error .  Due to the internal Tcl core implementation and the restriction on transferring shared channels, one has to take extra measures when transferring socket channels created by accepting the connection out of the **[socket](../tclcmd/socket.htm)** commands callback procedures: 



```
socket -server _Accept 2200
    proc _Accept {s ipaddr port} {
        after idle [list Accept $s $ipaddr $port]
    }
    proc Accept {s ipaddr port} {
        set tid [thread::create]
        thread::transfer $tid $s
    }
```



**thread::detach** *channel*

 This detaches the specified *channel* from the current thread and interpreter . After that, the current interpreter has no access to the channel any more . The channel is in the parked state until some other (or the same) thread attaches the channel again with **thread::attach** . Restrictions: same as for transferring shared channels with the **thread::transfer** command . 


**thread::attach** *channel*

 This attaches the previously detached *channel* in the current thread/interpreter . For already existing channels, the command does nothing, i .e . it is not an error to attach the same channel more than once . The first operation will actualy perform the operation, while all subsequent operation will just do nothing . Command throws error if the *channel* cannot be found in the list of detached channels and/or in the current interpreter . 

**thread::mutex**
 Mutexes are most common thread synchronization primitives . They are used to synchronize access from two or more threads to one or more shared resources . This command provides script-level access to exclusive and/or recursive mutexes . Exclusive mutexes can be locked only once by one thread, while recursive mutexes can be locked many times by the same thread . For recursive mutexes, number of lock and unlock operations must match, otherwise, the mutex will never be released, which would lead to various deadlock situations .  Care has to be taken when using mutexes in an multithreading program . Improper use of mutexes may lead to various deadlock situations, especially when using exclusive mutexes . 


 The **thread::mutex** command supports following subcommands and options: 


 
**thread::mutex** **create** ?-recursive?
 Creates the mutex and returns it's opaque handle . This handle should be used for any future reference to the newly created mutex . If no optional ?-recursive? argument was specified, the command creates the exclusive mutex . With the ?-recursive? argument, the command creates a recursive mutex . 


**thread::mutex** **destroy** *mutex*

 Destroys the *mutex* . Mutex should be in unlocked state before the destroy attempt . If the mutex is locked, the command will throw Tcl error . 


**thread::mutex** **lock** *mutex*

 Locks the *mutex* . Locking the exclusive mutex may throw Tcl error if on attempt to lock the same mutex twice from the same thread . If your program logic forces you to lock the same mutex twice or more from the same thread (this may happen in recursive procedure invocations) you should consider using the recursive mutexes . 


**thread::mutex** **unlock** *mutex*

 Unlocks the *mutex* so some other thread may lock it again . Attempt to unlock the already unlocked mutex will throw Tcl error . 



**thread::rwmutex**
 This command creates many-readers/single-writer mutexes . Reader/writer mutexes allow you to serialize access to a shared resource more optimally . In situations where a shared resource gets mostly read and seldom modified, you might gain some performace by using reader/writer mutexes instead of exclusive or recursive mutexes .  For reading the resource, thread should obtain a read lock on the resource . Read lock is non-exclusive, meaning that more than one thread can obtain a read lock to the same resource, without waiting on other readers . For changing the resource, however, a thread must obtain a exclusive write lock . This lock effectively blocks all threads from gaining the read-lock while the resource is been modified by the writer thread . Only after the write lock has been released, the resource may be read-locked again . 


 The **thread::rwmutex** command supports following subcommands and options: 


 
**thread::rwmutex** **create**

 Creates the reader/writer mutex and returns it's opaque handle . This handle should be used for any future reference to the newly created mutex . 


**thread::rwmutex** **destroy** *mutex*

 Destroys the reader/writer *mutex* . If the mutex is already locked, attempt to destroy it will throw Tcl error . 


**thread::rwmutex** **rlock** *mutex*

 Locks the *mutex* for reading . More than one thread may read-lock the same *mutex* at the same time . 


**thread::rwmutex** **wlock** *mutex*

 Locks the *mutex* for writing . Only one thread may write-lock the same *mutex* at the same time . Attempt to write-lock same *mutex* twice from the same thread will throw Tcl error . 


**thread::rwmutex** **unlock** *mutex*

 Unlocks the *mutex* so some other thread may lock it again . Attempt to unlock already unlocked *mutex* will throw Tcl error . 



**thread::cond**
 This command provides script-level access to condition variables . A condition variable creates a safe environment for the program to test some condition, sleep on it when false and be awakened when it might have become true . A condition variable is always used in the conjuction with an exclusive mutex . If you attempt to use other type of mutex in conjuction with the condition variable, a Tcl error will be thrown .  The command supports following subcommands and options: 


 
**thread::cond** **create**

 Creates the condition variable and returns it's opaque handle . This handle should be used for any future reference to newly created condition variable . 


**thread::cond** **destroy** *cond*

 Destroys condition variable *cond* . Extreme care has to be taken that nobody is using (i .e . waiting on) the condition variable, otherwise unexpected errors may happen . 


**thread::cond** **notify** *cond*

 Wakes up all threads waiting on the condition variable *cond* . 


**thread::cond** **wait** *cond* *mutex* ?ms?
 This command is used to suspend program execution until the condition variable *cond* has been signalled or the optional timer has expired . The exclusive *mutex* must be locked by the calling thread on entrance to this command . If the mutex is not locked, Tcl error is thrown . While waiting on the *cond*, the command releases *mutex* . Before returning to the calling thread, the command re-acquires the *mutex* again . Unlocking the *mutex* and waiting on the condition variable *cond* is done atomically .  The **ms** command option, if given, must be an integer specifying time interval in milliseconds the command waits to be signalled . Otherwise the command waits on condition notify forever . 


 In multithreading programs, there are many situations where a thread has to wait for some event to happen until it is allowed to proceed . This is usually accomplished by repeatedly testing a condition under the mutex protection and waiting on the condition variable until the condition evaluates to true: 



```
set mutex [thread::mutex create]
    set cond  [thread::cond  create]

    thread::mutex lock $mutex
    while {<some_condition_is_true>} {
        thread::cond wait $cond $mutex
    }
    # Do some work under mutex protection
    thread::mutex unlock $mutex
```


 Repeated testing of the condition is needed since the condition variable may get signalled without the condition being actually changed (spurious thread wake-ups, for example) . 




Discussion
----------

 The fundamental threading model in Tcl is that there can be one or more Tcl interpreters per thread, but each Tcl interpreter should only be used by a single thread which created it . A "shared memory" abstraction is awkward to provide in Tcl because Tcl makes assumptions about variable and data ownership . Therefore this extension supports a simple form of threading where the main thread can manage several background, or "worker" threads . For example, an event-driven server can pass requests to worker threads, and then await responses from worker threads or new client requests . Everything goes through the common Tcl event loop, so message passing between threads works naturally with event-driven I/O, **[vwait](../tclcmd/vwait.htm)** on variables, and so forth . For the transfer of bulk information it is possible to move channels between the threads .  For advanced multithreading scripts, script-level access to two basic synchronization primitives, mutex and condition variables, is also supported . 


See also
--------

 ***<http://www> .tcl .tk/doc/howto/thread\_model .html***, **[tpool](tpool.htm)**, **[tsv](tsv.htm)**, **[ttrace](ttrace.htm)** 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/ThreadCmd/thread.htm>

ttk\_notebook
=============

  
[NAME](ttk_notebook.htm#M2) ttk::notebook — Multi-paned container widget 
[SYNOPSIS](ttk_notebook.htm#M3) 
[DESCRIPTION](ttk_notebook.htm#M4) 
[STANDARD OPTIONS](ttk_notebook.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 



 
[WIDGET-SPECIFIC OPTIONS](ttk_notebook.htm#M6)  
[-height, height, Height](ttk_notebook.htm#M7) 
[-padding, padding, Padding](ttk_notebook.htm#M8) 
[-width, width, Width](ttk_notebook.htm#M9) 


 
[TAB OPTIONS](ttk_notebook.htm#M10)  
[-state, state, State](ttk_notebook.htm#M11) 
[-sticky, sticky, Sticky](ttk_notebook.htm#M12) 
[-padding, padding, Padding](ttk_notebook.htm#M13) 
[-text, text, Text](ttk_notebook.htm#M14) 
[-image, image, Image](ttk_notebook.htm#M15) 
[-compound, compound, Compound](ttk_notebook.htm#M16) 
[-underline, underline, Underline](ttk_notebook.htm#M17) 






 
[TAB IDENTIFIERS](ttk_notebook.htm#M18) 
[WIDGET COMMAND](ttk_notebook.htm#M19)  
[*pathname* **add** *window* ?*options...*?](ttk_notebook.htm#M20) 
[*pathname* **configure** ?*options*?](ttk_notebook.htm#M21) 
[*pathname* **cget** *option*](ttk_notebook.htm#M22) 
[*pathname* **forget** *tabid*](ttk_notebook.htm#M23) 
[*pathname* **hide** *tabid*](ttk_notebook.htm#M24) 
[*pathname* **identify** *component x y*](ttk_notebook.htm#M25)  
[*pathname* **identify element** *x y*](ttk_notebook.htm#M26) 
[*pathname* **identify tab** *x y*](ttk_notebook.htm#M27) 

 
[*pathname* **index** *tabid*](ttk_notebook.htm#M28) 
[*pathname* **insert** *pos subwindow options...*](ttk_notebook.htm#M29) 
[*pathname* **instate** *statespec* ?*script...*?](ttk_notebook.htm#M30) 
[*pathname* **select** ?*tabid*?](ttk_notebook.htm#M31) 
[*pathname* **state** ?*statespec*?](ttk_notebook.htm#M32) 
[*pathname* **tab** *tabid* ?*-option* ?*value ...*](ttk_notebook.htm#M33) 
[*pathname* **tabs**](ttk_notebook.htm#M34) 












 
[KEYBOARD TRAVERSAL](ttk_notebook.htm#M35) 
[VIRTUAL EVENTS](ttk_notebook.htm#M36) 
[EXAMPLE](ttk_notebook.htm#M37) 
[SEE ALSO](ttk_notebook.htm#M38) 
[KEYWORDS](ttk_notebook.htm#M39) 












 Name
----

 ttk::notebook — Multi-paned container widget Synopsis
--------

 **ttk::notebook** *pathname* ?*options...*?  
 *pathname* **add** *window* ?*options...*?  
 *pathname* **insert** *index* *window* ?*options...*?  
 Description
-----------

 A **ttk::notebook** widget manages a collection of windows and displays a single one at a time. Each slave window is associated with a *tab*, which the user may select to change the currently-displayed window. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 



 Widget-specific options
-----------------------

  Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


If present and greater than zero, specifies the desired height of the pane area (not including internal padding or tabs). Otherwise, the maximum height of all panes is used. 

Command-Line Name: **-padding** Database Name: **padding** Database Class: **Padding** 


Specifies the amount of extra space to add around the outside of the notebook. The padding is a list of up to four length specifications *left top right bottom*. If fewer than four elements are specified, *bottom* defaults to *top*, *right* defaults to *left*, and *top* defaults to *left*. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


If present and greater than zero, specifies the desired width of the pane area (not including internal padding). Otherwise, the maximum width of all panes is used. 
 Tab options
-----------

 The following options may be specified for individual notebook panes:  Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Either **normal**, **disabled** or **hidden**. If **disabled**, then the tab is not selectable. If **hidden**, then the tab is not shown. 

Command-Line Name: **-sticky** Database Name: **sticky** Database Class: **Sticky** 


Specifies how the slave window is positioned within the pane area. Value is a string containing zero or more of the characters **n, s, e,** or **w**. Each letter refers to a side (north, south, east, or west) that the slave window will “stick” to, as per the **[grid](grid.htm)** geometry manager. 

Command-Line Name: **-padding** Database Name: **padding** Database Class: **Padding** 


Specifies the amount of extra space to add between the notebook and this pane. Syntax is the same as for the widget **-padding** option. 

Command-Line Name: **-text** Database Name: **text** Database Class: **Text** 


Specifies a string to be displayed in the tab. 

Command-Line Name: **-image** Database Name: **image** Database Class: **Image** 


Specifies an image to display in the tab. See *ttk\_widget(n)* for details. 

Command-Line Name: **-compound** Database Name: **compound** Database Class: **Compound** 


Specifies how to display the image relative to the text, in the case both **-text** and **-image** are present. See *label(n)* for legal values. 

Command-Line Name: **-underline** Database Name: **underline** Database Class: **Underline** 


Specifies the integer index (0-based) of a character to underline in the text string. The underlined character is used for mnemonic activation if **ttk::notebook::enableTraversal** is called. 
 Tab identifiers
---------------

 The *tabid* argument to the following commands may take any of the following forms: 
* An integer between zero and the number of tabs;
* The name of a slave window;
* A positional specification of the form “@*x*,*y*”, which identifies the tab
* The literal string “**current**”, which identifies the currently-selected tab; or:
* The literal string “**end**”, which returns the number of tabs (only valid for “*pathname* **index**”).

 Widget command
--------------

  
*pathname* **add** *window* ?*options...*?
 Adds a new tab to the notebook. See **[TAB OPTIONS](#M10)** for the list of available *options*. If *window* is currently managed by the notebook but hidden, it is restored to its previous position. 


*pathname* **configure** ?*options*?
 See *ttk::widget(n)*. 


*pathname* **cget** *option*

 See *ttk::widget(n)*. 


*pathname* **forget** *tabid*

 Removes the tab specified by *tabid*, unmaps and unmanages the associated window. 


*pathname* **hide** *tabid*

 Hides the tab specified by *tabid*. The tab will not be displayed, but the associated window remains managed by the notebook and its configuration remembered. Hidden tabs may be restored with the **add** command. 


*pathname* **identify** *component x y*

 Returns the name of the element under the point given by *x* and *y*, or the empty string if no component is present at that location. The following subcommands are supported: 
 
*pathname* **identify element** *x y*

 Returns the name of the element at the specified location. 


*pathname* **identify tab** *x y*

 Returns the index of the tab at the specified location. 




*pathname* **index** *tabid*

 Returns the numeric index of the tab specified by *tabid*, or the total number of tabs if *tabid* is the string “**end**”. 


*pathname* **insert** *pos subwindow options...*

 Inserts a pane at the specified position. *pos* is either the string **end**, an integer index, or the name of a managed subwindow. If *subwindow* is already managed by the notebook, moves it to the specified position. See **[TAB OPTIONS](#M10)** for the list of available options. 


*pathname* **instate** *statespec* ?*script...*?
 See *ttk::widget(n)*. 


*pathname* **select** ?*tabid*?
 Selects the specified tab. The associated slave window will be displayed, and the previously-selected window (if different) is unmapped. If *tabid* is omitted, returns the widget name of the currently selected pane. 


*pathname* **state** ?*statespec*?
 See *ttk::widget(n)*. 


*pathname* **tab** *tabid* ?*-option* ?*value ...*

 Query or modify the options of the specific tab. If no *-option* is specified, returns a dictionary of the tab option values. If one *-option* is specified, returns the value of that *option*. Otherwise, sets the *-option*s to the corresponding *value*s. See **[TAB OPTIONS](#M10)** for the available options. 


*pathname* **tabs**

 Returns the list of windows managed by the notebook. 

 Keyboard traversal
------------------

 To enable keyboard traversal for a toplevel window containing a notebook widget *$nb*, call: 
```
ttk::notebook::enableTraversal $nb
```
  This will extend the bindings for the toplevel window containing the notebook as follows: 


* **Control-Tab** selects the tab following the currently selected one.
* **Control-Shift-Tab** selects the tab preceding the currently selected one.
* **Alt-***K*, where *K* is the mnemonic (underlined) character of any tab, will select that tab.

  Multiple notebooks in a single toplevel may be enabled for traversal, including nested notebooks. However, notebook traversal only works properly if all panes are direct children of the notebook. 


Virtual events
--------------

 The notebook widget generates a **<<NotebookTabChanged>>** virtual event after a new tab is selected. Example
-------

 
```
pack [**ttk::notebook** .nb]
	.nb add [frame .nb.f1] -text "First tab"
	.nb add [frame .nb.f2] -text "Second tab"
	.nb select .nb.f2
ttk::notebook::enableTraversal .nb
```
 See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[grid](grid.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_notebook.htm>

bindtags
========

 Name
----

 bindtags — Determine which bindings apply to a window, and order of evaluation Synopsis
--------

 **bindtags** *window* ?*tagList*?  
 Description
-----------

 When a binding is created with the **[bind](bind.htm)** command, it is associated either with a particular window such as **.a.b.c**, a class name such as **[Button](button.htm)**, the keyword **all**, or any other string. All of these forms are called *binding tags*. Each window contains a list of binding tags that determine how events are processed for the window. When an event occurs in a window, it is applied to each of the window's tags in order: for each tag, the most specific binding that matches the given tag and event is executed. See the **[bind](bind.htm)** command for more information on the matching process.  By default, each window has four binding tags consisting of the name of the window, the window's class name, the name of the window's nearest toplevel ancestor, and **all**, in that order. Toplevel windows have only three tags by default, since the toplevel name is the same as that of the window. The **bindtags** command allows the binding tags for a window to be read and modified. 


 If **bindtags** is invoked with only one argument, then the current set of binding tags for *window* is returned as a list. If the *tagList* argument is specified to **bindtags**, then it must be a proper list; the tags for *window* are changed to the elements of the list. The elements of *tagList* may be arbitrary strings; however, any tag starting with a dot is treated as the name of a window; if no window by that name exists at the time an event is processed, then the tag is ignored for that event. The order of the elements in *tagList* determines the order in which binding scripts are executed in response to events. For example, the command 



```
**bindtags .b {all . Button .b}**
```
 reverses the order in which binding scripts will be evaluated for a button named **.b** so that **all** bindings are invoked first, following by bindings for **.b**'s toplevel (“.”), followed by class bindings, followed by bindings for **.b**. If *tagList* is an empty list then the binding tags for *window* are returned to the default state described above.  The **bindtags** command may be used to introduce arbitrary additional binding tags for a window, or to remove standard tags. For example, the command 



```
**bindtags .b {.b TrickyButton . all}**
```
 replaces the **[Button](button.htm)** tag for **.b** with **TrickyButton**. This means that the default widget bindings for buttons, which are associated with the **[Button](button.htm)** tag, will no longer apply to **.b**, but any bindings associated with **TrickyButton** (perhaps some new button behavior) will apply. Example
-------

 If you have a set of nested **[frame](frame.htm)** widgets and you want events sent to a **[button](button.htm)** widget to also be delivered to all the widgets up to the current **[toplevel](toplevel.htm)** (in contrast to Tk's default behavior, where events are not delivered to those intermediate windows) to make it easier to have accelerators that are only active for part of a window, you could use a helper procedure like this to help set things up: 
```
proc setupBindtagsForTreeDelivery {widget} {
    set tags [list $widget [winfo class $widget]]
    set w $widget
    set t [winfo toplevel $w]
    while {$w ne $t} {
        set w [winfo parent $w]
        lappend tags $w
    }
    lappend tags all
    **bindtags** $widget $tags
}
```
 See also
--------

 **[bind](bind.htm)** Copyright © 1990 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/bindtags.htm>

bitmap
======

  
[NAME](bitmap.htm#M2) bitmap — Images that display two colors 
[SYNOPSIS](bitmap.htm#M3) 
[DESCRIPTION](bitmap.htm#M4) 
[CREATING BITMAPS](bitmap.htm#M5)  
[**-background** *color*](bitmap.htm#M6) 
[**-data** *string*](bitmap.htm#M7) 
[**-file** *name*](bitmap.htm#M8) 
[**-foreground** *color*](bitmap.htm#M9) 
[**-maskdata** *string*](bitmap.htm#M10) 
[**-maskfile** *name*](bitmap.htm#M11) 





 
[IMAGE COMMAND](bitmap.htm#M12)  
[*imageName* **cget** *option*](bitmap.htm#M13) 
[*imageName* **configure** ?*option*? ?*value option value ...*?](bitmap.htm#M14) 

 
[KEYWORDS](bitmap.htm#M15) 





 Name
----

 bitmap — Images that display two colors Synopsis
--------

 **image create bitmap** ?*name*? ?*options*?  
   
 *imageName* **cget** *option*  
 *imageName* **configure** ?*option*? ?*value option value ...*?  
 Description
-----------

 A bitmap is an image whose pixels can display either of two colors or be transparent. A bitmap image is defined by four things: a background color, a foreground color, and two bitmaps, called the *source* and the *mask*. Each of the bitmaps specifies 0/1 values for a rectangular array of pixels, and the two bitmaps must have the same dimensions. For pixels where the mask is zero, the image displays nothing, producing a transparent effect. For other pixels, the image displays the foreground color if the source data is one and the background color if the source data is zero. Creating bitmaps
----------------

 Like all images, bitmaps are created using the **[image create](image.htm)** command. Bitmaps support the following *options*: 
 
**-background** *color*

 Specifies a background color for the image in any of the standard ways accepted by Tk. If this option is set to an empty string then the background pixels will be transparent. This effect is achieved by using the source bitmap as the mask bitmap, ignoring any **-maskdata** or **-maskfile** options. 


**-data** *string*

 Specifies the contents of the source bitmap as a string. The string must adhere to X11 bitmap format (e.g., as generated by the **bitmap** program). If both the **-data** and **-file** options are specified, the **-data** option takes precedence. 


**-file** *name*

 *name* gives the name of a file whose contents define the source bitmap. The file must adhere to X11 bitmap format (e.g., as generated by the **bitmap** program). 


**-foreground** *color*

 Specifies a foreground color for the image in any of the standard ways accepted by Tk. 


**-maskdata** *string*

 Specifies the contents of the mask as a string. The string must adhere to X11 bitmap format (e.g., as generated by the **bitmap** program). If both the **-maskdata** and **-maskfile** options are specified, the **-maskdata** option takes precedence. 


**-maskfile** *name*

 *name* gives the name of a file whose contents define the mask. The file must adhere to X11 bitmap format (e.g., as generated by the **bitmap** program). 

 Image command
-------------

 When a bitmap image is created, Tk also creates a new command whose name is the same as the image. This command may be used to invoke various operations on the image. It has the following general form: 
```
*imageName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for bitmap images: 
 
*imageName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **[image create](image.htm)** **bitmap** command. 


*imageName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options for the image. If no *option* is specified, returns a list describing all of the available options for *imageName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **[image create](image.htm)** **bitmap** command. 

 Copyright © 1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/bitmap.htm>

scale
=====

  
[NAME](scale.htm#M2) scale — Create and manipulate 'scale' value-controlled slider widgets 
[SYNOPSIS](scale.htm#M3) 
[STANDARD OPTIONS](scale.htm#M4)  
[-activebackground, activeBackground, Foreground](options.htm#M-activebackground) 
[-background or -bg, background, Background](options.htm#M-background) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-orient, orient, Orient](options.htm#M-orient) 
[-relief, relief, Relief](options.htm#M-relief) 
[-repeatdelay, repeatDelay, RepeatDelay](options.htm#M-repeatdelay) 
[-repeatinterval, repeatInterval, RepeatInterval](options.htm#M-repeatinterval) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-troughcolor, troughColor, Background](options.htm#M-troughcolor) 














 
[WIDGET-SPECIFIC OPTIONS](scale.htm#M5)  
[-bigincrement, bigIncrement, BigIncrement](scale.htm#M6) 
[-command, command, Command](scale.htm#M7) 
[-digits, digits, Digits](scale.htm#M8) 
[-from, from, From](scale.htm#M9) 
[-label, label, Label](scale.htm#M10) 
[-length, length, Length](scale.htm#M11) 
[-resolution, resolution, Resolution](scale.htm#M12) 
[-showvalue, showValue, ShowValue](scale.htm#M13) 
[-sliderlength, sliderLength, SliderLength](scale.htm#M14) 
[-sliderrelief, sliderRelief, SliderRelief](scale.htm#M15) 
[-state, state, State](scale.htm#M16) 
[-tickinterval, tickInterval, TickInterval](scale.htm#M17) 
[-to, to, To](scale.htm#M18) 
[-variable, variable, Variable](scale.htm#M19) 
[-width, width, Width](scale.htm#M20) 














 
[DESCRIPTION](scale.htm#M21) 
[WIDGET COMMAND](scale.htm#M22)  
[*pathName* **cget** *option*](scale.htm#M23) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](scale.htm#M24) 
[*pathName* **coords** ?*value*?](scale.htm#M25) 
[*pathName* **get** ?*x y*?](scale.htm#M26) 
[*pathName* **identify** *x y*](scale.htm#M27) 
[*pathName* **set** *value*](scale.htm#M28) 





 
[BINDINGS](scale.htm#M29) 
[SEE ALSO](scale.htm#M30) 
[KEYWORDS](scale.htm#M31) 








 Name
----

 scale — Create and manipulate 'scale' value-controlled slider widgets Synopsis
--------

 **scale** *pathName* ?*options*?  
 Standard options
----------------

  
**[-activebackground, activeBackground, Foreground](options.htm#M-activebackground)** 
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-orient, orient, Orient](options.htm#M-orient)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-repeatdelay, repeatDelay, RepeatDelay](options.htm#M-repeatdelay)** 
**[-repeatinterval, repeatInterval, RepeatInterval](options.htm#M-repeatinterval)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-troughcolor, troughColor, Background](options.htm#M-troughcolor)** 














 Widget-specific options
-----------------------

  Command-Line Name: **-bigincrement** Database Name: **bigIncrement** Database Class: **BigIncrement** 


Some interactions with the scale cause its value to change by “large” increments; this option specifies the size of the large increments. If specified as 0, the large increments default to 1/10 the range of the scale. 

Command-Line Name: **-command** Database Name: **command** Database Class: **Command** 


Specifies the prefix of a Tcl command to invoke whenever the scale's value is changed via a widget command. The actual command consists of this option followed by a space and a real number indicating the new value of the scale. 

Command-Line Name: **-digits** Database Name: **digits** Database Class: **Digits** 


An integer specifying how many significant digits should be retained when converting the value of the scale to a string. If the number is less than or equal to zero, then the scale picks the smallest value that guarantees that every possible slider position prints as a different string. 

Command-Line Name: **-from** Database Name: **from** Database Class: **From** 


A real value corresponding to the left or top end of the scale. 

Command-Line Name: **-label** Database Name: **label** Database Class: **Label** 


A string to display as a label for the scale. For vertical scales the label is displayed just to the right of the top end of the scale. For horizontal scales the label is displayed just above the left end of the scale. If the option is specified as an empty string, no label is displayed. 

Command-Line Name: **-length** Database Name: **length** Database Class: **Length** 


Specifies the desired long dimension of the scale in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**). For vertical scales this is the scale's height; for horizontal scales it is the scale's width. 

Command-Line Name: **-resolution** Database Name: **resolution** Database Class: **Resolution** 


A real value specifying the resolution for the scale. If this value is greater than zero then the scale's value will always be rounded to an even multiple of this value, as will tick marks and the endpoints of the scale. If the value is less than zero then no rounding occurs. Defaults to 1 (i.e., the value will be integral). 

Command-Line Name: **-showvalue** Database Name: **showValue** Database Class: **ShowValue** 


Specifies a boolean value indicating whether or not the current value of the scale is to be displayed. 

Command-Line Name: **-sliderlength** Database Name: **sliderLength** Database Class: **SliderLength** 


Specifies the size of the slider, measured in screen units along the slider's long dimension. The value may be specified in any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 

Command-Line Name: **-sliderrelief** Database Name: **sliderRelief** Database Class: **SliderRelief** 


Specifies the relief to use when drawing the slider, such as **raised** or **sunken**. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Specifies one of three states for the scale: **normal**, **active**, or **disabled**. If the scale is disabled then the value may not be changed and the scale will not activate. If the scale is active, the slider is displayed using the color specified by the **-activebackground** option. 

Command-Line Name: **-tickinterval** Database Name: **tickInterval** Database Class: **TickInterval** 


Must be a real value. Determines the spacing between numerical tick marks displayed below or to the left of the slider. If 0, no tick marks will be displayed. 

Command-Line Name: **-to** Database Name: **to** Database Class: **To** 


Specifies a real value corresponding to the right or bottom end of the scale. This value may be either less than or greater than the **-from** option. 

Command-Line Name: **-variable** Database Name: **variable** Database Class: **Variable** 


Specifies the name of a global variable to link to the scale. Whenever the value of the variable changes, the scale will update to reflect this value. Whenever the scale is manipulated interactively, the variable will be modified to reflect the scale's new value. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies the desired narrow dimension of the trough in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**). For vertical scales this is the trough's width; for horizontal scales this is the trough's height. 
 Description
-----------

 The **scale** command creates a new window (given by the *pathName* argument) and makes it into a scale widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the scale such as its colors, orientation, and relief. The **scale** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  A scale is a widget that displays a rectangular *trough* and a small *slider*. The trough corresponds to a range of real values (determined by the **-from**, **-to**, and **-resolution** options), and the position of the slider selects a particular real value. The slider's position (and hence the scale's value) may be adjusted with the mouse or keyboard as described in the **[BINDINGS](#M29)** section below. Whenever the scale's value is changed, a Tcl command is invoked (using the **-command** option) to notify other interested widgets of the change. In addition, the value of the scale can be linked to a Tcl variable (using the **-variable** option), so that changes in either are reflected in the other. 


 Three annotations may be displayed in a scale widget: a label appearing at the top right of the widget (top left for horizontal scales), a number displayed just to the left of the slider (just above the slider for horizontal scales), and a collection of numerical tick marks just to the left of the current value (just below the trough for horizontal scales). Each of these three annotations may be enabled or disabled using the configuration options. 


Widget command
--------------

 The **scale** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for scale widgets: 
 
*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **scale** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **scale** command. 


*pathName* **coords** ?*value*?
 Returns a list whose elements are the x and y coordinates of the point along the centerline of the trough that corresponds to *value*. If *value* is omitted then the scale's current value is used. 


*pathName* **get** ?*x y*?
 If *x* and *y* are omitted, returns the current value of the scale. If *x* and *y* are specified, they give pixel coordinates within the widget; the command returns the scale value corresponding to the given pixel. Only one of *x* or *y* is used: for horizontal scales *y* is ignored, and for vertical scales *x* is ignored. 


*pathName* **identify** *x y*

 Returns a string indicating what part of the scale lies under the coordinates given by *x* and *y*. A return value of **slider** means that the point is over the slider; **trough1** means that the point is over the portion of the slider above or to the left of the slider; and **trough2** means that the point is over the portion of the slider below or to the right of the slider. If the point is not over one of these elements, an empty string is returned. 


*pathName* **set** *value*

 This command is invoked to change the current value of the scale, and hence the position at which the slider is displayed. *Value* gives the new value for the scale. The command has no effect if the scale is disabled. 

 Bindings
--------

 Tk automatically creates class bindings for scales that give them the following default behavior. Where the behavior is different for vertical and horizontal scales, the horizontal behavior is described in parentheses. 
1. If button 1 is pressed in the trough, the scale's value will be incremented or decremented by the value of the **-resolution** option so that the slider moves in the direction of the cursor. If the button is held down, the action auto-repeats.
2. If button 1 is pressed over the slider, the slider can be dragged with the mouse.
3. If button 1 is pressed in the trough with the Control key down, the slider moves all the way to the end of its range, in the direction towards the mouse cursor.
4. If button 2 is pressed, the scale's value is set to the mouse position. If the mouse is dragged with button 2 down, the scale's value changes with the drag.
5. The Up and Left keys move the slider up (left) by the value of the **-resolution** option.
6. The Down and Right keys move the slider down (right) by the value of the **-resolution** option.
7. Control-Up and Control-Left move the slider up (left) by the value of the **-bigincrement** option.
8. Control-Down and Control-Right move the slider down (right) by the value of the **-bigincrement** option.
9. Home moves the slider to the top (left) end of its range.
10. End moves the slider to the bottom (right) end of its range.

  If the scale is disabled using the **-state** option then none of the above bindings have any effect. 


 The behavior of scales can be changed by defining new bindings for individual widgets or by redefining the class bindings. 


See also
--------

 **[ttk::scale](ttk_scale.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/scale.htm>

selection
=========

  
[NAME](selection.htm#M2) selection — Manipulate the X selection 
[SYNOPSIS](selection.htm#M3) 
[DESCRIPTION](selection.htm#M4)  
[**selection clear** ?**-displayof** *window*? ?**-selection** *selection*?](selection.htm#M5) 
[**selection get** ?**-displayof** *window*? ?**-selection** *selection*? ?**-type** *type*?](selection.htm#M6) 
[**selection handle** ?**-selection** *s*? ?**-type** *t*? ?**-format** *f*? *window command*](selection.htm#M7) 
[**selection own** ?**-displayof** *window*? ?**-selection** *selection*?](selection.htm#M8) 
[**selection own** ?**-command** *command*? ?**-selection** *selection*? *window*](selection.htm#M9) 




 
[EXAMPLES](selection.htm#M10) 
[SEE ALSO](selection.htm#M11) 
[KEYWORDS](selection.htm#M12) 





 Name
----

 selection — Manipulate the X selection Synopsis
--------

 **selection** *option* ?*arg arg ...*?  
 Description
-----------

 This command provides a Tcl interface to the X selection mechanism and implements the full selection functionality described in the X Inter-Client Communication Conventions Manual (ICCCM).  Note that for management of the **CLIPBOARD** selection (see below), the **[clipboard](clipboard.htm)** command may also be used. 


 The first argument to **selection** determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported: 


 
**selection clear** ?**-displayof** *window*? ?**-selection** *selection*?
 If *selection* exists anywhere on *window*'s display, clear it so that no window owns the selection anymore. *Selection* specifies the X selection that should be cleared, and should be an atom name such as **PRIMARY** or **CLIPBOARD**; see the Inter-Client Communication Conventions Manual for complete details. *Selection* defaults to **PRIMARY** and *window* defaults to “.”. Returns an empty string. 


**selection get** ?**-displayof** *window*? ?**-selection** *selection*? ?**-type** *type*?
 Retrieves the value of *selection* from *window*'s display and returns it as a result. *Selection* defaults to **PRIMARY** and *window* defaults to “.”. *Type* specifies the form in which the selection is to be returned (the desired “target” for conversion, in ICCCM terminology), and should be an atom name such as **STRING** or **FILE\_NAME**; see the Inter-Client Communication Conventions Manual for complete details. *Type* defaults to **STRING**. The selection owner may choose to return the selection in any of several different representation formats, such as **STRING**, **UTF8\_STRING**, **ATOM**, **INTEGER**, etc. (this format is different than the selection type; see the ICCCM for all the confusing details). If the selection is returned in a non-string format, such as **INTEGER** or **ATOM**, the **selection** command converts it to string format as a collection of fields separated by spaces: atoms are converted to their textual names, and anything else is converted to hexadecimal integers. Note that **selection get** does not retrieve the selection in the **UTF8\_STRING** format unless told to. 


**selection handle** ?**-selection** *s*? ?**-type** *t*? ?**-format** *f*? *window command*

 Creates a handler for selection requests, such that *command* will be executed whenever selection *s* is owned by *window* and someone attempts to retrieve it in the form given by type *t* (e.g. *t* is specified in the **selection get** command). *S* defaults to **PRIMARY**, *t* defaults to **STRING**, and *f* defaults to **STRING**. If *command* is an empty string then any existing handler for *window*, *t*, and *s* is removed. Note that when the selection is handled as type **STRING** it is also automatically handled as type **UTF8\_STRING** as well.  When *selection* is requested, *window* is the selection owner, and *type* is the requested type, *command* will be executed as a Tcl command with two additional numbers appended to it (with space separators). The two additional numbers are *offset* and *maxChars*: *offset* specifies a starting character position in the selection and *maxChars* gives the maximum number of characters to retrieve. The command should return a value consisting of at most *maxChars* of the selection, starting at position *offset*. For very large selections (larger than *maxChars*) the selection will be retrieved using several invocations of *command* with increasing *offset* values. If *command* returns a string whose length is less than *maxChars*, the return value is assumed to include all of the remainder of the selection; if the length of *command*'s result is equal to *maxChars* then *command* will be invoked again, until it eventually returns a result shorter than *maxChars*. The value of *maxChars* will always be relatively large (thousands of characters). 


 If *command* returns an error then the selection retrieval is rejected just as if the selection did not exist at all. 


 The *format* argument specifies the representation that should be used to transmit the selection to the requester (the second column of Table 2 of the ICCCM), and defaults to **STRING**. If *format* is **STRING**, the selection is transmitted as 8-bit ASCII characters (i.e. just in the form returned by *command*, in the system **[encoding](../tclcmd/encoding.htm)**; the **UTF8\_STRING** format always uses UTF-8 as its encoding). If *format* is **ATOM**, then the return value from *command* is divided into fields separated by white space; each field is converted to its atom value, and the 32-bit atom value is transmitted instead of the atom name. For any other *format*, the return value from *command* is divided into fields separated by white space and each field is converted to a 32-bit integer; an array of integers is transmitted to the selection requester. 


The *format* argument is needed only for compatibility with selection requesters that do not use Tk. If Tk is being used to retrieve the selection then the value is converted back to a string at the requesting end, so *format* is irrelevant. 




**selection own** ?**-displayof** *window*? ?**-selection** *selection*?

**selection own** ?**-command** *command*? ?**-selection** *selection*? *window*

 The first form of **selection own** returns the path name of the window in this application that owns *selection* on the display containing *window*, or an empty string if no window in this application owns the selection. *Selection* defaults to **PRIMARY** and *window* defaults to “.”.  The second form of **selection own** causes *window* to become the new owner of *selection* on *window*'s display, returning an empty string as result. The existing owner, if any, is notified that it has lost the selection. If *command* is specified, it is a Tcl script to execute when some other window claims ownership of the selection away from *window*. *Selection* defaults to PRIMARY. 



 Examples
--------

 On X11 platforms, one of the standard selections available is the **SECONDARY** selection. Hardly anything uses it, but here is how to read it using Tk: 

```
set selContents [**selection get** -selection SECONDARY]
```
  Many different types of data may be available for a selection; the special type **TARGETS** allows you to get a list of available types: 



```
foreach type [**selection get** -type TARGETS] {
   puts "Selection PRIMARY supports type $type"
}
```
  To claim the selection, you must first set up a handler to supply the data for the selection. Then you have to claim the selection... 



```
# Set up the data handler ready for incoming requests
set foo "This is a string with some data in it... blah blah"
**selection handle** -selection SECONDARY . getData
proc getData {offset maxChars} {
   puts "Retrieving selection starting at $offset"
   return [string range $::foo $offset [expr {$offset+$maxChars-1}]]
}

# Now we grab the selection itself
puts "Claiming selection"
**selection own** -command lost -selection SECONDARY .
proc lost {} {
   puts "Lost selection"
}
```
 See also
--------

 **[clipboard](clipboard.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/selection.htm>

ttk\_panedwindow
================

  
[NAME](ttk_panedwindow.htm#M2) ttk::panedwindow — Multi-pane container window 
[SYNOPSIS](ttk_panedwindow.htm#M3) 
[DESCRIPTION](ttk_panedwindow.htm#M4) 
[STANDARD OPTIONS](ttk_panedwindow.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 



 
[WIDGET-SPECIFIC OPTIONS](ttk_panedwindow.htm#M6)  
[-orient, orient, Orient](ttk_panedwindow.htm#M7) 
[-width, width, Width](ttk_panedwindow.htm#M8) 
[-height, height, Height](ttk_panedwindow.htm#M9) 


 
[PANE OPTIONS](ttk_panedwindow.htm#M10)  
[-weight, weight, Weight](ttk_panedwindow.htm#M11) 
 
[WIDGET COMMAND](ttk_panedwindow.htm#M12)  
[*pathname* **add** *subwindow options...*](ttk_panedwindow.htm#M13) 
[*pathname* **forget** *pane*](ttk_panedwindow.htm#M14) 
[*pathname* **identify** *component x y*](ttk_panedwindow.htm#M15)  
[*pathname* **identify element** *x y*](ttk_panedwindow.htm#M16) 
[*pathname* **identify sash** *x y*](ttk_panedwindow.htm#M17) 

 
[*pathname* **insert** *pos subwindow options...*](ttk_panedwindow.htm#M18) 
[*pathname* **pane** *pane -option* ?*value* ?*-option value...*](ttk_panedwindow.htm#M19) 
[*pathname* **panes**](ttk_panedwindow.htm#M20) 
[*pathname* **sashpos** *index* ?*newpos*?](ttk_panedwindow.htm#M21) 






 
[VIRTUAL EVENTS](ttk_panedwindow.htm#M22) 
[SEE ALSO](ttk_panedwindow.htm#M23) 








 Name
----

 ttk::panedwindow — Multi-pane container window Synopsis
--------

 **ttk::panedwindow** *pathname* ?*options*?  
 *pathname* **add** *window* ?*options...*?  
 *pathname* **insert** *index* *window* ?*options...*?  
 Description
-----------

 A **ttk::panedwindow** widget displays a number of subwindows, stacked either vertically or horizontally. The user may adjust the relative sizes of the subwindows by dragging the sash between panes. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 



 Widget-specific options
-----------------------

  Command-Line Name: **-orient** Database Name: **orient** Database Class: **Orient** 


Specifies the orientation of the window. If **vertical**, subpanes are stacked top-to-bottom; if **horizontal**, subpanes are stacked left-to-right. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


If present and greater than zero, specifies the desired width of the widget in pixels. Otherwise, the requested width is determined by the width of the managed windows. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


If present and greater than zero, specifies the desired height of the widget in pixels. Otherwise, the requested height is determined by the height of the managed windows. 
 Pane options
------------

 The following options may be specified for each pane:  Command-Line Name: **-weight** Database Name: **weight** Database Class: **Weight** 


An integer specifying the relative stretchability of the pane. When the paned window is resized, the extra space is added or subtracted to each pane proportionally to its **-weight**. 
 Widget command
--------------

 Supports the standard **configure**, **cget**, **state**, and **instate** commands; see *ttk::widget(n)* for details. Additional commands: 
 
*pathname* **add** *subwindow options...*

 Adds a new pane to the window. See **[PANE OPTIONS](#M10)** for the list of available options. 


*pathname* **forget** *pane*

 Removes the specified subpane from the widget. *pane* is either an integer index or the name of a managed subwindow. 


*pathname* **identify** *component x y*

 Returns the name of the element under the point given by *x* and *y*, or the empty string if no component is present at that location. If *component* is omitted, it defaults to **sash**. The following subcommands are supported: 
 
*pathname* **identify element** *x y*

 Returns the name of the element at the specified location. 


*pathname* **identify sash** *x y*

 Returns the index of the sash at the specified location. 




*pathname* **insert** *pos subwindow options...*

 Inserts a pane at the specified position. *pos* is either the string **end**, an integer index, or the name of a managed subwindow. If *subwindow* is already managed by the paned window, moves it to the specified position. See **[PANE OPTIONS](#M10)** for the list of available options. 


*pathname* **pane** *pane -option* ?*value* ?*-option value...*

 Query or modify the options of the specified *pane*, where *pane* is either an integer index or the name of a managed subwindow. If no *-option* is specified, returns a dictionary of the pane option values. If one *-option* is specified, returns the value of that *option*. Otherwise, sets the *-option*s to the corresponding *value*s. 


*pathname* **panes**

 Returns the list of all windows managed by the widget. 


*pathname* **sashpos** *index* ?*newpos*?
 If *newpos* is specified, sets the position of sash number *index*. May adjust the positions of adjacent sashes to ensure that positions are monotonically increasing. Sash positions are further constrained to be between 0 and the total size of the widget. Returns the new position of sash number *index*. 

 Virtual events
--------------

 The panedwindow widget generates an **<<EnteredChild>>** virtual event on LeaveNotify/NotifyInferior events, because Tk does not execute binding scripts for <Leave> events when the pointer crosses from a parent to a child. The panedwindow widget needs to know when that happens. See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[ttk::notebook](ttk_notebook.htm)**, **[panedwindow](panedwindow.htm)** Copyright © 2005 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_panedwindow.htm>

send
====

  
[NAME](send.htm#M2) send — Execute a command in a different application 
[SYNOPSIS](send.htm#M3) 
[DESCRIPTION](send.htm#M4)  
[**-async**](send.htm#M5) 
[**-displayof** *pathName*](send.htm#M6) 
[**--**](send.htm#M7) 


 
[APPLICATION NAMES](send.htm#M8) 
[DISABLING SENDS](send.htm#M9) 
[SECURITY](send.htm#M10) 
[EXAMPLE](send.htm#M11) 
[KEYWORDS](send.htm#M12) 







 Name
----

 send — Execute a command in a different application Synopsis
--------

 **send ?***options*? *app cmd* ?*arg arg ...*?  
 Description
-----------

 This command arranges for *cmd* (and *arg*s) to be executed in the application named by *app*. It returns the result or error from that command execution. *App* may be the name of any application whose main window is on the display containing the sender's main window; it need not be within the same process. If no *arg* arguments are present, then the command to be executed is contained entirely within the *cmd* argument. If one or more *arg*s are present, they are concatenated to form the command to be executed, just as for the **[eval](../tclcmd/eval.htm)** command.  If the initial arguments of the command begin with “-” they are treated as options. The following options are currently defined: 


 **-async**
 Requests asynchronous invocation. In this case the **send** command will complete immediately without waiting for *cmd* to complete in the target application; no result will be available and errors in the sent command will be ignored. If the target application is in the same process as the sending application then the **-async** option is ignored. 


**-displayof** *pathName*

 Specifies that the target application's main window is on the display of the window given by *pathName*, instead of the display containing the application's main window. 

**--**
 Serves no purpose except to terminate the list of options. This option is needed only if *app* could contain a leading “-” character. 

 Application names
-----------------

 The name of an application is set initially from the name of the program or script that created the application. You can query and change the name of an application with the **[tk appname](tk.htm)** command. Disabling sends
---------------

 If the **send** command is removed from an application (e.g. with the command **[rename](../tclcmd/rename.htm)** **send {}**) then the application will not respond to incoming send requests anymore, nor will it be able to issue outgoing requests. Communication can be reenabled by invoking the **[tk appname](tk.htm)** command. Security
--------

 The **send** command is potentially a serious security loophole. On Unix, any application that can connect to your X server can send scripts to your applications. These incoming scripts can use Tcl to read and write your files and invoke subprocesses under your name. Host-based access control such as that provided by **xhost** is particularly insecure, since it allows anyone with an account on particular hosts to connect to your server, and if disabled it allows anyone anywhere to connect to your server. In order to provide at least a small amount of security, Tk checks the access control being used by the server and rejects incoming sends unless (a) **xhost**-style access control is enabled (i.e. only certain hosts can establish connections) and (b) the list of enabled hosts is empty. This means that applications cannot connect to your server unless they use some other form of authorization such as that provide by **xauth**. Under Windows, **send** is currently disabled. Most of the functionality is provided by the **[dde](../tclcmd/dde.htm)** command instead. Example
-------

 This script fragment can be used to make an application that only runs once on a particular display. 
```
if {[tk appname FoobarApp] ne "FoobarApp"} {
    **send** -async FoobarApp RemoteStart $argv
    exit
}
# The command that will be called remotely, which raises
# the application main window and opens the requested files
proc RemoteStart args {
    raise .
    foreach filename $args {
        OpenFile $filename
    }
}
```
 Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/send.htm>

palette
=======

 Name
----

 tk\_setPalette, tk\_bisque — Modify the Tk color palette Synopsis
--------

 **tk\_setPalette** *background*  
 **tk\_setPalette** *name value* ?*name value ...*?  
 **tk\_bisque**  
 Description
-----------

 The **tk\_setPalette** procedure changes the color scheme for Tk. It does this by modifying the colors of existing widgets and by changing the option database so that future widgets will use the new color scheme. If **tk\_setPalette** is invoked with a single argument, the argument is the name of a color to use as the normal background color; **tk\_setPalette** will compute a complete color palette from this background color. Alternatively, the arguments to **tk\_setPalette** may consist of any number of *name*-*value* pairs, where the first argument of the pair is the name of an option in the Tk option database and the second argument is the new value to use for that option. The following database names are currently supported: 

|  |  |  |
| --- | --- | --- |
| **activeBackground** | **foreground** | **selectColor** |
| **activeForeground** | **highlightBackground** | **selectBackground** |
| **background** | **highlightColor** | **selectForeground** |
| **disabledForeground** | **insertBackground** | **troughColor** |

 **tk\_setPalette** tries to compute reasonable defaults for any options that you do not specify. You can specify options other than the above ones and Tk will change those options on widgets as well. This feature may be useful if you are using custom widgets with additional color options.  Once it has computed the new value to use for each of the color options, **tk\_setPalette** scans the widget hierarchy to modify the options of all existing widgets. For each widget, it checks to see if any of the above options is defined for the widget. If so, and if the option's current value is the default, then the value is changed; if the option has a value other than the default, **tk\_setPalette** will not change it. The default for an option is the one provided by the widget (**[lindex [$w configure $option] 3]**) unless **tk\_setPalette** has been run previously, in which case it is the value specified in the previous invocation of **tk\_setPalette**. 


 After modifying all the widgets in the application, **tk\_setPalette** adds options to the option database to change the defaults for widgets created in the future. The new options are added at priority **widgetDefault**, so they will be overridden by options from the .Xdefaults file or options specified on the command-line that creates a widget. 


 The procedure **tk\_bisque** is provided for backward compatibility: it restores the application's colors to the light brown (“bisque”) color scheme used in Tk 3.6 and earlier versions. 

 Copyright © 1995-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/palette.htm>

scrollbar
=========

  
[NAME](scrollbar.htm#M2) scrollbar — Create and manipulate 'scrollbar' scrolling control and indicator widgets 
[SYNOPSIS](scrollbar.htm#M3) 
[STANDARD OPTIONS](scrollbar.htm#M4)  
[-activebackground, activeBackground, Foreground](options.htm#M-activebackground) 
[-background or -bg, background, Background](options.htm#M-background) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-jump, jump, Jump](options.htm#M-jump) 
[-orient, orient, Orient](options.htm#M-orient) 
[-relief, relief, Relief](options.htm#M-relief) 
[-repeatdelay, repeatDelay, RepeatDelay](options.htm#M-repeatdelay) 
[-repeatinterval, repeatInterval, RepeatInterval](options.htm#M-repeatinterval) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-troughcolor, troughColor, Background](options.htm#M-troughcolor) 













 
[WIDGET-SPECIFIC OPTIONS](scrollbar.htm#M5)  
[-activerelief, activeRelief, ActiveRelief](scrollbar.htm#M6) 
[-command, command, Command](scrollbar.htm#M7) 
[-elementborderwidth, elementBorderWidth, BorderWidth](scrollbar.htm#M8) 
[-width, width, Width](scrollbar.htm#M9) 



 
[DESCRIPTION](scrollbar.htm#M10) 
[ELEMENTS](scrollbar.htm#M11)  
[**arrow1**](scrollbar.htm#M12) 
[**trough1**](scrollbar.htm#M13) 
[**slider**](scrollbar.htm#M14) 
[**trough2**](scrollbar.htm#M15) 
[**arrow2**](scrollbar.htm#M16) 




 
[WIDGET COMMAND](scrollbar.htm#M17)  
[*pathName* **activate** ?*element*?](scrollbar.htm#M18) 
[*pathName* **cget** *option*](scrollbar.htm#M19) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](scrollbar.htm#M20) 
[*pathName* **delta** *deltaX deltaY*](scrollbar.htm#M21) 
[*pathName* **fraction** *x y*](scrollbar.htm#M22) 
[*pathName* **get**](scrollbar.htm#M23) 
[*pathName* **identify** *x y*](scrollbar.htm#M24) 
[*pathName* **set** *first last*](scrollbar.htm#M25) 







 
[SCROLLING COMMANDS](scrollbar.htm#M26)  
[*prefix* **moveto** *fraction*](scrollbar.htm#M27) 
[*prefix* **scroll** *number* **units**](scrollbar.htm#M28) 
[*prefix* **scroll** *number* **pages**](scrollbar.htm#M29) 


 
[OLD COMMAND SYNTAX](scrollbar.htm#M30)  
[*pathName* **set** *totalUnits windowUnits firstUnit lastUnit*](scrollbar.htm#M31) 
  
[*prefix* *unit*](scrollbar.htm#M32) 
 
[BINDINGS](scrollbar.htm#M33) 
[EXAMPLE](scrollbar.htm#M34) 
[SEE ALSO](scrollbar.htm#M35) 
[KEYWORDS](scrollbar.htm#M36) 












 Name
----

 scrollbar — Create and manipulate 'scrollbar' scrolling control and indicator widgets Synopsis
--------

 **scrollbar** *pathName* ?*options*?  
 Standard options
----------------

  
**[-activebackground, activeBackground, Foreground](options.htm#M-activebackground)** 
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-jump, jump, Jump](options.htm#M-jump)** 
**[-orient, orient, Orient](options.htm#M-orient)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-repeatdelay, repeatDelay, RepeatDelay](options.htm#M-repeatdelay)** 
**[-repeatinterval, repeatInterval, RepeatInterval](options.htm#M-repeatinterval)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-troughcolor, troughColor, Background](options.htm#M-troughcolor)** 













 Widget-specific options
-----------------------

  Command-Line Name: **-activerelief** Database Name: **activeRelief** Database Class: **ActiveRelief** 


Specifies the relief to use when displaying the element that is active, if any. Elements other than the active element are always displayed with a raised relief. 

Command-Line Name: **-command** Database Name: **command** Database Class: **Command** 


Specifies the prefix of a Tcl command to invoke to change the view in the widget associated with the scrollbar. When a user requests a view change by manipulating the scrollbar, a Tcl command is invoked. The actual command consists of this option followed by additional information as described later. This option almost always has a value such as **.t xview** or **.t yview**, consisting of the name of a widget and either **xview** (if the scrollbar is for horizontal scrolling) or **yview** (for vertical scrolling). All scrollable widgets have **xview** and **yview** commands that take exactly the additional arguments appended by the scrollbar as described in **[SCROLLING COMMANDS](#M26)** below. 

Command-Line Name: **-elementborderwidth** Database Name: **elementBorderWidth** Database Class: **BorderWidth** 


Specifies the width of borders drawn around the internal elements of the scrollbar (the two arrows and the slider). The value may have any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. If this value is less than zero, the value of the **-borderwidth** option is used in its place. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies the desired narrow dimension of the scrollbar window, not including 3-D border, if any. For vertical scrollbars this will be the width and for horizontal scrollbars this will be the height. The value may have any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 
 Description
-----------

 The **scrollbar** command creates a new window (given by the *pathName* argument) and makes it into a scrollbar widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the scrollbar such as its colors, orientation, and relief. The **scrollbar** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  A scrollbar is a widget that displays two arrows, one at each end of the scrollbar, and a *slider* in the middle portion of the scrollbar. It provides information about what is visible in an *associated window* that displays a document of some sort (such as a file being edited or a drawing). The position and size of the slider indicate which portion of the document is visible in the associated window. For example, if the slider in a vertical scrollbar covers the top third of the area between the two arrows, it means that the associated window displays the top third of its document. 


 Scrollbars can be used to adjust the view in the associated window by clicking or dragging with the mouse. See the **[BINDINGS](#M33)** section below for details. 


Elements
--------

 A scrollbar displays five elements, which are referred to in the widget commands for the scrollbar: 
 **arrow1**
 The top or left arrow in the scrollbar. 

**trough1**
 The region between the slider and **arrow1**. 

**slider**
 The rectangle that indicates what is visible in the associated widget. 

**trough2**
 The region between the slider and **arrow2**. 

**arrow2**
 The bottom or right arrow in the scrollbar. 

 Widget command
--------------

 The **scrollbar** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for scrollbar widgets: 
 
*pathName* **activate** ?*element*?
 Marks the element indicated by *element* as active, which causes it to be displayed as specified by the **-activebackground** and **-activerelief** options. The only element values understood by this command are **arrow1**, **slider**, or **arrow2**. If any other value is specified then no element of the scrollbar will be active. If *element* is not specified, the command returns the name of the element that is currently active, or an empty string if no element is active. 


*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **scrollbar** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **scrollbar** command. 


*pathName* **delta** *deltaX deltaY*

 Returns a real number indicating the fractional change in the scrollbar setting that corresponds to a given change in slider position. For example, if the scrollbar is horizontal, the result indicates how much the scrollbar setting must change to move the slider *deltaX* pixels to the right (*deltaY* is ignored in this case). If the scrollbar is vertical, the result indicates how much the scrollbar setting must change to move the slider *deltaY* pixels down. The arguments and the result may be zero or negative. 


*pathName* **fraction** *x y*

 Returns a real number between 0 and 1 indicating where the point given by *x* and *y* lies in the trough area of the scrollbar. The value 0 corresponds to the top or left of the trough, the value 1 corresponds to the bottom or right, 0.5 corresponds to the middle, and so on. *X* and *y* must be pixel coordinates relative to the scrollbar widget. If *x* and *y* refer to a point outside the trough, the closest point in the trough is used. 


*pathName* **get**

 Returns the scrollbar settings in the form of a list whose elements are the arguments to the most recent **set** widget command. 


*pathName* **identify** *x y*

 Returns the name of the element under the point given by *x* and *y* (such as **arrow1**), or an empty string if the point does not lie in any element of the scrollbar. *X* and *y* must be pixel coordinates relative to the scrollbar widget. 


*pathName* **set** *first last*

 This command is invoked by the scrollbar's associated widget to tell the scrollbar about the current view in the widget. The command takes two arguments, each of which is a real fraction between 0 and 1. The fractions describe the range of the document that is visible in the associated widget. For example, if *first* is 0.2 and *last* is 0.4, it means that the first part of the document visible in the window is 20% of the way through the document, and the last visible part is 40% of the way through. 

 Scrolling commands
------------------

 When the user interacts with the scrollbar, for example by dragging the slider, the scrollbar notifies the associated widget that it must change its view. The scrollbar makes the notification by evaluating a Tcl command generated from the scrollbar's **-command** option. The command may take any of the following forms. In each case, *prefix* is the contents of the **-command** option, which usually has a form like “**.t”yview**
 
*prefix* **moveto** *fraction*

 *Fraction* is a real number between 0 and 1. The widget should adjust its view so that the point given by *fraction* appears at the beginning of the widget. If *fraction* is 0 it refers to the beginning of the document. 1.0 refers to the end of the document, 0.333 refers to a point one-third of the way through the document, and so on. 


*prefix* **scroll** *number* **units**

 The widget should adjust its view by *number* units. The units are defined in whatever way makes sense for the widget, such as characters or lines in a text widget. *Number* is either 1, which means one unit should scroll off the top or left of the window, or -1, which means that one unit should scroll off the bottom or right of the window. 


*prefix* **scroll** *number* **pages**

 The widget should adjust its view by *number* pages. It is up to the widget to define the meaning of a page; typically it is slightly less than what fits in the window, so that there is a slight overlap between the old and new views. *Number* is either 1, which means the next page should become visible, or -1, which means that the previous page should become visible. 

 Old command syntax
------------------

 In versions of Tk before 4.0, the **set** and **get** widget commands used a different form. This form is still supported for backward compatibility, but it is deprecated. In the old command syntax, the **set** widget command has the following form: 
 
*pathName* **set** *totalUnits windowUnits firstUnit lastUnit*

 In this form the arguments are all integers. *TotalUnits* gives the total size of the object being displayed in the associated widget. The meaning of one unit depends on the associated widget; for example, in a text editor widget units might correspond to lines of text. *WindowUnits* indicates the total number of units that can fit in the associated window at one time. *FirstUnit* and *lastUnit* give the indices of the first and last units currently visible in the associated window (zero corresponds to the first unit of the object). 

  Under the old syntax the **get** widget command returns a list of four integers, consisting of the *totalUnits*, *windowUnits*, *firstUnit*, and *lastUnit* values from the last **set** widget command. 


 The commands generated by scrollbars also have a different form when the old syntax is being used: 


 
*prefix* *unit*

 *Unit* is an integer that indicates what should appear at the top or left of the associated widget's window. It has the same meaning as the *firstUnit* and *lastUnit* arguments to the **set** widget command. 

  The most recent **set** widget command determines whether or not to use the old syntax. If it is given two real arguments then the new syntax will be used in the future, and if it is given four integer arguments then the old syntax will be used. 


Bindings
--------

 Tk automatically creates class bindings for scrollbars that give them the following default behavior. If the behavior is different for vertical and horizontal scrollbars, the horizontal behavior is described in parentheses. 
1. Pressing button 1 over **arrow1** causes the view in the associated widget to shift up (left) by one unit so that the document appears to move down (right) one unit. If the button is held down, the action auto-repeats.
2. Pressing button 1 over **trough1** causes the view in the associated widget to shift up (left) by one screenful so that the document appears to move down (right) one screenful. If the button is held down, the action auto-repeats.
3. Pressing button 1 over the slider and dragging causes the view to drag with the slider. If the **jump** option is true, then the view does not drag along with the slider; it changes only when the mouse button is released.
4. Pressing button 1 over **trough2** causes the view in the associated widget to shift down (right) by one screenful so that the document appears to move up (left) one screenful. If the button is held down, the action auto-repeats.
5. Pressing button 1 over **arrow2** causes the view in the associated widget to shift down (right) by one unit so that the document appears to move up (left) one unit. If the button is held down, the action auto-repeats.
6. If button 2 is pressed over the trough or the slider, it sets the view to correspond to the mouse position; dragging the mouse with button 2 down causes the view to drag with the mouse. If button 2 is pressed over one of the arrows, it causes the same behavior as pressing button 1.
7. If button 1 is pressed with the Control key down, then if the mouse is over **arrow1** or **trough1** the view changes to the very top (left) of the document; if the mouse is over **arrow2** or **trough2** the view changes to the very bottom (right) of the document; if the mouse is anywhere else then the button press has no effect.
8. In vertical scrollbars the Up and Down keys have the same behavior as mouse clicks over **arrow1** and **arrow2**, respectively. In horizontal scrollbars these keys have no effect.
9. In vertical scrollbars Control-Up and Control-Down have the same behavior as mouse clicks over **trough1** and **trough2**, respectively. In horizontal scrollbars these keys have no effect.
10. In horizontal scrollbars the Up and Down keys have the same behavior as mouse clicks over **arrow1** and **arrow2**, respectively. In vertical scrollbars these keys have no effect.
11. In horizontal scrollbars Control-Up and Control-Down have the same behavior as mouse clicks over **trough1** and **trough2**, respectively. In vertical scrollbars these keys have no effect.
12. The Prior and Next keys have the same behavior as mouse clicks over **trough1** and **trough2**, respectively.
13. The Home key adjusts the view to the top (left edge) of the document.
14. The End key adjusts the view to the bottom (right edge) of the document.

 Example
-------

 Create a window with a scrollable **[text](text.htm)** widget: 
```
toplevel .tl
text .tl.t -yscrollcommand {.tl.s set}
**scrollbar** .tl.s -command {.tl.t yview}
grid .tl.t .tl.s -sticky nsew
grid columnconfigure .tl 0 -weight 1
grid rowconfigure .tl 0 -weight 1
```
 See also
--------

 **ttk:scrollbar** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/scrollbar.htm>

ttk\_progressbar
================

  
[NAME](ttk_progressbar.htm#M2) ttk::progressbar — Provide progress feedback 
[SYNOPSIS](ttk_progressbar.htm#M3) 
[DESCRIPTION](ttk_progressbar.htm#M4) 
[STANDARD OPTIONS](ttk_progressbar.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 



 
[WIDGET-SPECIFIC OPTIONS](ttk_progressbar.htm#M6)  
[-orient, orient, Orient](ttk_progressbar.htm#M7) 
[-length, length, Length](ttk_progressbar.htm#M8) 
[-mode, mode, Mode](ttk_progressbar.htm#M9) 
[-maximum, maximum, Maximum](ttk_progressbar.htm#M10) 
[-value, value, Value](ttk_progressbar.htm#M11) 
[-variable, variable, Variable](ttk_progressbar.htm#M12) 
[-phase, phase, Phase](ttk_progressbar.htm#M13) 






 
[WIDGET COMMAND](ttk_progressbar.htm#M14)  
[*pathName* **cget** *option*](ttk_progressbar.htm#M15) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](ttk_progressbar.htm#M16) 
[*pathName* **identify** *x y*](ttk_progressbar.htm#M17) 
[*pathName* **instate** *statespec* ?*script*?](ttk_progressbar.htm#M18) 
[*pathName* **start** ?*interval*?](ttk_progressbar.htm#M19) 
[*pathName* **state** ?*stateSpec*?](ttk_progressbar.htm#M20) 
[*pathName* **step** ?*amount*?](ttk_progressbar.htm#M21) 
[*pathName* **stop**](ttk_progressbar.htm#M22) 







 
[SEE ALSO](ttk_progressbar.htm#M23) 






 Name
----

 ttk::progressbar — Provide progress feedback Synopsis
--------

 **ttk::progressbar** *pathName* ?*options*?  
 Description
-----------

 A **ttk::progressbar** widget shows the status of a long-running operation. They can operate in two modes: *determinate* mode shows the amount completed relative to the total amount of work to be done, and *indeterminate* mode provides an animated display to let the user know that something is happening. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 



 Widget-specific options
-----------------------

  Command-Line Name: **-orient** Database Name: **orient** Database Class: **Orient** 


One of **horizontal** or **vertical**. Specifies the orientation of the progress bar. 

Command-Line Name: **-length** Database Name: **length** Database Class: **Length** 


Specifies the length of the long axis of the progress bar (width if horizontal, height if vertical). 

Command-Line Name: **-mode** Database Name: **mode** Database Class: **Mode** 


One of **determinate** or **indeterminate**. 

Command-Line Name: **-maximum** Database Name: **maximum** Database Class: **Maximum** 


A floating point number specifying the maximum **-value**. Defaults to 100. 

Command-Line Name: **-value** Database Name: **value** Database Class: **Value** 


The current value of the progress bar. In *determinate* mode, this represents the amount of work completed. In *indeterminate* mode, it is interpreted modulo **-maximum**; that is, the progress bar completes one “cycle” when the **-value** increases by **-maximum**. 

Command-Line Name: **-variable** Database Name: **variable** Database Class: **Variable** 


The name of a global Tcl variable which is linked to the **-value**. If specified, the **-value** of the progress bar is automatically set to the value of the variable whenever the latter is modified. 

Command-Line Name: **-phase** Database Name: **phase** Database Class: **Phase** 


Read-only option. The widget periodically increments the value of this option whenever the **-value** is greater than 0 and, in *determinate* mode, less than **-maximum**. This option may be used by the current theme to provide additional animation effects. 
 Widget command
--------------


 
*pathName* **cget** *option*

 Returns the current value of the specified *option*; see *ttk::widget(n)*. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Modify or query widget options; see *ttk::widget(n)*. 


*pathName* **identify** *x y*

 Returns the name of the element at position *x*, *y*. See *ttk::widget(n)*. 


*pathName* **instate** *statespec* ?*script*?
 Test the widget state; see *ttk::widget(n)*. 


*pathName* **start** ?*interval*?
 Begin autoincrement mode: schedules a recurring timer event that calls **step** every *interval* milliseconds. If omitted, *interval* defaults to 50 milliseconds (20 steps/second). 


*pathName* **state** ?*stateSpec*?
 Modify or query the widget state; see *ttk::widget(n)*. 


*pathName* **step** ?*amount*?
 Increments the **-value** by *amount*. *amount* defaults to 1.0 if omitted. 


*pathName* **stop**

 Stop autoincrement mode: cancels any recurring timer event initiated by *pathName* **start**. 

 See also
--------

 **[ttk::widget](ttk_widget.htm)** Copyright © 2005 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_progressbar.htm>

ttk\_radiobutton
================

  
[NAME](ttk_radiobutton.htm#M2) ttk::radiobutton — Mutually exclusive option widget 
[SYNOPSIS](ttk_radiobutton.htm#M3) 
[DESCRIPTION](ttk_radiobutton.htm#M4) 
[STANDARD OPTIONS](ttk_radiobutton.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-compound, compound, Compound](ttk_widget.htm#M-compound) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-image, image, Image](ttk_widget.htm#M-image) 
[-state, state, State](ttk_widget.htm#M-state) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 
[-text, text, Text](ttk_widget.htm#M-text) 
[-textvariable, textVariable, Variable](ttk_widget.htm#M-textvariable) 
[-underline, underline, Underline](ttk_widget.htm#M-underline) 
[-width, width, Width](ttk_widget.htm#M-width) 










 
[WIDGET-SPECIFIC OPTIONS](ttk_radiobutton.htm#M6)  
[-command, command, Command](ttk_radiobutton.htm#M7) 
[-value, Value, Value](ttk_radiobutton.htm#M8) 
[-variable, variable, Variable](ttk_radiobutton.htm#M9) 


 
[WIDGET COMMAND](ttk_radiobutton.htm#M10)  
[*pathname* **invoke**](ttk_radiobutton.htm#M11) 
 
[WIDGET STATES](ttk_radiobutton.htm#M12) 
[STANDARD STYLES](ttk_radiobutton.htm#M13) 
[SEE ALSO](ttk_radiobutton.htm#M14) 
[KEYWORDS](ttk_radiobutton.htm#M15) 









 Name
----

 ttk::radiobutton — Mutually exclusive option widget Synopsis
--------

 **ttk::radiobutton** *pathName* ?*options*?  
 Description
-----------

 **ttk::radiobutton** widgets are used in groups to show or change a set of mutually-exclusive options. Radiobuttons are linked to a Tcl variable, and have an associated value; when a radiobutton is clicked, it sets the variable to its associated value. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-compound, compound, Compound](ttk_widget.htm#M-compound)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-image, image, Image](ttk_widget.htm#M-image)** 
**[-state, state, State](ttk_widget.htm#M-state)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 
**[-text, text, Text](ttk_widget.htm#M-text)** 
**[-textvariable, textVariable, Variable](ttk_widget.htm#M-textvariable)** 
**[-underline, underline, Underline](ttk_widget.htm#M-underline)** 
**[-width, width, Width](ttk_widget.htm#M-width)** 










 Widget-specific options
-----------------------

  Command-Line Name: **-command** Database Name: **command** Database Class: **Command** 


A Tcl script to evaluate whenever the widget is invoked. 

Command-Line Name: **-value** Database Name: **Value** Database Class: **Value** 


The value to store in the associated **-variable** when the widget is selected. 

Command-Line Name: **-variable** Database Name: **variable** Database Class: **Variable** 


The name of a global variable whose value is linked to the widget. Default value is **::selectedButton**. 
 Widget command
--------------

 In addition to the standard **cget**, **configure**, **identify**, **instate**, and **state** commands, radiobuttons support the following additional widget commands: 
 
*pathname* **invoke**

 Sets the **-variable** to the **-value**, selects the widget, and evaluates the associated **-command**. Returns the result of the **-command**, or the empty string if no **-command** is specified. 

 Widget states
-------------

 The widget does not respond to user input if the **disabled** state is set. The widget sets the **selected** state whenever the linked **-variable** is set to the widget's **-value**, and clears it otherwise. The widget sets the **alternate** state whenever the linked **-variable** is unset. (The **alternate** state may be used to indicate a “tri-state” or “indeterminate” selection.) Standard styles
---------------

 **Ttk::radiobutton** widgets support the **Toolbutton** style in all standard themes, which is useful for creating widgets for toolbars. See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[ttk::checkbutton](ttk_checkbutton.htm)**, **[radiobutton](radiobutton.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_radiobutton.htm>

grid
====

  
[NAME](grid.htm#M2) grid — Geometry manager that arranges widgets in a grid 
[SYNOPSIS](grid.htm#M3) 
[DESCRIPTION](grid.htm#M4)  
[**grid** *slave* ?*slave ...*? ?*options*?](grid.htm#M5) 
[**grid anchor** *master* ?*anchor*?](grid.htm#M6) 
[**grid bbox** *master* ?*column row*? ?*column2 row2*?](grid.htm#M7) 
[**grid columnconfigure** *master index* ?*-option value...*?](grid.htm#M8) 
[**grid configure** *slave* ?*slave ...*? ?*options*?](grid.htm#M9)  
[**-column** *n*](grid.htm#M10) 
[**-columnspan** *n*](grid.htm#M11) 
[**-in** *other*](grid.htm#M12) 
[**-ipadx** *amount*](grid.htm#M13) 
[**-ipady** *amount*](grid.htm#M14) 
[**-padx** *amount*](grid.htm#M15) 
[**-pady** *amount*](grid.htm#M16) 
[**-row** *n*](grid.htm#M17) 
[**-rowspan** *n*](grid.htm#M18) 
[**-sticky** *style*](grid.htm#M19) 









 
[**grid forget** *slave* ?*slave ...*?](grid.htm#M20) 
[**grid info** *slave*](grid.htm#M21) 
[**grid location** *master x y*](grid.htm#M22) 
[**grid propagate** *master* ?*boolean*?](grid.htm#M23) 
[**grid rowconfigure** *master index* ?*-option value...*?](grid.htm#M24) 
[**grid remove** *slave* ?*slave ...*?](grid.htm#M25) 
[**grid size** *master*](grid.htm#M26) 
[**grid slaves** *master* ?*-option value*?](grid.htm#M27) 












 
[RELATIVE PLACEMENT](grid.htm#M28)  
[**-**](grid.htm#M29) 
[**x**](grid.htm#M30) 
[**^**](grid.htm#M31) 


 
[THE GRID ALGORITHM](grid.htm#M32) 
[GEOMETRY PROPAGATION](grid.htm#M33) 
[RESTRICTIONS ON MASTER WINDOWS](grid.htm#M34) 
[STACKING ORDER](grid.htm#M35) 
[CREDITS](grid.htm#M36) 
[EXAMPLES](grid.htm#M37) 
[SEE ALSO](grid.htm#M38) 
[KEYWORDS](grid.htm#M39) 











 Name
----

 grid — Geometry manager that arranges widgets in a grid Synopsis
--------

 **grid** *option arg* ?*arg ...*?  
 Description
-----------

 The **grid** command is used to communicate with the grid geometry manager that arranges widgets in rows and columns inside of another window, called the geometry master (or master window). The **grid** command can have any of several forms, depending on the *option* argument: 
 
**grid** *slave* ?*slave ...*? ?*options*?
 If the first argument to **grid** is suitable as the first slave argument to **grid configure**, either a window name (any value starting with **.**) or one of the characters **x** or **^** (see the **[RELATIVE PLACEMENT](#M28)** section below), then the command is processed in the same way as **grid configure**. 


**grid anchor** *master* ?*anchor*?
 The anchor value controls how to place the grid within the master when no row/column has any weight. See **[THE GRID ALGORITHM](#M32)** below for further details. The default *anchor* is *nw*. 


**grid bbox** *master* ?*column row*? ?*column2 row2*?
 With no arguments, the bounding box (in pixels) of the grid is returned. The return value consists of 4 integers. The first two are the pixel offset from the master window (x then y) of the top-left corner of the grid, and the second two integers are the width and height of the grid, also in pixels. If a single *column* and *row* is specified on the command line, then the bounding box for that cell is returned, where the top left cell is numbered from zero. If both *column* and *row* arguments are specified, then the bounding box spanning the rows and columns indicated is returned. 


**grid columnconfigure** *master index* ?*-option value...*?
 Query or set the column properties of the *index* column of the geometry master, *master*. The valid options are **-minsize**, **-weight**, **-uniform** and **-pad**. If one or more options are provided, then *index* may be given as a list of column indices to which the configuration options will operate on. Indices may be integers, window names or the keyword *all*. For *all* the options apply to all columns currently occupied be slave windows. For a window name, that window must be a slave of this master and the options apply to all columns currently occupied be the slave. The **-minsize** option sets the minimum size, in screen units, that will be permitted for this column. The **-weight** option (an integer value) sets the relative weight for apportioning any extra spaces among columns. A weight of zero (0) indicates the column will not deviate from its requested size. A column whose weight is two will grow at twice the rate as a column of weight one when extra space is allocated to the layout. The **-uniform** option, when a non-empty value is supplied, places the column in a *uniform group* with other columns that have the same value for **-uniform**. The space for columns belonging to a uniform group is allocated so that their sizes are always in strict proportion to their **-weight** values. See **[THE GRID ALGORITHM](#M32)** below for further details. The **-pad** option specifies the number of screen units that will be added to the largest window contained completely in that column when the grid geometry manager requests a size from the containing window. If only an option is specified, with no value, the current value of that option is returned. If only the master window and index is specified, all the current settings are returned in a list of “-option value” pairs. 


**grid configure** *slave* ?*slave ...*? ?*options*?
 The arguments consist of the names of one or more slave windows followed by pairs of arguments that specify how to manage the slaves. The characters **-**, **x** and **^**, can be specified instead of a window name to alter the default location of a *slave*, as described in the **[RELATIVE PLACEMENT](#M28)** section, below. The following options are supported: 
 
**-column** *n*

 Insert the slave so that it occupies the *n*th column in the grid. Column numbers start with 0. If this option is not supplied, then the slave is arranged just to the right of previous slave specified on this call to **grid**, or column “0” if it is the first slave. For each **x** that immediately precedes the *slave*, the column position is incremented by one. Thus the **x** represents a blank column for this row in the grid. 


**-columnspan** *n*

 Insert the slave so that it occupies *n* columns in the grid. The default is one column, unless the window name is followed by a **-**, in which case the columnspan is incremented once for each immediately following **-**. 


**-in** *other*

 Insert the slave(s) in the master window given by *other*. The default is the first slave's parent window. 


**-ipadx** *amount*

 The *amount* specifies how much horizontal internal padding to leave on each side of the slave(s). This is space is added inside the slave(s) border. The *amount* must be a valid screen distance, such as **2** or **.5c**. It defaults to 0. 


**-ipady** *amount*

 The *amount* specifies how much vertical internal padding to leave on the top and bottom of the slave(s). This space is added inside the slave(s) border. The *amount* defaults to 0. 


**-padx** *amount*

 The *amount* specifies how much horizontal external padding to leave on each side of the slave(s), in screen units. *Amount* may be a list of two values to specify padding for left and right separately. The *amount* defaults to 0. This space is added outside the slave(s) border. 


**-pady** *amount*

 The *amount* specifies how much vertical external padding to leave on the top and bottom of the slave(s), in screen units. *Amount* may be a list of two values to specify padding for top and bottom separately. The *amount* defaults to 0. This space is added outside the slave(s) border. 


**-row** *n*

 Insert the slave so that it occupies the *n*th row in the grid. Row numbers start with 0. If this option is not supplied, then the slave is arranged on the same row as the previous slave specified on this call to **grid**, or the first unoccupied row if this is the first slave. 


**-rowspan** *n*

 Insert the slave so that it occupies *n* rows in the grid. The default is one row. If the next **grid** command contains **^** characters instead of *slaves* that line up with the columns of this *slave*, then the **rowspan** of this *slave* is extended by one. 


**-sticky** *style*

 If a slave's cell is larger than its requested dimensions, this option may be used to position (or stretch) the slave within its cell. *Style* is a string that contains zero or more of the characters **n**, **s**, **e** or **w**. The string can optionally contains spaces or commas, but they are ignored. Each letter refers to a side (north, south, east, or west) that the slave will “stick” to. If both **n** and **s** (or **e** and **w**) are specified, the slave will be stretched to fill the entire height (or width) of its cavity. The **-sticky** option subsumes the combination of **-anchor** and **-fill** that is used by **[pack](pack.htm)**. The default is “”, which causes the slave to be centered in its cavity, at its requested size. 

If any of the slaves are already managed by the geometry manager then any unspecified options for them retain their previous values rather than receiving default values.




**grid forget** *slave* ?*slave ...*?
 Removes each of the *slave*s from grid for its master and unmaps their windows. The slaves will no longer be managed by the grid geometry manager. The configuration options for that window are forgotten, so that if the slave is managed once more by the grid geometry manager, the initial default settings are used. 


**grid info** *slave*

 Returns a list whose elements are the current configuration state of the slave given by *slave* in the same option-value form that might be specified to **grid configure**. The first two elements of the list are “**-in** *master*” where *master* is the slave's master. 


**grid location** *master x y*

 Given *x* and *y* values in screen units relative to the master window, the column and row number at that *x* and *y* location is returned. For locations that are above or to the left of the grid, **-1** is returned. 


**grid propagate** *master* ?*boolean*?
 If *boolean* has a true boolean value such as **1** or **on** then propagation is enabled for *master*, which must be a window name (see **[GEOMETRY PROPAGATION](#M33)** below). If *boolean* has a false boolean value then propagation is disabled for *master*. In either of these cases an empty string is returned. If *boolean* is omitted then the command returns **0** or **1** to indicate whether propagation is currently enabled for *master*. Propagation is enabled by default. 


**grid rowconfigure** *master index* ?*-option value...*?
 Query or set the row properties of the *index* row of the geometry master, *master*. The valid options are **-minsize**, **-weight**, **-uniform** and **-pad**. If one or more options are provided, then *index* may be given as a list of row indices to which the configuration options will operate on. Indices may be integers, window names or the keyword *all*. For *all* the options apply to all rows currently occupied be slave windows. For a window name, that window must be a slave of this master and the options apply to all rows currently occupied be the slave. The **-minsize** option sets the minimum size, in screen units, that will be permitted for this row. The **-weight** option (an integer value) sets the relative weight for apportioning any extra spaces among rows. A weight of zero (0) indicates the row will not deviate from its requested size. A row whose weight is two will grow at twice the rate as a row of weight one when extra space is allocated to the layout. The **-uniform** option, when a non-empty value is supplied, places the row in a *uniform group* with other rows that have the same value for **-uniform**. The space for rows belonging to a uniform group is allocated so that their sizes are always in strict proportion to their **-weight** values. See **[THE GRID ALGORITHM](#M32)** below for further details. The **-pad** option specifies the number of screen units that will be added to the largest window contained completely in that row when the grid geometry manager requests a size from the containing window. If only an option is specified, with no value, the current value of that option is returned. If only the master window and index is specified, all the current settings are returned in a list of “-option value” pairs. 


**grid remove** *slave* ?*slave ...*?
 Removes each of the *slave*s from grid for its master and unmaps their windows. The slaves will no longer be managed by the grid geometry manager. However, the configuration options for that window are remembered, so that if the slave is managed once more by the grid geometry manager, the previous values are retained. 


**grid size** *master*

 Returns the size of the grid (in columns then rows) for *master*. The size is determined either by the *slave* occupying the largest row or column, or the largest column or row with a **-minsize**, **-weight**, or **-pad** that is non-zero. 


**grid slaves** *master* ?*-option value*?
 If no options are supplied, a list of all of the slaves in *master* are returned, most recently manages first. *Option* can be either **-row** or **-column** which causes only the slaves in the row (or column) specified by *value* to be returned. 

 Relative placement
------------------

 The **grid** command contains a limited set of capabilities that permit layouts to be created without specifying the row and column information for each slave. This permits slaves to be rearranged, added, or removed without the need to explicitly specify row and column information. When no column or row information is specified for a *slave*, default values are chosen for **-column**, **-row**, **-columnspan** and **-rowspan** at the time the *slave* is managed. The values are chosen based upon the current layout of the grid, the position of the *slave* relative to other *slave*s in the same grid command, and the presence of the characters **-**, **x**, and **^** in **grid** command where *slave* names are normally expected. 
 **-**
 This increases the **-columnspan** of the *slave* to the left. Several **-**'s in a row will successively increase the number of columns spanned. A **-** may not follow a **^** or a **x**, nor may it be the first *slave* argument to **grid configure**. 

**x**
 This leaves an empty column between the *slave* on the left and the *slave* on the right. 

**^**
 This extends the **-rowspan** of the *slave* above the **^**'s in the grid. The number of **^**'s in a row must match the number of columns spanned by the *slave* above it. 

 The grid algorithm
------------------

 The grid geometry manager lays out its slaves in three steps. In the first step, the minimum size needed to fit all of the slaves is computed, then (if propagation is turned on), a request is made of the master window to become that size. In the second step, the requested size is compared against the actual size of the master. If the sizes are different, then spaces is added to or taken away from the layout as needed. For the final step, each slave is positioned in its row(s) and column(s) based on the setting of its *sticky* flag.  To compute the minimum size of a layout, the grid geometry manager first looks at all slaves whose **-columnspan** and **-rowspan** values are one, and computes the nominal size of each row or column to be either the *minsize* for that row or column, or the sum of the *pad*ding plus the size of the largest slave, whichever is greater. After that the rows or columns in each uniform group adapt to each other. Then the slaves whose row-spans or column-spans are greater than one are examined. If a group of rows or columns need to be increased in size in order to accommodate these slaves, then extra space is added to each row or column in the group according to its *weight*. For each group whose weights are all zero, the additional space is apportioned equally. 


 When multiple rows or columns belong to a uniform group, the space allocated to them is always in proportion to their weights. (A weight of zero is considered to be 1.) In other words, a row or column configured with **-weight 1 -uniform a** will have exactly the same size as any other row or column configured with **-weight 1 -uniform a**. A row or column configured with **-weight 2 -uniform b** will be exactly twice as large as one that is configured with **-weight 1 -uniform b**. 


 More technically, each row or column in the group will have a size equal to *k\*weight* for some constant *k*. The constant *k* is chosen so that no row or column becomes smaller than its minimum size. For example, if all rows or columns in a group have the same weight, then each row or column will have the same size as the largest row or column in the group. 


 For masters whose size is larger than the requested layout, the additional space is apportioned according to the row and column weights. If all of the weights are zero, the layout is placed within its master according to the *anchor* value. For masters whose size is smaller than the requested layout, space is taken away from columns and rows according to their weights. However, once a column or row shrinks to its minsize, its weight is taken to be zero. If more space needs to be removed from a layout than would be permitted, as when all the rows or columns are at their minimum sizes, the layout is placed and clipped according to the *anchor* value. 


Geometry propagation
--------------------

 The grid geometry manager normally computes how large a master must be to just exactly meet the needs of its slaves, and it sets the requested width and height of the master to these dimensions. This causes geometry information to propagate up through a window hierarchy to a top-level window so that the entire sub-tree sizes itself to fit the needs of the leaf windows. However, the **grid propagate** command may be used to turn off propagation for one or more masters. If propagation is disabled then grid will not set the requested width and height of the master window. This may be useful if, for example, you wish for a master window to have a fixed size that you specify. Restrictions on master windows
------------------------------

 The master for each slave must either be the slave's parent (the default) or a descendant of the slave's parent. This restriction is necessary to guarantee that the slave can be placed over any part of its master that is visible without danger of the slave being clipped by its parent. In addition, all slaves in one call to **grid** must have the same master. Stacking order
--------------

 If the master for a slave is not its parent then you must make sure that the slave is higher in the stacking order than the master. Otherwise the master will obscure the slave and it will appear as if the slave has not been managed correctly. The easiest way to make sure the slave is higher than the master is to create the master window first: the most recently created window will be highest in the stacking order. Credits
-------

 The **grid** command is based on ideas taken from the *GridBag* geometry manager written by Doug. Stein, and the **blt\_table** geometry manager, written by George Howlett. Examples
--------

 A toplevel window containing a text widget and two scrollbars: 

```
# Make the widgets
toplevel .t
text .t.txt -wrap none -xscroll {.t.h set} -yscroll {.t.v set}
scrollbar .t.v -orient vertical   -command {.t.txt yview}
scrollbar .t.h -orient horizontal -command {.t.txt xview}

# Lay them out
**grid** .t.txt .t.v -sticky nsew
**grid** .t.h        -sticky nsew

# Tell the text widget to take all the extra room
**grid rowconfigure**    .t .t.txt -weight 1
**grid columnconfigure** .t .t.txt -weight 1
```
  Three widgets of equal width, despite their different “natural” widths: 



```
button .b -text "Foo"
entry .e -variable foo
label .l -text "This is a fairly long piece of text"

**grid** .b .e .l -sticky ew
**grid columnconfigure** . "all" -uniform allTheSame
```
 See also
--------

 **[pack](pack.htm)**, **[place](place.htm)** Copyright © 1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/grid.htm>

label
=====

  
[NAME](label.htm#M2) label — Create and manipulate 'label' non-interactive text or image widgets 
[SYNOPSIS](label.htm#M3) 
[STANDARD OPTIONS](label.htm#M4)  
[-activebackground, activeBackground, Foreground](options.htm#M-activebackground) 
[-activeforeground, activeForeground, Background](options.htm#M-activeforeground) 
[-anchor, anchor, Anchor](options.htm#M-anchor) 
[-background or -bg, background, Background](options.htm#M-background) 
[-bitmap, bitmap, Bitmap](options.htm#M-bitmap) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-compound, compound, Compound](options.htm#M-compound) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-image, image, Image](options.htm#M-image) 
[-justify, justify, Justify](options.htm#M-justify) 
[-padx, padX, Pad](options.htm#M-padx) 
[-pady, padY, Pad](options.htm#M-pady) 
[-relief, relief, Relief](options.htm#M-relief) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-text, text, Text](options.htm#M-text) 
[-textvariable, textVariable, Variable](options.htm#M-textvariable) 
[-underline, underline, Underline](options.htm#M-underline) 
[-wraplength, wrapLength, WrapLength](options.htm#M-wraplength) 























 
[WIDGET-SPECIFIC OPTIONS](label.htm#M5)  
[-height, height, Height](label.htm#M6) 
[-state, state, State](label.htm#M7) 
[-width, width, Width](label.htm#M8) 


 
[DESCRIPTION](label.htm#M9) 
[WIDGET COMMAND](label.htm#M10)  
[*pathName* **cget** *option*](label.htm#M11) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](label.htm#M12) 

 
[BINDINGS](label.htm#M13) 
[EXAMPLE](label.htm#M14) 
[SEE ALSO](label.htm#M15) 
[KEYWORDS](label.htm#M16) 









 Name
----

 label — Create and manipulate 'label' non-interactive text or image widgets Synopsis
--------

 **label** *pathName* ?*options*?  
 Standard options
----------------

  
**[-activebackground, activeBackground, Foreground](options.htm#M-activebackground)** 
**[-activeforeground, activeForeground, Background](options.htm#M-activeforeground)** 
**[-anchor, anchor, Anchor](options.htm#M-anchor)** 
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-bitmap, bitmap, Bitmap](options.htm#M-bitmap)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-compound, compound, Compound](options.htm#M-compound)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-image, image, Image](options.htm#M-image)** 
**[-justify, justify, Justify](options.htm#M-justify)** 
**[-padx, padX, Pad](options.htm#M-padx)** 
**[-pady, padY, Pad](options.htm#M-pady)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-text, text, Text](options.htm#M-text)** 
**[-textvariable, textVariable, Variable](options.htm#M-textvariable)** 
**[-underline, underline, Underline](options.htm#M-underline)** 
**[-wraplength, wrapLength, WrapLength](options.htm#M-wraplength)** 























 Widget-specific options
-----------------------

  Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies a desired height for the label. If an image or bitmap is being displayed in the label then the value is in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**); for text it is in lines of text. If this option is not specified, the label's desired height is computed from the size of the image or bitmap or text being displayed in it. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Specifies one of three states for the label: **normal**, **active**, or **disabled**. In normal state the button is displayed using the **-foreground** and **-background** options. In active state the label is displayed using the **-activeforeground** and **-activebackground** options. In the disabled state the **-disabledforeground** and **-background** options determine how the button is displayed. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies a desired width for the label. If an image or bitmap is being displayed in the label then the value is in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**); for text it is in characters. If this option is not specified, the label's desired width is computed from the size of the image or bitmap or text being displayed in it. 
 Description
-----------

 The **label** command creates a new window (given by the *pathName* argument) and makes it into a label widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the label such as its colors, font, text, and initial relief. The **label** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  A label is a widget that displays a textual string, bitmap or image. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the **-wraplength** option) and one of the characters may optionally be underlined using the **-underline** option. The label can be manipulated in a few simple ways, such as changing its relief or text, using the commands described below. 


Widget command
--------------

 The **label** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for label widgets: 
 
*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **label** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **label** command. 

 Bindings
--------

 When a new label is created, it has no default event bindings: labels are not intended to be interactive. Example
-------

 
```
# Make the widgets
**label** .t -text "This widget is at the top"    -bg red
**label** .b -text "This widget is at the bottom" -bg green
**label** .l -text "Left\nHand\nSide"
**label** .r -text "Right\nHand\nSide"
text .mid
	.mid insert end "This layout is like Java's BorderLayout"
# Lay them out
pack .t   -side top    -fill x
pack .b   -side bottom -fill x
pack .l   -side left   -fill y
pack .r   -side right  -fill y
pack .mid -expand 1    -fill both
```
 See also
--------

 **[labelframe](labelframe.htm)**, **[button](button.htm)**, **[ttk::label](ttk_label.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/label.htm>

busy
====

  
[NAME](busy.htm#M2) busy — confine pointer and keyboard events to a window sub-tree 
[SYNOPSIS](busy.htm#M3) 
[DESCRIPTION](busy.htm#M4) 
[INTRODUCTION](busy.htm#M5) 
[EXAMPLE](busy.htm#M6) 
[OPERATIONS](busy.htm#M7)  
[**tk busy** *window* ?*option value*?...](busy.htm#M8) 
[**tk busy hold** *window* ?*option value*?...](busy.htm#M9)  
[**-cursor** *cursorName*](busy.htm#M10) 
 
[**tk busy cget** *window* *option*](busy.htm#M11) 
[**tk busy configure** *window* ?*option value*?...](busy.htm#M12) 
[**tk busy forget** *window* ?*window*?...](busy.htm#M13) 
[**tk busy current** ?*pattern*?](busy.htm#M14) 
[**tk busy status** *window*](busy.htm#M15) 






 
[EVENT HANDLING](busy.htm#M16) 
[BINDINGS](busy.htm#M17) 
[ENTER/LEAVE EVENTS](busy.htm#M18) 
[KEYBOARD EVENTS](busy.htm#M19) 
[PORTABILITY](busy.htm#M20) 
[SEE ALSO](busy.htm#M21) 
[KEYWORDS](busy.htm#M22) 












 Name
----

 busy — confine pointer and keyboard events to a window sub-tree Synopsis
--------

 **tk busy** *window* ?*options*?  
 **tk busy hold** *window* ?*options*?  
 **tk busy configure** *window* ?*option value*?...  
 **tk busy forget** *window* ?*window* ?...  
 **tk busy current** ?*pattern*?  
 **tk busy status** *window*  
 Description
-----------

 The **tk busy** command provides a simple means to block keyboard, button, and pointer events from Tk widgets, while overriding the widget's cursor with a configurable busy cursor. Introduction
------------

 There are many times in applications where you want to temporarily restrict what actions the user can take. For example, an application could have a “Run” button that when pressed causes some processing to occur. However, while the application is busy processing, you probably don't want the user to be able to click the “Run” button again. You may also want restrict the user from other tasks such as clicking a “Print” button.  The **tk busy** command lets you make Tk widgets busy. This means that user interactions such as button clicks, moving the mouse, typing at the keyboard, etc. are ignored by the widget. You can set a special cursor (like a watch) that overrides the widget's normal cursor, providing feedback that the application (widget) is temporarily busy. 


 When a widget is made busy, the widget and all of its descendants will ignore events. It's easy to make an entire panel of widgets busy. You can simply make the toplevel widget (such as “.”) busy. This is easier and far much more efficient than recursively traversing the widget hierarchy, disabling each widget and re-configuring its cursor. 


 Often, the **tk busy** command can be used instead of Tk's **[grab](grab.htm)** command. Unlike **[grab](grab.htm)** which restricts all user interactions to one widget, with the **tk busy** command you can have more than one widget active (for example, a “Cancel” dialog and a “Help” button). 


### Example

 You can make several widgets busy by simply making its ancestor widget busy using the **hold** operation. 

```
frame .top
button .top.button; canvas .top.canvas
pack .top.button .top.canvas
pack .top
# . . .
**tk busy** hold .top
update
```
  All the widgets within **.top** (including **.top**) are now busy. Using **[update](../tclcmd/update.htm)** insures that **tk busy** command will take effect before any other user events can occur. 


 When the application is no longer busy processing, you can allow user interactions again and free any resources it allocated by the **forget** operation. 



```
**tk busy** forget .top
```
  The busy window has a configurable cursor. You can change the busy cursor using the **configure** operation. 



```
**tk busy** configure .top -cursor "watch"
```
  Destroying the widget will also clean up any resources allocated by the **tk busy** command. 


Operations
----------

 The following operations are available for the **tk busy** command: 
 
**tk busy** *window* ?*option value*?...
 Shortcut for **tk busy hold** command. 


**tk busy hold** *window* ?*option value*?...
 Makes the specified *window* (and its descendants in the Tk window hierarchy) appear busy. *Window* must be a valid path name of a Tk widget. A transparent window is put in front of the specified window. This transparent window is mapped the next time idle tasks are processed, and the specified window and its descendants will be blocked from user interactions. Normally **[update](../tclcmd/update.htm)** should be called immediately afterward to insure that the hold operation is in effect before the application starts its processing. The following configuration options are valid: 
 
**-cursor** *cursorName*

 Specifies the cursor to be displayed when the widget is made busy. *CursorName* can be in any form accepted by **[Tk\_GetCursor](https://www.tcl.tk/man/tcl/TkLib/GetCursor.htm)**. The default cursor is **wait** on Windows and **watch** on other platforms. 




**tk busy cget** *window* *option*

 Queries the **tk busy** command configuration options for *window*. *Window* must be the path name of a widget previously made busy by the **hold** operation. The command returns the present value of the specified *option*. *Option* may have any of the values accepted by the **hold** operation. 


**tk busy configure** *window* ?*option value*?...
 Queries or modifies the **tk busy** command configuration options for *window*. *Window* must be the path name of a widget previously made busy by the **hold** operation. If no options are specified, a list describing all of the available options for *window* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list) is returned. If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns the empty string. *Option* may have any of the values accepted by the **hold** operation.  Please note that the option database is referenced through *window*. For example, if the widget **.frame** is to be made busy, the busy cursor can be specified for it by either **[option](option.htm)** command: 



```
option add *frame.busyCursor gumby
option add *Frame.BusyCursor gumby
```



**tk busy forget** *window* ?*window*?...
 Releases resources allocated by the **tk busy** command for *window*, including the transparent window. User events will again be received by *window*. Resources are also released when *window* is destroyed. *Window* must be the name of a widget specified in the **hold** operation, otherwise an error is reported. 


**tk busy current** ?*pattern*?
 Returns the pathnames of all widgets that are currently busy. If a *pattern* is given, only the path names of busy widgets matching *pattern* are returned. 


**tk busy status** *window*

 Returns the status of a widget *window*. If *window* presently can not receive user interactions, **1** is returned, otherwise **0**. 

 Event handling
--------------

 ### Bindings

 The event blocking feature is implemented by creating and mapping a transparent window that completely covers the widget. When the busy window is mapped, it invisibly shields the widget and its hierarchy from all events that may be sent. Like Tk widgets, busy windows have widget names in the Tk window hierarchy. This means that you can use the **[bind](bind.htm)** command, to handle events in the busy window. 

```
**tk busy** hold .frame.canvas
bind .frame.canvas_Busy <Enter> { ... }
```
  Normally the busy window is a sibling of the widget. The name of the busy window is “*widget***\_Busy**” where *widget* is the name of the widget to be made busy. In the previous example, the pathname of the busy window is “**.frame.canvas\_Busy**”. The exception is when the widget is a toplevel widget (such as “.”) where the busy window can't be made a sibling. The busy window is then a child of the widget named “*widget***.\_Busy**” where *widget* is the name of the toplevel widget. In the following example, the pathname of the busy window is “**.\_Busy**”. 



```
**tk busy** hold .
bind ._Busy <Enter> { ... }
```
 ### Enter/leave events

 Mapping and unmapping busy windows generates Enter/Leave events for all widgets they cover. Please note this if you are tracking Enter/Leave events in widgets. ### Keyboard events

 When a widget is made busy, the widget is prevented from gaining the keyboard focus by the busy window. But if the widget already had focus, it still may received keyboard events. To prevent this, you must move focus to another window. 

```
**tk busy** hold .frame
label .dummy
focus .dummy
update
```
  The above example moves the focus from .frame immediately after invoking the **hold** so that no keyboard events will be sent to **.frame** or any of its descendants. 


Portability
-----------

 Note that the **tk busy** command does not currently have any effect on OSX when Tk is built using Aqua support. See also
--------

 **[grab](grab.htm)** Copyright © 1993-1998 Lucent Technologies, Inc.  
 Copyright © 2008 Jos Decoster 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/busy.htm>

labelframe
==========

  
[NAME](labelframe.htm#M2) labelframe — Create and manipulate 'labelframe' labelled container widgets 
[SYNOPSIS](labelframe.htm#M3) 
[STANDARD OPTIONS](labelframe.htm#M4)  
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-padx, padX, Pad](options.htm#M-padx) 
[-pady, padY, Pad](options.htm#M-pady) 
[-relief, relief, Relief](options.htm#M-relief) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-text, text, Text](options.htm#M-text) 











 
[WIDGET-SPECIFIC OPTIONS](labelframe.htm#M5)  
[-background, background, Background](labelframe.htm#M6) 
[-class, class, Class](labelframe.htm#M7) 
[-colormap, colormap, Colormap](labelframe.htm#M8) 
[-height, height, Height](labelframe.htm#M9) 
[-labelanchor, labelAnchor, LabelAnchor](labelframe.htm#M10) 
[-labelwidget, labelWidget, LabelWidget](labelframe.htm#M11) 
[-visual, visual, Visual](labelframe.htm#M12) 
[-width, width, Width](labelframe.htm#M13) 







 
[DESCRIPTION](labelframe.htm#M14) 
[WIDGET COMMAND](labelframe.htm#M15)  
[*pathName* **cget** *option*](labelframe.htm#M16) 
[*pathName* **configure** ?*option*? *?value option value ...*?](labelframe.htm#M17) 

 
[BINDINGS](labelframe.htm#M18) 
[EXAMPLE](labelframe.htm#M19) 
[SEE ALSO](labelframe.htm#M20) 
[KEYWORDS](labelframe.htm#M21) 









 Name
----

 labelframe — Create and manipulate 'labelframe' labelled container widgets Synopsis
--------

 **labelframe** *pathName* ?*options*?  
 Standard options
----------------

  
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-padx, padX, Pad](options.htm#M-padx)** 
**[-pady, padY, Pad](options.htm#M-pady)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-text, text, Text](options.htm#M-text)** 











 Widget-specific options
-----------------------

  Command-Line Name: **-background** Database Name: **background** Database Class: **Background** 


This option is the same as the standard **-background** option except that its value may also be specified as an empty string. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border. 

Command-Line Name: **-class** Database Name: **class** Database Class: **Class** 


Specifies a class for the window. This class will be used when querying the option database for the window's other options, and it will also be used later for other purposes such as bindings. The **-class** option may not be changed with the **configure** widget command. 

Command-Line Name: **-colormap** Database Name: **colormap** Database Class: **Colormap** 


Specifies a colormap to use for the window. The value may be either **new**, in which case a new colormap is created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as *pathName*), in which case the new window will use the colormap from the specified window. If the **-colormap** option is not specified, the new window uses the same colormap as its parent. This option may not be changed with the **configure** widget command. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies the desired height for the window in any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. If this option is less than or equal to zero then the window will not request any size at all. 

Command-Line Name: **-labelanchor** Database Name: **labelAnchor** Database Class: **LabelAnchor** 


Specifies where to place the label. A label is only displayed if the **-text** option is not the empty string. Valid values for this option are (listing them clockwise) **nw**, **n**, **ne**, **en**, **e**, **es**, **se**, **s**,**sw**, **ws**, **w** and **wn**. The default value is **nw**. 

Command-Line Name: **-labelwidget** Database Name: **labelWidget** Database Class: **LabelWidget** 


Specifies a widget to use as label. This overrides any **-text** option. The widget must exist before being used as **-labelwidget** and if it is not a descendant of this window, it will be raised above it in the stacking order. 

Command-Line Name: **-visual** Database Name: **visual** Database Class: **Visual** 


Specifies visual information for the new window in any of the forms accepted by **[Tk\_GetVisual](https://www.tcl.tk/man/tcl/TkLib/GetVisual.htm)**. If this option is not specified, the new window will use the same visual as its parent. The **-visual** option may not be modified with the **configure** widget command. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies the desired width for the window in any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. If this option is less than or equal to zero then the window will not request any size at all. 
 Description
-----------

 The **labelframe** command creates a new window (given by the *pathName* argument) and makes it into a labelframe widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the labelframe such as its background color and relief. The **labelframe** command returns the path name of the new window.  A labelframe is a simple widget. Its primary purpose is to act as a spacer or container for complex window layouts. It has the features of a **[frame](frame.htm)** plus the ability to display a label. 


Widget command
--------------

 The **labelframe** command creates a new Tcl command whose name is the same as the path name of the labelframe's window. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *PathName* is the name of the command, which is the same as the labelframe widget's path name. *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for frame widgets: 
 
*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **labelframe** command. 


*pathName* **configure** ?*option*? *?value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **labelframe** command. 

 Bindings
--------

 When a new labelframe is created, it has no default event bindings: labelframes are not intended to be interactive. Example
-------

 This shows how to build part of a GUI for a hamburger vendor. The **labelframe** widgets are used to organize the available choices by the kinds of things that the choices are being made over. 

```
grid [**labelframe** .burger -text "Burger"] \
     [**labelframe** .bun    -text "Bun"] -sticky news
grid [**labelframe** .cheese -text "Cheese Option"] \
     [**labelframe** .pickle -text "Pickle Option"] -sticky news
foreach {type name val} {
    burger Beef    beef
    burger Lamb    lamb
    burger Vegetarian beans

    bun    Plain   white
    bun    Sesame  seeds
    bun    Wholemeal brown

    cheese None    none
    cheese Cheddar cheddar
    cheese Edam    edam
    cheese Brie    brie
    cheese Gruy\u00e8re gruyere
    cheese "Monterey Jack" jack

    pickle None    none
    pickle Gherkins gherkins
    pickle Onions  onion
    pickle Chili   chili
} {
    set w [radiobutton .$type.$val -text $name -anchor w \
            -variable $type -value $val]
    pack $w -side top -fill x
}
set burger beef
set bun    white
set cheese none
set pickle none
```
 See also
--------

 **[frame](frame.htm)**, **[label](label.htm)**, **[ttk::labelframe](ttk_labelframe.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/labelframe.htm>

namespace
=========

  
[NAME](namespace.htm#M2) namespace — create and manipulate contexts for commands and variables 
[SYNOPSIS](namespace.htm#M3) 
[DESCRIPTION](namespace.htm#M4)  
[**namespace children** ?*namespace*? ?*pattern*?](namespace.htm#M5) 
[**namespace code** *script*](namespace.htm#M6) 
[**namespace current**](namespace.htm#M7) 
[**namespace delete** ?*namespace namespace ...*?](namespace.htm#M8) 
[**namespace ensemble** *subcommand* ?*arg ...*?](namespace.htm#M9) 
[**namespace eval** *namespace arg* ?*arg ...*?](namespace.htm#M10) 
[**namespace exists** *namespace*](namespace.htm#M11) 
[**namespace export** ?**-clear**? ?*pattern pattern ...*?](namespace.htm#M12) 
[**namespace forget** ?*pattern pattern ...*?](namespace.htm#M13) 
[**namespace import** ?**-force**? ?*pattern* *pattern ...*?](namespace.htm#M14) 
[**namespace inscope** *namespace* *script* ?*arg ...*?](namespace.htm#M15) 
[**namespace origin** *command*](namespace.htm#M16) 
[**namespace parent** ?*namespace*?](namespace.htm#M17) 
[**namespace path** ?*namespaceList*?](namespace.htm#M18) 
[**namespace qualifiers** *string*](namespace.htm#M19) 
[**namespace tail** *string*](namespace.htm#M20) 
[**namespace upvar** *namespace* ?*otherVar myVar* ...?](namespace.htm#M21) 
[**namespace unknown** ?*script*?](namespace.htm#M22) 
[**namespace which** ?**-command**? ?**-variable**? *name*](namespace.htm#M23) 


















 
[WHAT IS A NAMESPACE?](namespace.htm#M24) 
[QUALIFIED NAMES](namespace.htm#M25) 
[NAME RESOLUTION](namespace.htm#M26) 
[IMPORTING COMMANDS](namespace.htm#M27) 
[EXPORTING COMMANDS](namespace.htm#M28) 
[SCOPED SCRIPTS](namespace.htm#M29) 
[ENSEMBLES](namespace.htm#M30)  
[**namespace ensemble create** ?*option value ...*?](namespace.htm#M31) 
[**namespace ensemble configure** *command* ?*option*? ?*value ...*?](namespace.htm#M32) 
[**namespace ensemble exists** *command*](namespace.htm#M33) 


 
[ENSEMBLE OPTIONS](namespace.htm#M34)  
[**-map**](namespace.htm#M35) 
[**-parameters**](namespace.htm#M36) 
[**-prefixes**](namespace.htm#M37) 
[**-subcommands**](namespace.htm#M38) 
[**-unknown**](namespace.htm#M39) 




  
[**-command**](namespace.htm#M40) 
  
[**-namespace**](namespace.htm#M41) 
 
[UNKNOWN HANDLER BEHAVIOUR](namespace.htm#M42) 
[EXAMPLES](namespace.htm#M43) 
[SEE ALSO](namespace.htm#M44) 
[KEYWORDS](namespace.htm#M45) 














 Name
----

 namespace — create and manipulate contexts for commands and variables Synopsis
--------

 **namespace** ?*subcommand*? ?*arg ...*?  
 Description
-----------

 The **namespace** command lets you create, access, and destroy separate contexts for commands and variables. See the section **[WHAT IS A NAMESPACE?](#M24)** below for a brief overview of namespaces. The legal values of *subcommand* are listed below. Note that you can abbreviate the *subcommand*s. 
 
**namespace children** ?*namespace*? ?*pattern*?
 Returns a list of all child namespaces that belong to the namespace *namespace*. If *namespace* is not specified, then the children are returned for the current namespace. This command returns fully-qualified names, which start with a double colon (**::**). If the optional *pattern* is given, then this command returns only the names that match the glob-style pattern. The actual pattern used is determined as follows: a pattern that starts with double colon (**::**) is used directly, otherwise the namespace *namespace* (or the fully-qualified name of the current namespace) is prepended onto the pattern. 


**namespace code** *script*

 Captures the current namespace context for later execution of the script *script*. It returns a new script in which *script* has been wrapped in a **namespace inscope** command. The new script has two important properties. First, it can be evaluated in any namespace and will cause *script* to be evaluated in the current namespace (the one where the **namespace code** command was invoked). Second, additional arguments can be appended to the resulting script and they will be passed to *script* as additional arguments. For example, suppose the command **set script [namespace code {foo bar}]** is invoked in namespace **::a::b**. Then **eval $script [list x y]** can be executed in any namespace (assuming the value of **script** has been passed in properly) and will have the same effect as the command **::namespace eval ::a::b {foo bar x y}**. This command is needed because extensions like Tk normally execute callback scripts in the global namespace. A scoped command captures a command together with its namespace context in a way that allows it to be executed properly later. See the section **[SCOPED SCRIPTS](#M29)** for some examples of how this is used to create callback scripts. 

**namespace current**
 Returns the fully-qualified name for the current namespace. The actual name of the global namespace is “” (i.e., an empty string), but this command returns **::** for the global namespace as a convenience to programmers. 


**namespace delete** ?*namespace namespace ...*?
 Each namespace *namespace* is deleted and all variables, procedures, and child namespaces contained in the namespace are deleted. If a procedure is currently executing inside the namespace, the namespace will be kept alive until the procedure returns; however, the namespace is marked to prevent other code from looking it up by name. If a namespace does not exist, this command returns an error. If no namespace names are given, this command does nothing. 


**namespace ensemble** *subcommand* ?*arg ...*?
 Creates and manipulates a command that is formed out of an ensemble of subcommands. See the section **[ENSEMBLES](#M30)** below for further details. 


**namespace eval** *namespace arg* ?*arg ...*?
 Activates a namespace called *namespace* and evaluates some code in that context. If the namespace does not already exist, it is created. If more than one *arg* argument is specified, the arguments are concatenated together with a space between each one in the same fashion as the **[eval](eval.htm)** command, and the result is evaluated.  If *namespace* has leading namespace qualifiers and any leading namespaces do not exist, they are automatically created. 




**namespace exists** *namespace*

 Returns **1** if *namespace* is a valid namespace in the current context, returns **0** otherwise. 


**namespace export** ?**-clear**? ?*pattern pattern ...*?
 Specifies which commands are exported from a namespace. The exported commands are those that can be later imported into another namespace using a **namespace import** command. Both commands defined in a namespace and commands the namespace has previously imported can be exported by a namespace. The commands do not have to be defined at the time the **namespace export** command is executed. Each *pattern* may contain glob-style special characters, but it may not include any namespace qualifiers. That is, the pattern can only specify commands in the current (exporting) namespace. Each *pattern* is appended onto the namespace's list of export patterns. If the **-clear** flag is given, the namespace's export pattern list is reset to empty before any *pattern* arguments are appended. If no *pattern*s are given and the **-clear** flag is not given, this command returns the namespace's current export list. 


**namespace forget** ?*pattern pattern ...*?
 Removes previously imported commands from a namespace. Each *pattern* is a simple or qualified name such as **x**, **foo::x** or **a::b::p\***. Qualified names contain double colons (**::**) and qualify a name with the name of one or more namespaces. Each “qualified pattern” is qualified with the name of an exporting namespace and may have glob-style special characters in the command name at the end of the qualified name. Glob characters may not appear in a namespace name. For each “simple pattern” this command deletes the matching commands of the current namespace that were imported from a different namespace. For “qualified patterns”, this command first finds the matching exported commands. It then checks whether any of those commands were previously imported by the current namespace. If so, this command deletes the corresponding imported commands. In effect, this un-does the action of a **namespace import** command. 


**namespace import** ?**-force**? ?*pattern* *pattern ...*?
 Imports commands into a namespace, or queries the set of imported commands in a namespace. When no arguments are present, **namespace import** returns the list of commands in the current namespace that have been imported from other namespaces. The commands in the returned list are in the format of simple names, with no namespace qualifiers at all. This format is suitable for composition with **namespace forget** (see **[EXAMPLES](#M43)** below).  When *pattern* arguments are present, each *pattern* is a qualified name like **foo::x** or **a::p\***. That is, it includes the name of an exporting namespace and may have glob-style special characters in the command name at the end of the qualified name. Glob characters may not appear in a namespace name. When the namespace name is not fully qualified (i.e., does not start with a namespace separator) it is resolved as a namespace name in the way described in the **[NAME RESOLUTION](#M26)** section; it is an error if no namespace with that name can be found. 


All the commands that match a *pattern* string and which are currently exported from their namespace are added to the current namespace. This is done by creating a new command in the current namespace that points to the exported command in its original namespace; when the new imported command is called, it invokes the exported command. This command normally returns an error if an imported command conflicts with an existing command. However, if the **-force** option is given, imported commands will silently replace existing commands. The **namespace import** command has snapshot semantics: that is, only requested commands that are currently defined in the exporting namespace are imported. In other words, you can import only the commands that are in a namespace at the time when the **namespace import** command is executed. If another command is defined and exported in this namespace later on, it will not be imported. 




**namespace inscope** *namespace* *script* ?*arg ...*?
 Executes a script in the context of the specified *namespace*. This command is not expected to be used directly by programmers; calls to it are generated implicitly when applications use **namespace code** commands to create callback scripts that the applications then register with, e.g., Tk widgets. The **namespace inscope** command is much like the **namespace eval** command except that the *namespace* must already exist, and **namespace inscope** appends additional *arg*s as proper list elements. 

```
**namespace inscope ::foo $script $x $y $z**
```
  is equivalent to 



```
**namespace eval ::foo [concat $script [list $x $y $z]]**
```
 thus additional arguments will not undergo a second round of substitution, as is the case with **namespace eval**. 




**namespace origin** *command*

 Returns the fully-qualified name of the original command to which the imported command *command* refers. When a command is imported into a namespace, a new command is created in that namespace that points to the actual command in the exporting namespace. If a command is imported into a sequence of namespaces *a, b,...,n* where each successive namespace just imports the command from the previous namespace, this command returns the fully-qualified name of the original command in the first namespace, *a*. If *command* does not refer to an imported command, the command's own fully-qualified name is returned. 


**namespace parent** ?*namespace*?
 Returns the fully-qualified name of the parent namespace for namespace *namespace*. If *namespace* is not specified, the fully-qualified name of the current namespace's parent is returned. 


**namespace path** ?*namespaceList*?
 Returns the command resolution path of the current namespace. If *namespaceList* is specified as a list of named namespaces, the current namespace's command resolution path is set to those namespaces and returns the empty list. The default command resolution path is always empty. See the section **[NAME RESOLUTION](#M26)** below for an explanation of the rules regarding name resolution. 


**namespace qualifiers** *string*

 Returns any leading namespace qualifiers for *string*. Qualifiers are namespace names separated by double colons (**::**). For the *string* **::foo::bar::x**, this command returns **::foo::bar**, and for **::** it returns an empty string. This command is the complement of the **namespace tail** command. Note that it does not check whether the namespace names are, in fact, the names of currently defined namespaces. 


**namespace tail** *string*

 Returns the simple name at the end of a qualified string. Qualifiers are namespace names separated by double colons (**::**). For the *string* **::foo::bar::x**, this command returns **x**, and for **::** it returns an empty string. This command is the complement of the **namespace qualifiers** command. It does not check whether the namespace names are, in fact, the names of currently defined namespaces. 


**namespace upvar** *namespace* ?*otherVar myVar* ...?
 This command arranges for zero or more local variables in the current procedure to refer to variables in *namespace*. The namespace name is resolved as described in section **[NAME RESOLUTION](#M26)**. The command **namespace upvar $ns a b** has the same behaviour as **upvar 0 ${ns}::a b**, with the sole exception of the resolution rules used for qualified namespace or variable names. **namespace upvar** returns an empty string. 


**namespace unknown** ?*script*?
 Sets or returns the unknown command handler for the current namespace. The handler is invoked when a command called from within the namespace cannot be found in the current namespace, the namespace's path nor in the global namespace. The *script* argument, if given, should be a well formed list representing a command name and optional arguments. When the handler is invoked, the full invocation line will be appended to the script and the result evaluated in the context of the namespace. The default handler for all namespaces is **::unknown**. If no argument is given, it returns the handler for the current namespace. 


**namespace which** ?**-command**? ?**-variable**? *name*

 Looks up *name* as either a command or variable and returns its fully-qualified name. For example, if *name* does not exist in the current namespace but does exist in the global namespace, this command returns a fully-qualified name in the global namespace. If the command or variable does not exist, this command returns an empty string. If the variable has been created but not defined, such as with the **[variable](variable.htm)** command or through a **[trace](trace.htm)** on the variable, this command will return the fully-qualified name of the variable. If no flag is given, *name* is treated as a command name. See the section **[NAME RESOLUTION](#M26)** below for an explanation of the rules regarding name resolution. 

 What is a namespace?
--------------------

 A namespace is a collection of commands and variables. It encapsulates the commands and variables to ensure that they will not interfere with the commands and variables of other namespaces. Tcl has always had one such collection, which we refer to as the *global namespace*. The global namespace holds all global variables and commands. The **namespace eval** command lets you create new namespaces. For example, 

```
**namespace eval** Counter {
    **namespace export** bump
    variable num 0

    proc bump {} {
        variable num
        incr num
    }
}
```
  creates a new namespace containing the variable **num** and the procedure **bump**. The commands and variables in this namespace are separate from other commands and variables in the same program. If there is a command named **bump** in the global namespace, for example, it will be different from the command **bump** in the **Counter** namespace. 


 Namespace variables resemble global variables in Tcl. They exist outside of the procedures in a namespace but can be accessed in a procedure via the **[variable](variable.htm)** command, as shown in the example above. 


 Namespaces are dynamic. You can add and delete commands and variables at any time, so you can build up the contents of a namespace over time using a series of **namespace eval** commands. For example, the following series of commands has the same effect as the namespace definition shown above: 



```
**namespace eval** Counter {
    variable num 0
    proc bump {} {
        variable num
        return [incr num]
    }
}
**namespace eval** Counter {
    proc test {args} {
        return $args
    }
}
**namespace eval** Counter {
     rename test ""
}
```
  Note that the **test** procedure is added to the **Counter** namespace, and later removed via the **[rename](rename.htm)** command. 


 Namespaces can have other namespaces within them, so they nest hierarchically. A nested namespace is encapsulated inside its parent namespace and can not interfere with other namespaces. 


Qualified names
---------------

 Each namespace has a textual name such as **[history](history.htm)** or **::safe::interp**. Since namespaces may nest, qualified names are used to refer to commands, variables, and child namespaces contained inside namespaces. Qualified names are similar to the hierarchical path names for Unix files or Tk widgets, except that **::** is used as the separator instead of **/** or **.**. The topmost or global namespace has the name “” (i.e., an empty string), although **::** is a synonym. As an example, the name **::safe::interp::create** refers to the command **create** in the namespace **[interp](interp.htm)** that is a child of namespace **::safe**, which in turn is a child of the global namespace, **::**.  If you want to access commands and variables from another namespace, you must use some extra syntax. Names must be qualified by the namespace that contains them. From the global namespace, we might access the **Counter** procedures like this: 



```
Counter::bump 5
Counter::Reset
```
  We could access the current count like this: 



```
puts "count = $Counter::num"
```
  When one namespace contains another, you may need more than one qualifier to reach its elements. If we had a namespace **Foo** that contained the namespace **Counter**, you could invoke its **bump** procedure from the global namespace like this: 



```
Foo::Counter::bump 3
```
  You can also use qualified names when you create and rename commands. For example, you could add a procedure to the **Foo** namespace like this: 



```
proc Foo::Test {args} {return $args}
```
  And you could move the same procedure to another namespace like this: 



```
rename Foo::Test Bar::Test
```
  There are a few remaining points about qualified names that we should cover. Namespaces have nonempty names except for the global namespace. **::** is disallowed in simple command, variable, and namespace names except as a namespace separator. Extra colons in any separator part of a qualified name are ignored; i.e. two or more colons are treated as a namespace separator. A trailing **::** in a qualified variable or command name refers to the variable or command named {}. However, a trailing **::** in a qualified namespace name is ignored. 


Name resolution
---------------

 In general, all Tcl commands that take variable and command names support qualified names. This means you can give qualified names to such commands as **[set](set.htm)**, **[proc](proc.htm)**, **[rename](rename.htm)**, and **[interp alias](interp.htm)**. If you provide a fully-qualified name that starts with a **::**, there is no question about what command, variable, or namespace you mean. However, if the name does not start with a **::** (i.e., is *relative*), Tcl follows basic rules for looking it up: 
* **Variable names** are always resolved by looking first in the current namespace, and then in the global namespace.
* **Command names** are always resolved by looking in the current namespace first. If not found there, they are searched for in every namespace on the current namespace's command path (which is empty by default). If not found there, command names are looked up in the global namespace (or, failing that, are processed by the appropriate **namespace unknown** handler.)
* **Namespace names** are always resolved by looking in only the current namespace.

  In the following example, 



```
set traceLevel 0
**namespace eval** Debug {
    printTrace $traceLevel
}
```
  Tcl looks for **traceLevel** in the namespace **Debug** and then in the global namespace. It looks up the command **printTrace** in the same way. If a variable or command name is not found in either context, the name is undefined. To make this point absolutely clear, consider the following example: 



```
set traceLevel 0
**namespace eval** Foo {
    variable traceLevel 3

    **namespace eval** Debug {
        printTrace $traceLevel
    }
}
```
  Here Tcl looks for **traceLevel** first in the namespace **Foo::Debug**. Since it is not found there, Tcl then looks for it in the global namespace. The variable **Foo::traceLevel** is completely ignored during the name resolution process. 


 You can use the **namespace which** command to clear up any question about name resolution. For example, the command: 



```
**namespace eval** Foo::Debug {**namespace which** -variable traceLevel}
```
  returns **::traceLevel**. On the other hand, the command, 



```
**namespace eval** Foo {**namespace which** -variable traceLevel}
```
  returns **::Foo::traceLevel**. 


 As mentioned above, namespace names are looked up differently than the names of variables and commands. Namespace names are always resolved in the current namespace. This means, for example, that a **namespace eval** command that creates a new namespace always creates a child of the current namespace unless the new namespace name begins with **::**. 


 Tcl has no access control to limit what variables, commands, or namespaces you can reference. If you provide a qualified name that resolves to an element by the name resolution rule above, you can access the element. 


 You can access a namespace variable from a procedure in the same namespace by using the **[variable](variable.htm)** command. Much like the **[global](global.htm)** command, this creates a local link to the namespace variable. If necessary, it also creates the variable in the current namespace and initializes it. Note that the **[global](global.htm)** command only creates links to variables in the global namespace. It is not necessary to use a **[variable](variable.htm)** command if you always refer to the namespace variable using an appropriate qualified name. 


Importing commands
------------------

 Namespaces are often used to represent libraries. Some library commands are used so frequently that it is a nuisance to type their qualified names. For example, suppose that all of the commands in a package like BLT are contained in a namespace called **Blt**. Then you might access these commands like this: 

```
Blt::graph .g -background red
Blt::table . .g 0,0
```
  If you use the **graph** and **table** commands frequently, you may want to access them without the **Blt::** prefix. You can do this by importing the commands into the current namespace, like this: 



```
**namespace import** Blt::*
```
  This adds all exported commands from the **Blt** namespace into the current namespace context, so you can write code like this: 



```
graph .g -background red
table . .g 0,0
```
  The **namespace import** command only imports commands from a namespace that that namespace exported with a **namespace export** command. 


 Importing *every* command from a namespace is generally a bad idea since you do not know what you will get. It is better to import just the specific commands you need. For example, the command 



```
**namespace import** Blt::graph Blt::table
```
  imports only the **graph** and **table** commands into the current context. 


 If you try to import a command that already exists, you will get an error. This prevents you from importing the same command from two different packages. But from time to time (perhaps when debugging), you may want to get around this restriction. You may want to reissue the **namespace import** command to pick up new commands that have appeared in a namespace. In that case, you can use the **-force** option, and existing commands will be silently overwritten: 



```
**namespace import** -force Blt::graph Blt::table
```
  If for some reason, you want to stop using the imported commands, you can remove them with a **namespace forget** command, like this: 



```
**namespace forget** Blt::*
```
  This searches the current namespace for any commands imported from **Blt**. If it finds any, it removes them. Otherwise, it does nothing. After this, the **Blt** commands must be accessed with the **Blt::** prefix. 


 When you delete a command from the exporting namespace like this: 



```
rename Blt::graph ""
```
  the command is automatically removed from all namespaces that import it. 


Exporting commands
------------------

 You can export commands from a namespace like this: 

```
**namespace eval** Counter {
    **namespace export** bump reset
    variable Num 0
    variable Max 100

    proc bump {{by 1}} {
        variable Num
        incr Num $by
        Check
        return $Num
    }
    proc reset {} {
        variable Num
        set Num 0
    }
    proc Check {} {
        variable Num
        variable Max
        if {$Num > $Max} {
            error "too high!"
        }
    }
}
```
  The procedures **bump** and **reset** are exported, so they are included when you import from the **Counter** namespace, like this: 



```
**namespace import** Counter::*
```
  However, the **Check** procedure is not exported, so it is ignored by the import operation. 


 The **namespace import** command only imports commands that were declared as exported by their namespace. The **namespace export** command specifies what commands may be imported by other namespaces. If a **namespace import** command specifies a command that is not exported, the command is not imported. 


Scoped scripts
--------------

 The **namespace code** command is the means by which a script may be packaged for evaluation in a namespace other than the one in which it was created. It is used most often to create event handlers, Tk bindings, and traces for evaluation in the global context. For instance, the following code indicates how to direct a variable **[trace](trace.htm)** callback into the current namespace: 

```
**namespace eval** a {
    variable b
    proc theTraceCallback { n1 n2 op } {
        upvar 1 $n1 var
        puts "the value of $n1 has changed to $var"
        return
    }
    trace add variable b write [**namespace code** theTraceCallback]
}
set a::b c
```
  When executed, it prints the message: 



```
the value of a::b has changed to c
```
 Ensembles
---------

 The **namespace ensemble** is used to create and manipulate ensemble commands, which are commands formed by grouping subcommands together. The commands typically come from the current namespace when the ensemble was created, though this is configurable. Note that there may be any number of ensembles associated with any namespace (including none, which is true of all namespaces by default), though all the ensembles associated with a namespace are deleted when that namespace is deleted. The link between an ensemble command and its namespace is maintained however the ensemble is renamed.  Three subcommands of the **namespace ensemble** command are defined: 


 
**namespace ensemble create** ?*option value ...*?
 Creates a new ensemble command linked to the current namespace, returning the fully qualified name of the command created. The arguments to **namespace ensemble create** allow the configuration of the command as if with the **namespace ensemble configure** command. If not overridden with the **-command** option, this command creates an ensemble with exactly the same name as the linked namespace. See the section **[ENSEMBLE OPTIONS](#M34)** below for a full list of options supported and their effects. 


**namespace ensemble configure** *command* ?*option*? ?*value ...*?
 Retrieves the value of an option associated with the ensemble command named *command*, or updates some options associated with that ensemble command. See the section **[ENSEMBLE OPTIONS](#M34)** below for a full list of options supported and their effects. 


**namespace ensemble exists** *command*

 Returns a boolean value that describes whether the command *command* exists and is an ensemble command. This command only ever returns an error if the number of arguments to the command is wrong. 

  When called, an ensemble command takes its first argument and looks it up (according to the rules described below) to discover a list of words to replace the ensemble command and subcommand with. The resulting list of words is then evaluated (with no further substitutions) as if that was what was typed originally (i.e. by passing the list of words through **[Tcl\_EvalObjv](https://www.tcl.tk/man/tcl/TclLib/Eval.htm)**) and returning the result of the command. Note that it is legal to make the target of an ensemble rewrite be another (or even the same) ensemble command. The ensemble command will not be visible through the use of the **[uplevel](uplevel.htm)** or **[info level](info.htm)** commands. 


### Ensemble options

 The following options, supported by the **namespace ensemble create** and **namespace ensemble configure** commands, control how an ensemble command behaves: 
 **-map**
 When non-empty, this option supplies a dictionary that provides a mapping from subcommand names to a list of prefix words to substitute in place of the ensemble command and subcommand words (in a manner similar to an alias created with **[interp alias](interp.htm)**; the words are not reparsed after substitution); if the first word of any target is not fully qualified when set, it is assumed to be relative to the *current* namespace and changed to be exactly that (that is, it is always fully qualified when read). When this option is empty, the mapping will be from the local name of the subcommand to its fully-qualified name. Note that when this option is non-empty and the **-subcommands** option is empty, the ensemble subcommand names will be exactly those words that have mappings in the dictionary. 

**-parameters**
 This option gives a list of named arguments (the names being used during generation of error messages) that are passed by the caller of the ensemble between the name of the ensemble and the subcommand argument. By default, it is the empty list. 

**-prefixes**
 This option (which is enabled by default) controls whether the ensemble command recognizes unambiguous prefixes of its subcommands. When turned off, the ensemble command requires exact matching of subcommand names. 

**-subcommands**
 When non-empty, this option lists exactly what subcommands are in the ensemble. The mapping for each of those commands will be either whatever is defined in the **-map** option, or to the command with the same name in the namespace linked to the ensemble. If this option is empty, the subcommands of the namespace will either be the keys of the dictionary listed in the **-map** option or the exported commands of the linked namespace at the time of the invocation of the ensemble command. 

**-unknown**
 When non-empty, this option provides a partial command (to which all the words that are arguments to the ensemble command, including the fully-qualified name of the ensemble, are appended) to handle the case where an ensemble subcommand is not recognized and would otherwise generate an error. When empty (the default) an error (in the style of **[Tcl\_GetIndexFromObj](https://www.tcl.tk/man/tcl/TclLib/GetIndex.htm)**) is generated whenever the ensemble is unable to determine how to implement a particular subcommand. See **[UNKNOWN HANDLER BEHAVIOUR](#M42)** for more details. 

  The following extra option is allowed by **namespace ensemble create**: 


 **-command**
 This write-only option allows the name of the ensemble created by **namespace ensemble create** to be anything in any existing namespace. The default value for this option is the fully-qualified name of the namespace in which the **namespace ensemble create** command is invoked. 

  The following extra option is allowed by **namespace ensemble configure**: 


 **-namespace**
 This read-only option allows the retrieval of the fully-qualified name of the namespace which the ensemble was created within. 

 ### Unknown handler behaviour

 If an unknown handler is specified for an ensemble, that handler is called when the ensemble command would otherwise return an error due to it being unable to decide which subcommand to invoke. The exact conditions under which that occurs are controlled by the **-subcommands**, **-map** and **-prefixes** options as described above.  To execute the unknown handler, the ensemble mechanism takes the specified **-unknown** option and appends each argument of the attempted ensemble command invocation (including the ensemble command itself, expressed as a fully qualified name). It invokes the resulting command in the scope of the attempted call. If the execution of the unknown handler terminates normally, the ensemble engine reparses the subcommand (as described below) and tries to dispatch it again, which is ideal for when the ensemble's configuration has been updated by the unknown subcommand handler. Any other kind of termination of the unknown handler is treated as an error. 


 The result of the unknown handler is expected to be a list (it is an error if it is not). If the list is an empty list, the ensemble command attempts to look up the original subcommand again and, if it is not found this time, an error will be generated just as if the **-unknown** handler was not there (i.e. for any particular invocation of an ensemble, its unknown handler will be called at most once.) This makes it easy for the unknown handler to update the ensemble or its backing namespace so as to provide an implementation of the desired subcommand and reparse. 


 When the result is a non-empty list, the words of that list are used to replace the ensemble command and subcommand, just as if they had been looked up in the **-map**. It is up to the unknown handler to supply all namespace qualifiers if the implementing subcommand is not in the namespace of the caller of the ensemble command. Also note that when ensemble commands are chained (e.g. if you make one of the commands that implement an ensemble subcommand into an ensemble, in a manner similar to the **[text](../tkcmd/text.htm)** widget's tag and mark subcommands) then the rewrite happens in the context of the caller of the outermost ensemble. That is to say that ensembles do not in themselves place any namespace contexts on the Tcl call stack. 


 Where an empty **-unknown** handler is given (the default), the ensemble command will generate an error message based on the list of commands that the ensemble has defined (formatted similarly to the error message from **[Tcl\_GetIndexFromObj](https://www.tcl.tk/man/tcl/TclLib/GetIndex.htm)**). This is the error that will be thrown when the subcommand is still not recognized during reparsing. It is also an error for an **-unknown** handler to delete its namespace. 


Examples
--------

 Create a namespace containing a variable and an exported command: 

```
**namespace eval** foo {
    variable bar 0
    proc grill {} {
        variable bar
        puts "called [incr bar] times"
    }
    **namespace export** grill
}
```
  Call the command defined in the previous example in various ways. 



```
# Direct call
::foo::grill

# Use the command resolution path to find the name
**namespace eval** boo {
    **namespace path** ::foo
    grill
}

# Import into current namespace, then call local alias
**namespace import** foo::grill
grill

# Create two ensembles, one with the default name and one with a
# specified name.  Then call through the ensembles.
**namespace eval** foo {
    **namespace ensemble** create
    **namespace ensemble** create -command ::foobar
}
foo grill
foobar grill
```
  Look up where the command imported in the previous example came from: 



```
puts "grill came from [**namespace origin** grill]"
```
  Remove all imported commands from the current namespace: 



```
namespace forget {*}[namespace import]
```
  Create an ensemble for simple working with numbers, using the **-parameters** option to allow the operator to be put between the first and second arguments. 



```
**namespace eval** do {
    **namespace export** *
    **namespace ensemble** create -parameters x
    proc plus  {x y} {expr { $x + $y }}
    proc minus {x y} {expr { $x - $y }}
}

# In use, the ensemble works like this:
puts [do 1 plus [do 9 minus 7]]
```
 See also
--------

 **[interp](interp.htm)**, **[upvar](upvar.htm)**, **[variable](variable.htm)** Copyright © 1993-1997 Bell Labs Innovations for Lucent Technologies  
 Copyright © 1997 Sun Microsystems, Inc.  
 Copyright © 2000 Scriptics Corporation.  
 Copyright © 2004-2005 Donal K. Fellows. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/namespace.htm>

ttk\_scale
==========

  
[NAME](ttk_scale.htm#M2) ttk::scale — Create and manipulate a scale widget 
[SYNOPSIS](ttk_scale.htm#M3) 
[DESCRIPTION](ttk_scale.htm#M4) 
[STANDARD OPTIONS](ttk_scale.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 



 
[WIDGET-SPECIFIC OPTIONS](ttk_scale.htm#M6)  
[-command, command, Command](ttk_scale.htm#M7) 
[-from, from, From](ttk_scale.htm#M8) 
[-length, length, Length](ttk_scale.htm#M9) 
[-orient, orient, Orient](ttk_scale.htm#M10) 
[-to, to, To](ttk_scale.htm#M11) 
[-value, value, Value](ttk_scale.htm#M12) 
[-variable, variable, Variable](ttk_scale.htm#M13) 






 
[WIDGET COMMAND](ttk_scale.htm#M14)  
[*pathName* **cget** *option*](ttk_scale.htm#M15) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](ttk_scale.htm#M16) 
[*pathName* **get** ?*x y*?](ttk_scale.htm#M17) 
[*pathName* **identify** *x y*](ttk_scale.htm#M18) 
[*pathName* **instate** *statespec* ?*script*?](ttk_scale.htm#M19) 
[*pathName* **set** *value*](ttk_scale.htm#M20) 
[*pathName* **state** ?*stateSpec*?](ttk_scale.htm#M21) 






 
[INTERNAL COMMANDS](ttk_scale.htm#M22)  
[*pathName* **coords** ?*value*?](ttk_scale.htm#M23) 
 
[SEE ALSO](ttk_scale.htm#M24) 
[KEYWORDS](ttk_scale.htm#M25) 








 Name
----

 ttk::scale — Create and manipulate a scale widget Synopsis
--------

 **ttk::scale** *pathName* ?*options...*?  
 Description
-----------

 A **ttk::scale** widget is typically used to control the numeric value of a linked variable that varies uniformly over some range. A scale displays a *slider* that can be moved along over a *trough*, with the relative position of the slider over the trough indicating the value of the variable. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 



 Widget-specific options
-----------------------

  Command-Line Name: **-command** Database Name: **command** Database Class: **Command** 


Specifies the prefix of a Tcl command to invoke whenever the scale's value is changed via a widget command. The actual command consists of this option followed by a space and a real number indicating the new value of the scale. 

Command-Line Name: **-from** Database Name: **from** Database Class: **From** 


A real value corresponding to the left or top end of the scale. 

Command-Line Name: **-length** Database Name: **length** Database Class: **Length** 


Specifies the desired long dimension of the scale in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**). For vertical scales this is the scale's height; for horizontal scales it is the scale's width. 

Command-Line Name: **-orient** Database Name: **orient** Database Class: **Orient** 


Specifies which orientation whether the widget should be laid out horizontally or vertically. Must be either **horizontal** or **vertical** or an abbreviation of one of these. 

Command-Line Name: **-to** Database Name: **to** Database Class: **To** 


Specifies a real value corresponding to the right or bottom end of the scale. This value may be either less than or greater than the **-from** option. 

Command-Line Name: **-value** Database Name: **value** Database Class: **Value** 


Specifies the current floating-point value of the variable. 

Command-Line Name: **-variable** Database Name: **variable** Database Class: **Variable** 


Specifies the name of a global variable to link to the scale. Whenever the value of the variable changes, the scale will update to reflect this value. Whenever the scale is manipulated interactively, the variable will be modified to reflect the scale's new value. 
 Widget command
--------------


 
*pathName* **cget** *option*

 Returns the current value of the specified *option*; see *ttk::widget(n)*. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Modify or query widget options; see *ttk::widget(n)*. 


*pathName* **get** ?*x y*?
 Get the current value of the **-value** option, or the value corresponding to the coordinates *x,y* if they are specified. *X* and *y* are pixel coordinates relative to the scale widget origin. 


*pathName* **identify** *x y*

 Returns the name of the element at position *x*, *y*. See *ttk::widget(n)*. 


*pathName* **instate** *statespec* ?*script*?
 Test the widget state; see *ttk::widget(n)*. 


*pathName* **set** *value*

 Set the value of the widget (i.e. the **-value** option) to *value*. The value will be clipped to the range given by the **-from** and **-to** options. Note that setting the linked variable (i.e. the variable named in the **-variable** option) does not cause such clipping. 


*pathName* **state** ?*stateSpec*?
 Modify or query the widget state; see *ttk::widget(n)*. 

 Internal commands
-----------------


 
*pathName* **coords** ?*value*?
 Get the coordinates corresponding to *value*, or the coordinates corresponding to the current value of the **-value** option if *value* is omitted. 

 See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[scale](scale.htm)** 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_scale.htm>

lower
=====

 Name
----

 lower — Change a window's position in the stacking order Synopsis
--------

 **lower** *window* ?*belowThis*?  
 Description
-----------

 If the *belowThis* argument is omitted then the command lowers *window* so that it is below all of its siblings in the stacking order (it will be obscured by any siblings that overlap it and will not obscure any siblings). If *belowThis* is specified then it must be the path name of a window that is either a sibling of *window* or the descendant of a sibling of *window*. In this case the **lower** command will insert *window* into the stacking order just below *belowThis* (or the ancestor of *belowThis* that is a sibling of *window*); this could end up either raising or lowering *window*.  All **[toplevel](toplevel.htm)** windows may be restacked with respect to each other, whatever their relative path names, but the window manager is not obligated to strictly honor requests to restack. 


See also
--------

 **[raise](raise.htm)** Copyright © 1990 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/lower.htm>

ttk\_separator
==============

  
[NAME](ttk_separator.htm#M2) ttk::separator — Separator bar 
[SYNOPSIS](ttk_separator.htm#M3) 
[DESCRIPTION](ttk_separator.htm#M4) 
[STANDARD OPTIONS](ttk_separator.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-state, state, State](ttk_widget.htm#M-state) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 




 
[WIDGET-SPECIFIC OPTIONS](ttk_separator.htm#M6)  
[-orient, orient, Orient](ttk_separator.htm#M7) 
 
[WIDGET COMMAND](ttk_separator.htm#M8) 
[SEE ALSO](ttk_separator.htm#M9) 
[KEYWORDS](ttk_separator.htm#M10) 







 Name
----

 ttk::separator — Separator bar Synopsis
--------

 **ttk::separator** *pathName* ?*options*?  
 Description
-----------

 A **ttk::separator** widget displays a horizontal or vertical separator bar. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-state, state, State](ttk_widget.htm#M-state)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 




 Widget-specific options
-----------------------

  Command-Line Name: **-orient** Database Name: **orient** Database Class: **Orient** 


One of **horizontal** or **vertical**. Specifies the orientation of the separator. 
 Widget command
--------------

 Separator widgets support the standard **cget**, **configure**, **identify**, **instate**, and **state** methods. No other widget methods are used. See also
--------

 **[ttk::widget](ttk_widget.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_separator.htm>

clipboard
=========

 Name
----

 clipboard — Manipulate Tk clipboard Synopsis
--------

 **clipboard** *option* ?*arg arg ...*?  
 Description
-----------

 This command provides a Tcl interface to the Tk clipboard, which stores data for later retrieval using the selection mechanism (via the **-selection CLIPBOARD** option). In order to copy data into the clipboard, **clipboard clear** must be called, followed by a sequence of one or more calls to **clipboard append**. To ensure that the clipboard is updated atomically, all appends should be completed before returning to the event loop.  The first argument to **clipboard** determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported: 


 
**clipboard append** ?**-displayof** *window*? ?**-format** *format*? ?**-type** *type*? ?**--**? *data*

 Appends *data* to the clipboard on *window*'s display in the form given by *type* with the representation given by *format* and claims ownership of the clipboard on *window*'s display.  *Type* specifies the form in which the selection is to be returned (the desired “target” for conversion, in ICCCM terminology), and should be an atom name such as **STRING** or **FILE\_NAME**; see the Inter-Client Communication Conventions Manual for complete details. *Type* defaults to **STRING**. 


 The *format* argument specifies the representation that should be used to transmit the selection to the requester (the second column of Table 2 of the ICCCM), and defaults to **STRING**. If *format* is **STRING**, the selection is transmitted as 8-bit ASCII characters. If *format* is **ATOM**, then the *data* is divided into fields separated by white space; each field is converted to its atom value, and the 32-bit atom value is transmitted instead of the atom name. For any other *format*, *data* is divided into fields separated by white space and each field is converted to a 32-bit integer; an array of integers is transmitted to the selection requester. Note that strings passed to **clipboard append** are concatenated before conversion, so the caller must take care to ensure appropriate spacing across string boundaries. All items appended to the clipboard with the same *type* must have the same *format*. 


 The *format* argument is needed only for compatibility with clipboard requesters that do not use Tk. If the Tk toolkit is being used to retrieve the **CLIPBOARD** selection then the value is converted back to a string at the requesting end, so *format* is irrelevant. 


A **--** argument may be specified to mark the end of options: the next argument will always be used as *data*. This feature may be convenient if, for example, *data* starts with a **-**. 




**clipboard clear** ?**-displayof** *window*?
 Claims ownership of the clipboard on *window*'s display and removes any previous contents. *Window* defaults to “.”. Returns an empty string. 


**clipboard get** ?**-displayof** *window*? ?**-type** *type*?
 Retrieve data from the clipboard on *window*'s display. *Window* defaults to “.”. *Type* specifies the form in which the data is to be returned and should be an atom name such as **STRING** or **FILE\_NAME**. *Type* defaults to **STRING**. This command is equivalent to “**[selection get](selection.htm)** **-selection CLIPBOARD**”.  Note that on modern X11 systems, the most useful type to retrieve for transferred strings is not **STRING**, but rather **UTF8\_STRING**. 



 Examples
--------

 Get the current contents of the clipboard. 
```
if {[catch {**clipboard get**} contents]} {
    # There were no clipboard contents at all
}
```
  Set the clipboard to contain a fixed string. 



```
**clipboard clear**
**clipboard append** "some fixed string"
```
  You can put custom data into the clipboard by using a custom **-type** option. This is not necessarily portable, but can be very useful. The method of passing Tcl scripts this way is effective, but should be mixed with safe interpreters in production code. 



```
# This is a very simple canvas serializer;
# it produces a script that recreates the item(s) when executed
proc getItemConfig {canvas tag} {
   set script {}
   foreach item [$canvas find withtag $tag] {
      append script {$canvas create } [$canvas type $item]
      append script { } [$canvas coords $item] { }
      foreach config [$canvas itemconf $item] {
         lassign $config name - - - value
         append script [list $name $value] { }
      }
      append script \n
   }
   return [string trim $script]
}

# Set up a binding on a canvas to cut and paste an item
set c [canvas .c]
pack $c
$c create text 150 30 -text "cut and paste me"
bind $c <<Cut>> {
   **clipboard clear**
   **clipboard append -type** TkCanvasItem \
         [getItemConfig %W current]
   # Delete because this is cut, not copy.
   %W delete current
}
bind $c <<Paste>> {
   catch {
      set canvas %W
      eval [**clipboard get -type** TkCanvasItem]
   }
}
```
 See also
--------

 **[interp](../tclcmd/interp.htm)**, **[selection](selection.htm)** Copyright © 1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/clipboard.htm>

chooseColor
===========

 Name
----

 tk\_chooseColor — pops up a dialog box for the user to select a color. Synopsis
--------

 **tk\_chooseColor** ?*option value ...*?  
 Description
-----------

 The procedure **tk\_chooseColor** pops up a dialog box for the user to select a color. The following *option-value* pairs are possible as command line arguments: 
 
**-initialcolor** *color*

 Specifies the color to display in the color dialog when it pops up. *color* must be in a form acceptable to the **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)** function. 


**-parent** *window*

 Makes *window* the logical parent of the color dialog. The color dialog is displayed on top of its parent window. 


**-title** *titleString*

 Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title will be displayed. 

  If the user selects a color, **tk\_chooseColor** will return the name of the color in a form acceptable to **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. If the user cancels the operation, both commands will return the empty string. 


Example
-------

 
```
button .b -bg [tk_chooseColor -initialcolor gray -title "Choose color"]
```
 Copyright © 1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/chooseColor.htm>

bind
====

  
[NAME](bind.htm#M2) bind — Arrange for X events to invoke Tcl scripts 
[SYNOPSIS](bind.htm#M3) 
[INTRODUCTION](bind.htm#M4) 
[EVENT PATTERNS](bind.htm#M5) 
[MODIFIERS](bind.htm#M6) 
[EVENT TYPES](bind.htm#M7)  
[**Activate**, **Deactivate**](bind.htm#M8) 
[**MouseWheel**](bind.htm#M9) 
[**KeyPress**, **KeyRelease**](bind.htm#M10) 
[**ButtonPress**, **ButtonRelease**, **Motion**](bind.htm#M11) 
[**Configure**](bind.htm#M12) 
[**Map**, **Unmap**](bind.htm#M13) 
[**Visibility**](bind.htm#M14) 
[**Expose**](bind.htm#M15) 
[**Destroy**](bind.htm#M16) 
[**FocusIn**, **FocusOut**](bind.htm#M17) 
[**Enter**, **Leave**](bind.htm#M18) 
[**Property**](bind.htm#M19) 
[**Colormap**](bind.htm#M20) 
[**MapRequest**, **CirculateRequest**, **ResizeRequest**, **ConfigureRequest**, **Create**](bind.htm#M21) 
[**Gravity**, **Reparent**, **Circulate**](bind.htm#M22) 














 
[EVENT DETAILS](bind.htm#M23) 
[BINDING SCRIPTS AND SUBSTITUTIONS](bind.htm#M24)  
[**%%**](bind.htm#M25) 
[**%#**](bind.htm#M26) 
[**%a**](bind.htm#M27) 
[**%b**](bind.htm#M28) 
[**%c**](bind.htm#M29) 
[**%d**](bind.htm#M30) 
[**%f**](bind.htm#M31) 
[**%h**](bind.htm#M32) 
[**%i**](bind.htm#M33) 
[**%k**](bind.htm#M34) 
[**%m**](bind.htm#M35) 
[**%o**](bind.htm#M36) 
[**%p**](bind.htm#M37) 
[**%s**](bind.htm#M38) 
[**%t**](bind.htm#M39) 
[**%w**](bind.htm#M40) 
[**%x**, **%y**](bind.htm#M41) 
[**%A**](bind.htm#M42) 
[**%B**](bind.htm#M43) 
[**%D**](bind.htm#M44) 
[**%E**](bind.htm#M45) 
[**%K**](bind.htm#M46) 
[**%M**](bind.htm#M47) 
[**%N**](bind.htm#M48) 
[**%P**](bind.htm#M49) 
[**%R**](bind.htm#M50) 
[**%S**](bind.htm#M51) 
[**%T**](bind.htm#M52) 
[**%W**](bind.htm#M53) 
[**%X**, **%Y**](bind.htm#M54) 





























 
[MULTIPLE MATCHES](bind.htm#M55) 
[MULTI-EVENT SEQUENCES AND IGNORED EVENTS](bind.htm#M56) 
[ERRORS](bind.htm#M57) 
[EXAMPLES](bind.htm#M58) 
[SEE ALSO](bind.htm#M59) 
[KEYWORDS](bind.htm#M60) 













 Name
----

 bind — Arrange for X events to invoke Tcl scripts Synopsis
--------

 **bind** *tag* ?*sequence*? ?**+**??*script*?  
 Introduction
------------

 The **bind** command associates Tcl scripts with X events. If all three arguments are specified, **bind** will arrange for *script* (a Tcl script) to be evaluated whenever the event(s) given by *sequence* occur in the window(s) identified by *tag*. If *script* is prefixed with a “+”, then it is appended to any existing binding for *sequence*; otherwise *script* replaces any existing binding. If *script* is an empty string then the current binding for *sequence* is destroyed, leaving *sequence* unbound. In all of the cases where a *script* argument is provided, **bind** returns an empty string.  If *sequence* is specified without a *script*, then the script currently bound to *sequence* is returned, or an empty string is returned if there is no binding for *sequence*. If neither *sequence* nor *script* is specified, then the return value is a list whose elements are all the sequences for which there exist bindings for *tag*. 


 The *tag* argument determines which window(s) the binding applies to. If *tag* begins with a dot, as in **.a.b.c**, then it must be the path name for a window; otherwise it may be an arbitrary string. Each window has an associated list of tags, and a binding applies to a particular window if its tag is among those specified for the window. Although the **[bindtags](bindtags.htm)** command may be used to assign an arbitrary set of binding tags to a window, the default binding tags provide the following behavior: 


* If a tag is the name of an internal window the binding applies to that window.
* If the tag is the name of a toplevel window the binding applies to the toplevel window and all its internal windows.
* If the tag is the name of a class of widgets, such as **Button**, the binding applies to all widgets in that class;
* If *tag* has the value **all**, the binding applies to all windows in the application.

 Event patterns
--------------

 The *sequence* argument specifies a sequence of one or more event patterns, with optional white space between the patterns. Each event pattern may take one of three forms. In the simplest case it is a single printing ASCII character, such as **a** or **[**. The character may not be a space character or the character **<**. This form of pattern matches a **KeyPress** event for the particular character. The second form of pattern is longer but more general. It has the following syntax: 
```
**<***modifier-modifier-type-detail***>**
```
 The entire event pattern is surrounded by angle brackets. Inside the angle brackets are zero or more modifiers, an event type, and an extra piece of information (*detail*) identifying a particular button or keysym. Any of the fields may be omitted, as long as at least one of *type* and *detail* is present. The fields must be separated by white space or dashes.  The third form of pattern is used to specify a user-defined, named virtual event. It has the following syntax: 



```
**<<***name***>>**
```
 The entire virtual event pattern is surrounded by double angle brackets. Inside the angle brackets is the user-defined name of the virtual event. Modifiers, such as **Shift** or **Control**, may not be combined with a virtual event to modify it. Bindings on a virtual event may be created before the virtual event is defined, and if the definition of a virtual event changes dynamically, all windows bound to that virtual event will respond immediately to the new definition.  Some widgets (e.g. **[menu](menu.htm)** and **[text](text.htm)**) issue virtual events when their internal state is updated in some ways. Please see the manual page for each widget for details. 


### Modifiers

 Modifiers consist of any of the following values: 

|  |  |
| --- | --- |
| **Control** | **Mod1**, **M1**, **Command** |
| **Alt** | **Mod2**, **M2**, **Option** |
| **Shift** | **Mod3**, **M3** |
| **Lock** | **Mod4**, **M4** |
| **Extended** | **Mod5**, **M5** |
| **Button1**, **B1** | **Meta**, **M** |
| **Button2**, **B2** | **Double** |
| **Button3**, **B3** | **Triple** |
| **Button4**, **B4** | **Quadruple** |
| **Button5**, **B5** |

 Where more than one value is listed, separated by commas, the values are equivalent. Most of the modifiers have the obvious X meanings. For example, **Button1** requires that button 1 be depressed when the event occurs. For a binding to match a given event, the modifiers in the event must include all of those specified in the event pattern. An event may also contain additional modifiers not specified in the binding. For example, if button 1 is pressed while the shift and control keys are down, the pattern **<Control-Button-1>** will match the event, but **<Mod1-Button-1>** will not. If no modifiers are specified, then any combination of modifiers may be present in the event.  **Meta** and **M** refer to whichever of the **M1** through **M5** modifiers is associated with the Meta key(s) on the keyboard (keysyms **Meta\_R** and **Meta\_L**). If there are no Meta keys, or if they are not associated with any modifiers, then **Meta** and **M** will not match any events. Similarly, the **Alt** modifier refers to whichever modifier is associated with the alt key(s) on the keyboard (keysyms **Alt\_L** and **Alt\_R**). 


 The **Double**, **Triple** and **Quadruple** modifiers are a convenience for specifying double mouse clicks and other repeated events. They cause a particular event pattern to be repeated 2, 3 or 4 times, and also place a time and space requirement on the sequence: for a sequence of events to match a **Double**, **Triple** or **Quadruple** pattern, all of the events must occur close together in time and without substantial mouse motion in between. For example, **<Double-Button-1>** is equivalent to **<Button-1><Button-1>** with the extra time and space requirement. 


 The **Command** and **Option** modifiers are equivalents of **Mod1** resp. **Mod2**, they correspond to Macintosh-specific modifier keys. 


 The **Extended** modifier is, at present, specific to Windows. It appears on events that are associated with the keys on the “extended keyboard”. On a US keyboard, the extended keys include the **Alt** and **Control** keys at the right of the keyboard, the cursor keys in the cluster to the left of the numeric pad, the **NumLock** key, the **[Break](../tclcmd/break.htm)** key, the **PrintScreen** key, and the **/** and **Enter** keys in the numeric keypad. 


### Event types

 The *type* field may be any of the standard X event types, with a few extra abbreviations. The *type* field will also accept a couple non-standard X event types that were added to better support the Macintosh and Windows platforms. Below is a list of all the valid types; where two names appear together, they are synonyms. 

|  |  |  |
| --- | --- | --- |
| **Activate** | **Destroy** | **Map** |
| **ButtonPress**, **Button** | **Enter** | **MapRequest** |
| **ButtonRelease** | **Expose** | **Motion** |
| **Circulate** | **FocusIn** | **MouseWheel** |
| **CirculateRequest** | **FocusOut** | **Property** |
| **Colormap** | **Gravity** | **Reparent** |
| **Configure** | **KeyPress**, **Key** | **ResizeRequest** |
| **ConfigureRequest** | **KeyRelease** | **Unmap** |
| **Create** | **Leave** | **Visibility** |
| **Deactivate** |

 Most of the above events have the same fields and behaviors as events in the X Windowing system. You can find more detailed descriptions of these events in any X window programming book. A couple of the events are extensions to the X event system to support features unique to the Macintosh and Windows platforms. We provide a little more detail on these events here. These include: 
 
**Activate**, **Deactivate**

 These two events are sent to every sub-window of a toplevel when they change state. In addition to the focus Window, the Macintosh platform and Windows platforms have a notion of an active window (which often has but is not required to have the focus). On the Macintosh, widgets in the active window have a different appearance than widgets in deactive windows. The **Activate** event is sent to all the sub-windows in a toplevel when it changes from being deactive to active. Likewise, the **Deactive** event is sent when the window's state changes from active to deactive. There are no useful percent substitutions you would make when binding to these events. 

**MouseWheel**
 Many contemporary mice support a mouse wheel, which is used for scrolling documents without using the scrollbars. By rolling the wheel, the system will generate **MouseWheel** events that the application can use to scroll. Like **Key** events the event is always routed to the window that currently has focus. When the event is received you can use the **%D** substitution to get the *delta* field for the event, which is a integer value describing how the mouse wheel has moved. The smallest value for which the system will report is defined by the OS. The sign of the value determines which direction your widget should scroll. Positive values should scroll up and negative values should scroll down. 


**KeyPress**, **KeyRelease**

 The **KeyPress** and **KeyRelease** events are generated whenever a key is pressed or released. **KeyPress** and **KeyRelease** events are sent to the window which currently has the keyboard focus. 


**ButtonPress**, **ButtonRelease**, **Motion**

 The **ButtonPress** and **ButtonRelease** events are generated when the user presses or releases a mouse button. **Motion** events are generated whenever the pointer is moved. **ButtonPress**, **ButtonRelease**, and **Motion** events are normally sent to the window containing the pointer.  When a mouse button is pressed, the window containing the pointer automatically obtains a temporary pointer grab. Subsequent **ButtonPress**, **ButtonRelease**, and **Motion** events will be sent to that window, regardless of which window contains the pointer, until all buttons have been released. 



**Configure**
 A **Configure** event is sent to a window whenever its size, position, or border width changes, and sometimes when it has changed position in the stacking order. 


**Map**, **Unmap**

 The **Map** and **Unmap** events are generated whenever the mapping state of a window changes.  Windows are created in the unmapped state. Top-level windows become mapped when they transition to the **normal** state, and are unmapped in the **withdrawn** and **iconic** states. Other windows become mapped when they are placed under control of a geometry manager (for example **[pack](pack.htm)** or **[grid](grid.htm)**). 


A window is *viewable* only if it and all of its ancestors are mapped. Note that geometry managers typically do not map their children until they have been mapped themselves, and unmap all children when they become unmapped; hence in Tk **Map** and **Unmap** events indicate whether or not a window is viewable. 



**Visibility**
 A window is said to be *obscured* when another window above it in the stacking order fully or partially overlaps it. **Visibility** events are generated whenever a window's obscurity state changes; the *state* field (**%s**) specifies the new state. 

**Expose**
 An **Expose** event is generated whenever all or part of a window should be redrawn (for example, when a window is first mapped or if it becomes unobscured). It is normally not necessary for client applications to handle **Expose** events, since Tk handles them internally. 

**Destroy**
 A **Destroy** event is delivered to a window when it is destroyed.  When the **Destroy** event is delivered to a widget, it is in a “half-dead” state: the widget still exists, but most operations on it will fail. 




**FocusIn**, **FocusOut**

 The **FocusIn** and **FocusOut** events are generated whenever the keyboard focus changes. A **FocusOut** event is sent to the old focus window, and a **FocusIn** event is sent to the new one.  In addition, if the old and new focus windows do not share a common parent, “virtual crossing” focus events are sent to the intermediate windows in the hierarchy. Thus a **FocusIn** event indicates that the target window or one of its descendants has acquired the focus, and a **FocusOut** event indicates that the focus has been changed to a window outside the target window's hierarchy. 


The keyboard focus may be changed explicitly by a call to **[focus](focus.htm)**, or implicitly by the window manager. 




**Enter**, **Leave**

 An **Enter** event is sent to a window when the pointer enters that window, and a **Leave** event is sent when the pointer leaves it.  If there is a pointer grab in effect, **Enter** and **Leave** events are only delivered to the window owning the grab. 


In addition, when the pointer moves between two windows, **Enter** and **Leave** “virtual crossing” events are sent to intermediate windows in the hierarchy in the same manner as for **FocusIn** and **FocusOut** events. 



**Property**
 A **Property** event is sent to a window whenever an X property belonging to that window is changed or deleted. **Property** events are not normally delivered to Tk applications as they are handled by the Tk core. 

**Colormap**
 A **Colormap** event is generated whenever the colormap associated with a window has been changed, installed, or uninstalled.  Widgets may be assigned a private colormap by specifying a **-colormap** option; the window manager is responsible for installing and uninstalling colormaps as necessary. 


Note that Tk provides no useful details for this event type. 




**MapRequest**, **CirculateRequest**, **ResizeRequest**, **ConfigureRequest**, **Create**

 These events are not normally delivered to Tk applications. They are included for completeness, to make it possible to write X11 window managers in Tk. (These events are only delivered when a client has selected **SubstructureRedirectMask** on a window; the Tk core does not use this mask.) 


**Gravity**, **Reparent**, **Circulate**

 The events **Gravity** and **Reparent** are not normally delivered to Tk applications. They are included for completeness.  A **Circulate** event indicates that the window has moved to the top or to the bottom of the stacking order as a result of an **XCirculateSubwindows** protocol request. Note that the stacking order may be changed for other reasons which do not generate a **Circulate** event, and that Tk does not use **XCirculateSubwindows()** internally. This event type is included only for completeness; there is no reliable way to track changes to a window's position in the stacking order. 



 ### Event details

 The last part of a long event specification is *detail*. In the case of a **ButtonPress** or **ButtonRelease** event, it is the number of a button (1-5). If a button number is given, then only an event on that particular button will match; if no button number is given, then an event on any button will match. Note: giving a specific button number is different than specifying a button modifier; in the first case, it refers to a button being pressed or released, while in the second it refers to some other button that is already depressed when the matching event occurs. If a button number is given then *type* may be omitted: if will default to **ButtonPress**. For example, the specifier **<1>** is equivalent to **<ButtonPress-1>**.  If the event type is **KeyPress** or **KeyRelease**, then *detail* may be specified in the form of an X keysym. Keysyms are textual specifications for particular keys on the keyboard; they include all the alphanumeric ASCII characters (e.g. “a” is the keysym for the ASCII character “a”), plus descriptions for non-alphanumeric characters (“comma”is the keysym for the comma character), plus descriptions for all the non-ASCII keys on the keyboard (e.g. “Shift\_L” is the keysym for the left shift key, and “F1” is the keysym for the F1 function key, if it exists). The complete list of keysyms is not presented here; it is available in other X documentation and may vary from system to system. If necessary, you can use the **%K** notation described below to print out the keysym name for a particular key. If a keysym *detail* is given, then the *type* field may be omitted; it will default to **KeyPress**. For example, **<Control-comma>** is equivalent to **<Control-KeyPress-comma>**. 


Binding scripts and substitutions
---------------------------------

 The *script* argument to **bind** is a Tcl script, which will be executed whenever the given event sequence occurs. *Command* will be executed in the same interpreter that the **bind** command was executed in, and it will run at global level (only global variables will be accessible). If *script* contains any **%** characters, then the script will not be executed directly. Instead, a new script will be generated by replacing each **%**, and the character following it, with information from the current event. The replacement depends on the character following the **%**, as defined in the list below. Unless otherwise indicated, the replacement string is the decimal value of the given field from the current event. Some of the substitutions are only valid for certain types of events; if they are used for other types of events the value substituted is undefined. 
 **%%**
 Replaced with a single percent. 

**%#**
 The number of the last client request processed by the server (the *serial* field from the event). Valid for all event types. 

**%a**
 The *above* field from the event, formatted as a hexadecimal number. Valid only for **Configure** events. Indicates the sibling window immediately below the receiving window in the stacking order, or **0** if the receiving window is at the bottom. 

**%b**
 The number of the button that was pressed or released. Valid only for **ButtonPress** and **ButtonRelease** events. 

**%c**
 The *count* field from the event. Valid only for **Expose** events. Indicates that there are *count* pending **Expose** events which have not yet been delivered to the window. 

**%d**
 The *detail* or *user\_data* field from the event. The **%d** is replaced by a string identifying the detail. For **Enter**, **Leave**, **FocusIn**, and **FocusOut** events, the string will be one of the following: 

|  |  |
| --- | --- |
| **NotifyAncestor** | **NotifyNonlinearVirtual** |
| **NotifyDetailNone** | **NotifyPointer** |
| **NotifyInferior** | **NotifyPointerRoot** |
| **NotifyNonlinear** | **NotifyVirtual** |

 For **ConfigureRequest** events, the string will be one of: 

|  |  |
| --- | --- |
| **Above** | **Opposite** |
| **Below** | **None** |
| **BottomIf** | **TopIf** |

 For virtual events, the string will be whatever value is stored in the *user\_data* field when the event was created (typically with **event generate**), or the empty string if the field is NULL. Virtual events corresponding to key sequence presses (see **event add** for details) set the *user\_data* to NULL. For events other than these, the substituted string is undefined. 

**%f**
 The *focus* field from the event (**0** or **1**). Valid only for **Enter** and **Leave** events. **1** if the receiving window is the focus window or a descendant of the focus window, **0** otherwise. 

**%h**
 The *height* field from the event. Valid for the **Configure**, **ConfigureRequest**, **Create**, **ResizeRequest**, and **Expose** events. Indicates the new or requested height of the window. 

**%i**
 The *window* field from the event, represented as a hexadecimal integer. Valid for all event types. 

**%k**
 The *keycode* field from the event. Valid only for **KeyPress** and **KeyRelease** events. 

**%m**
 The *mode* field from the event. The substituted string is one of **NotifyNormal**, **NotifyGrab**, **NotifyUngrab**, or **NotifyWhileGrabbed**. Valid only for **Enter**, **FocusIn**, **FocusOut**, and **Leave** events. 

**%o**
 The *override\_redirect* field from the event. Valid only for **Map**, **Reparent**, and **Configure** events. 

**%p**
 The *place* field from the event, substituted as one of the strings **PlaceOnTop** or **PlaceOnBottom**. Valid only for **Circulate** and **CirculateRequest** events. 

**%s**
 The *state* field from the event. For **ButtonPress**, **ButtonRelease**, **Enter**, **KeyPress**, **KeyRelease**, **Leave**, and **Motion** events, a decimal string is substituted. For **Visibility**, one of the strings **VisibilityUnobscured**, **VisibilityPartiallyObscured**, and **VisibilityFullyObscured** is substituted. For **Property** events, substituted with either the string **NewValue** (indicating that the property has been created or modified) or **Delete** (indicating that the property has been removed). 

**%t**
 The *time* field from the event. This is the X server timestamp (typically the time since the last server reset) in milliseconds, when the event occurred. Valid for most events. 

**%w**
 The *width* field from the event. Indicates the new or requested width of the window. Valid only for **Configure**, **ConfigureRequest**, **Create**, **ResizeRequest**, and **Expose** events. 


**%x**, **%y**

 The *x* and *y* fields from the event. For **ButtonPress**, **ButtonRelease**, **Motion**, **KeyPress**, **KeyRelease**, and **MouseWheel** events, **%x** and **%y** indicate the position of the mouse pointer relative to the receiving window. For **Enter** and **Leave** events, the position where the mouse pointer crossed the window, relative to the receiving window. For **Configure** and **Create** requests, the *x* and *y* coordinates of the window relative to its parent window. 

**%A**
 Substitutes the UNICODE character corresponding to the event, or the empty string if the event does not correspond to a UNICODE character (e.g. the shift key was pressed). **XmbLookupString** (or **XLookupString** when input method support is turned off) does all the work of translating from the event to a UNICODE character. Valid only for **KeyPress** and **KeyRelease** events. 

**%B**
 The *border\_width* field from the event. Valid only for **Configure**, **ConfigureRequest**, and **Create** events. 

**%D**
 This reports the *delta* value of a **MouseWheel** event. The *delta* value represents the rotation units the mouse wheel has been moved. The sign of the value represents the direction the mouse wheel was scrolled. 

**%E**
 The *send\_event* field from the event. Valid for all event types. **0** indicates that this is a “normal” event, **1** indicates that it is a “synthetic” event generated by **SendEvent**. 

**%K**
 The keysym corresponding to the event, substituted as a textual string. Valid only for **KeyPress** and **KeyRelease** events. 

**%M**
 The number of script-based binding patterns matched so far for the event. Valid for all event types. 

**%N**
 The keysym corresponding to the event, substituted as a decimal number. Valid only for **KeyPress** and **KeyRelease** events. 

**%P**
 The name of the property being updated or deleted (which may be converted to an XAtom using **[winfo atom](winfo.htm)**.) Valid only for **Property** events. 

**%R**
 The *root* window identifier from the event. Valid only for events containing a *root* field. 

**%S**
 The *subwindow* window identifier from the event, formatted as a hexadecimal number. Valid only for events containing a *subwindow* field. 

**%T**
 The *type* field from the event. Valid for all event types. 

**%W**
 The path name of the window to which the event was reported (the *window* field from the event). Valid for all event types. 


**%X**, **%Y**

 The *x\_root* and *y\_root* fields from the event. If a virtual-root window manager is being used then the substituted values are the corresponding x-coordinate and y-coordinate in the virtual root. Valid only for **ButtonPress**, **ButtonRelease**, **KeyPress**, **KeyRelease**, and **Motion** events. Same meaning as **%x** and **%y**, except relative to the (virtual) root window. 

  The replacement string for a %-replacement is formatted as a proper Tcl list element. This means that spaces or special characters such as **$** and **{** may be preceded by backslashes. This guarantees that the string will be passed through the Tcl parser when the binding script is evaluated. Most replacements are numbers or well-defined strings such as **Above**; for these replacements no special formatting is ever necessary. The most common case where reformatting occurs is for the **%A** substitution. For example, if *script* is 



```
**insert %A**
```
 and the character typed is an open square bracket, then the script actually executed will be 
```
**insert \[**
```
 This will cause the **insert** to receive the original replacement string (open square bracket) as its first argument. If the extra backslash had not been added, Tcl would not have been able to parse the script correctly. Multiple matches
----------------

 It is possible for several bindings to match a given X event. If the bindings are associated with different *tag*'s, then each of the bindings will be executed, in order. By default, a binding for the widget will be executed first, followed by a class binding, a binding for its toplevel, and an **all** binding. The **[bindtags](bindtags.htm)** command may be used to change this order for a particular window or to associate additional binding tags with the window.  The **[continue](../tclcmd/continue.htm)** and **[break](../tclcmd/break.htm)** commands may be used inside a binding script to control the processing of matching scripts. If **[continue](../tclcmd/continue.htm)** is invoked, then the current binding script is terminated but Tk will continue processing binding scripts associated with other *tag*'s. If the **[break](../tclcmd/break.htm)** command is invoked within a binding script, then that script terminates and no other scripts will be invoked for the event. 


 If more than one binding matches a particular event and they have the same *tag*, then the most specific binding is chosen and its script is evaluated. The following tests are applied, in order, to determine which of several matching sequences is more specific: 


1. an event pattern that specifies a specific button or key is more specific than one that does not;
2. a longer sequence (in terms of number of events matched) is more specific than a shorter sequence;
3. if the modifiers specified in one pattern are a subset of the modifiers in another pattern, then the pattern with more modifiers is more specific.
4. a virtual event whose physical pattern matches the sequence is less specific than the same physical pattern that is not associated with a virtual event.
5. given a sequence that matches two or more virtual events, one of the virtual events will be chosen, but the order is undefined.

  If the matching sequences contain more than one event, then tests (c)-(e) are applied in order from the most recent event to the least recent event in the sequences. If these tests fail to determine a winner, then the most recently registered sequence is the winner. 


 If there are two (or more) virtual events that are both triggered by the same sequence, and both of those virtual events are bound to the same window tag, then only one of the virtual events will be triggered, and it will be picked at random: 



```
event add <<Paste>> <Control-y>
event add <<Paste>> <Button-2>
event add <<Scroll>> <Button-2>
**bind** Entry <<Paste>> {puts Paste}
**bind** Entry <<Scroll>> {puts Scroll}
```
 If the user types Control-y, the **<<Paste>>** binding will be invoked, but if the user presses button 2 then one of either the **<<Paste>>** or the **<<Scroll>>** bindings will be invoked, but exactly which one gets invoked is undefined.  If an X event does not match any of the existing bindings, then the event is ignored. An unbound event is not considered to be an error. 


Multi-event sequences and ignored events
----------------------------------------

 When a *sequence* specified in a **bind** command contains more than one event pattern, then its script is executed whenever the recent events (leading up to and including the current event) match the given sequence. This means, for example, that if button 1 is clicked repeatedly the sequence **<Double-ButtonPress-1>** will match each button press but the first. If extraneous events that would prevent a match occur in the middle of an event sequence then the extraneous events are ignored unless they are **KeyPress** or **ButtonPress** events. For example, **<Double-ButtonPress-1>** will match a sequence of presses of button 1, even though there will be **ButtonRelease** events (and possibly **Motion** events) between the **ButtonPress** events. Furthermore, a **KeyPress** event may be preceded by any number of other **KeyPress** events for modifier keys without the modifier keys preventing a match. For example, the event sequence **aB** will match a press of the **a** key, a release of the **a** key, a press of the **Shift** key, and a press of the **b** key: the press of **Shift** is ignored because it is a modifier key. Finally, if several **Motion** events occur in a row, only the last one is used for purposes of matching binding sequences. Errors
------

 If an error occurs in executing the script for a binding then the **[bgerror](../tclcmd/bgerror.htm)** mechanism is used to report the error. The **[bgerror](../tclcmd/bgerror.htm)** command will be executed at global level (outside the context of any Tcl procedure). Examples
--------

 Arrange for a string describing the motion of the mouse to be printed out when the mouse is double-clicked: 
```
**bind** . <Double-1> {
    puts "hi from (%x,%y)"
}
```
  A little GUI that displays what the keysym name of the last key pressed is: 



```
set keysym "Press any key"
pack [label .l -textvariable keysym -padx 2m -pady 1m]
**bind** . <Key> {
    set keysym "You pressed %K"
}
```
 See also
--------

 **[bgerror](../tclcmd/bgerror.htm)**, **[bindtags](bindtags.htm)**, **[event](event.htm)**, **[focus](focus.htm)**, **[grab](grab.htm)**, **[keysyms](keysyms.htm)** Copyright © 1990 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 1998 by Scriptics Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/bind.htm>

tk
==

  
[NAME](tk.htm#M2) tk — Manipulate Tk internal state 
[SYNOPSIS](tk.htm#M3) 
[DESCRIPTION](tk.htm#M4)  
[**tk appname** ?*newName*?](tk.htm#M5) 
[**tk busy** *subcommand* ...](tk.htm#M6) 
[**tk caret** *window* ?**-x** *x*? ?**-y** *y*? ?**-height** *height*?](tk.htm#M7) 
[**tk inactive** ?**-displayof** *window*? ?**reset**?](tk.htm#M8) 
[**tk fontchooser** *subcommand* ...](tk.htm#M9) 
[**tk scaling** ?**-displayof** *window*? ?*number*?](tk.htm#M10) 
[**tk useinputmethods** ?**-displayof** *window*? ?*boolean*?](tk.htm#M11) 
[**tk windowingsystem**](tk.htm#M12) 







 
[SEE ALSO](tk.htm#M13) 
[KEYWORDS](tk.htm#M14) 




 Name
----

 tk — Manipulate Tk internal state Synopsis
--------

 **tk** *option* ?*arg arg ...*?  
 Description
-----------

 The **tk** command provides access to miscellaneous elements of Tk's internal state. Most of the information manipulated by this command pertains to the application as a whole, or to a screen or display, rather than to a particular window. The command can take any of a number of different forms depending on the *option* argument. The legal forms are: 
 
**tk appname** ?*newName*?
 If *newName* is not specified, this command returns the name of the application (the name that may be used in **[send](send.htm)** commands to communicate with the application). If *newName* is specified, then the name of the application is changed to *newName*. If the given name is already in use, then a suffix of the form “ **#2**” or “ **#3**” is appended in order to make the name unique. The command's result is the name actually chosen. *newName* should not start with a capital letter. This will interfere with option processing, since names starting with capitals are assumed to be classes; as a result, Tk may not be able to find some options for the application. If sends have been disabled by deleting the **[send](send.htm)** command, this command will reenable them and recreate the **[send](send.htm)** command. 


**tk busy** *subcommand* ...
 This command controls the marking of window hierarchies as “busy”, rendering them non-interactive while some other operation is proceeding. For more details see the **[busy](busy.htm)** manual page. 


**tk caret** *window* ?**-x** *x*? ?**-y** *y*? ?**-height** *height*?
 Sets and queries the caret location for the display of the specified Tk window *window*. The caret is the per-display cursor location used for indicating global focus (e.g. to comply with Microsoft Accessibility guidelines), as well as for location of the over-the-spot XIM (X Input Methods) or Windows IME windows. If no options are specified, the last values used for setting the caret are return in option-value pair format. **-x** and **-y** represent window-relative coordinates, and **-height** is the height of the current cursor location, or the height of the specified *window* if none is given. 


**tk inactive** ?**-displayof** *window*? ?**reset**?
 Returns a positive integer, the number of milliseconds since the last time the user interacted with the system. If the **-displayof** option is given then the return value refers to the display of *window*; otherwise it refers to the display of the application's main window.  **tk inactive** will return -1, if querying the user inactive time is not supported by the system, and in safe interpreters. 


If the literal string **reset** is given as an additional argument, the timer is reset and an empty string is returned. Resetting the inactivity time is forbidden in safe interpreters and will throw an error if tried. 




**tk fontchooser** *subcommand* ...
 Controls the Tk font selection dialog. For more details see the **[fontchooser](fontchooser.htm)** manual page. 


**tk scaling** ?**-displayof** *window*? ?*number*?
 Sets and queries the current scaling factor used by Tk to convert between physical units (for example, points, inches, or millimeters) and pixels. The *number* argument is a floating point number that specifies the number of pixels per point on *window*'s display. If the *window* argument is omitted, it defaults to the main window. If the *number* argument is omitted, the current value of the scaling factor is returned.  A “point” is a unit of measurement equal to 1/72 inch. A scaling factor of 1.0 corresponds to 1 pixel per point, which is equivalent to a standard 72 dpi monitor. A scaling factor of 1.25 would mean 1.25 pixels per point, which is the setting for a 90 dpi monitor; setting the scaling factor to 1.25 on a 72 dpi monitor would cause everything in the application to be displayed 1.25 times as large as normal. The initial value for the scaling factor is set when the application starts, based on properties of the installed monitor, but it can be changed at any time. Measurements made after the scaling factor is changed will use the new scaling factor, but it is undefined whether existing widgets will resize themselves dynamically to accommodate the new scaling factor. 




**tk useinputmethods** ?**-displayof** *window*? ?*boolean*?
 Sets and queries the state of whether Tk should use XIM (X Input Methods) for filtering events. The resulting state is returned. XIM is used in some locales (i.e., Japanese, Korean), to handle special input devices. This feature is only significant on X. If XIM support is not available, this will always return 0. If the *window* argument is omitted, it defaults to the main window. If the *boolean* argument is omitted, the current state is returned. This is turned on by default for the main display. 

**tk windowingsystem**
 Returns the current Tk windowing system, one of **x11** (X11-based), **win32** (MS Windows), or **aqua** (Mac OS X Aqua). 

 See also
--------

 **[busy](busy.htm)**, **[fontchooser](fontchooser.htm)**, **[send](send.htm)**, **[winfo](winfo.htm)** Copyright © 1992 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/tk.htm>

ttk\_scrollbar
==============

  
[NAME](ttk_scrollbar.htm#M2) ttk::scrollbar — Control the viewport of a scrollable widget 
[SYNOPSIS](ttk_scrollbar.htm#M3) 
[DESCRIPTION](ttk_scrollbar.htm#M4) 
[STANDARD OPTIONS](ttk_scrollbar.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 



 
[WIDGET-SPECIFIC OPTIONS](ttk_scrollbar.htm#M6)  
[-command, command, Command](ttk_scrollbar.htm#M7) 
[-orient, orient, Orient](ttk_scrollbar.htm#M8) 

 
[WIDGET COMMAND](ttk_scrollbar.htm#M9)  
[*pathName* **cget** *option*](ttk_scrollbar.htm#M10) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](ttk_scrollbar.htm#M11) 
[*pathName* **get**](ttk_scrollbar.htm#M12) 
[*pathName* **identify** *x y*](ttk_scrollbar.htm#M13) 
[*pathName* **instate** *statespec* ?*script*?](ttk_scrollbar.htm#M14) 
[*pathName* **set** *first last*](ttk_scrollbar.htm#M15) 
[*pathName* **state** ?*stateSpec*?](ttk_scrollbar.htm#M16) 






 
[INTERNAL COMMANDS](ttk_scrollbar.htm#M17)  
[*pathName* **delta** *deltaX deltaY*](ttk_scrollbar.htm#M18) 
[*pathName* **fraction** *x y*](ttk_scrollbar.htm#M19) 

 
[SCROLLING COMMANDS](ttk_scrollbar.htm#M20)  
[*prefix* **moveto** *fraction*](ttk_scrollbar.htm#M21) 
[*prefix* **scroll** *number* **units**](ttk_scrollbar.htm#M22) 
[*prefix* **scroll** *number* **pages**](ttk_scrollbar.htm#M23) 


 
[WIDGET STATES](ttk_scrollbar.htm#M24) 
[EXAMPLE](ttk_scrollbar.htm#M25) 
[SEE ALSO](ttk_scrollbar.htm#M26) 
[KEYWORDS](ttk_scrollbar.htm#M27) 











 Name
----

 ttk::scrollbar — Control the viewport of a scrollable widget Synopsis
--------

 **ttk::scrollbar** *pathName* ?*options...*?  
 Description
-----------

 **ttk::scrollbar** widgets are typically linked to an associated window that displays a document of some sort, such as a file being edited or a drawing. A scrollbar displays a *thumb* in the middle portion of the scrollbar, whose position and size provides information about the portion of the document visible in the associated window. The thumb may be dragged by the user to control the visible region. Depending on the theme, two or more arrow buttons may also be present; these are used to scroll the visible region in discrete units. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 



 Widget-specific options
-----------------------

  Command-Line Name: **-command** Database Name: **command** Database Class: **Command** 


A Tcl script prefix to evaluate to change the view in the widget associated with the scrollbar. Additional arguments are appended to the value of this option, as described in **[SCROLLING COMMANDS](#M20)** below, whenever the user requests a view change by manipulating the scrollbar.  This option typically consists of a two-element list, containing the name of a scrollable widget followed by either **xview** (for horizontal scrollbars) or **yview** (for vertical scrollbars). 



Command-Line Name: **-orient** Database Name: **orient** Database Class: **Orient** 


One of **horizontal** or **vertical**. Specifies the orientation of the scrollbar. 
 Widget command
--------------


 
*pathName* **cget** *option*

 Returns the current value of the specified *option*; see *ttk::widget(n)*. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Modify or query widget options; see *ttk::widget(n)*. 


*pathName* **get**

 Returns the scrollbar settings in the form of a list whose elements are the arguments to the most recent **set** widget command. 


*pathName* **identify** *x y*

 Returns the name of the element at position *x*, *y*. See *ttk::widget(n)*. 


*pathName* **instate** *statespec* ?*script*?
 Test the widget state; see *ttk::widget(n)*. 


*pathName* **set** *first last*

 This command is normally invoked by the scrollbar's associated widget from an **-xscrollcommand** or **-yscrollcommand** callback. Specifies the visible range to be displayed. *first* and *last* are real fractions between 0 and 1. 


*pathName* **state** ?*stateSpec*?
 Modify or query the widget state; see *ttk::widget(n)*. 

 Internal commands
-----------------

 The following widget commands are used internally by the TScrollbar widget class bindings. 
 
*pathName* **delta** *deltaX deltaY*

 Returns a real number indicating the fractional change in the scrollbar setting that corresponds to a given change in thumb position. For example, if the scrollbar is horizontal, the result indicates how much the scrollbar setting must change to move the thumb *deltaX* pixels to the right (*deltaY* is ignored in this case). If the scrollbar is vertical, the result indicates how much the scrollbar setting must change to move the thumb *deltaY* pixels down. The arguments and the result may be zero or negative. 


*pathName* **fraction** *x y*

 Returns a real number between 0 and 1 indicating where the point given by *x* and *y* lies in the trough area of the scrollbar, where 0.0 corresponds to the top or left of the trough and 1.0 corresponds to the bottom or right. *X* and *y* are pixel coordinates relative to the scrollbar widget. If *x* and *y* refer to a point outside the trough, the closest point in the trough is used. 

 Scrolling commands
------------------

 When the user interacts with the scrollbar, for example by dragging the thumb, the scrollbar notifies the associated widget that it must change its view. The scrollbar makes the notification by evaluating a Tcl command generated from the scrollbar's **-command** option. The command may take any of the following forms. In each case, *prefix* is the contents of the **-command** option, which usually has a form like **.t yview**
 
*prefix* **moveto** *fraction*

 *Fraction* is a real number between 0 and 1. The widget should adjust its view so that the point given by *fraction* appears at the beginning of the widget. If *fraction* is 0 it refers to the beginning of the document. 1.0 refers to the end of the document, 0.333 refers to a point one-third of the way through the document, and so on. 


*prefix* **scroll** *number* **units**

 The widget should adjust its view by *number* units. The units are defined in whatever way makes sense for the widget, such as characters or lines in a text widget. *Number* is either 1, which means one unit should scroll off the top or left of the window, or -1, which means that one unit should scroll off the bottom or right of the window. 


*prefix* **scroll** *number* **pages**

 The widget should adjust its view by *number* pages. It is up to the widget to define the meaning of a page; typically it is slightly less than what fits in the window, so that there is a slight overlap between the old and new views. *Number* is either 1, which means the next page should become visible, or -1, which means that the previous page should become visible. 

 Widget states
-------------

 The scrollbar automatically sets the **disabled** state bit. when the entire range is visible (range is 0.0 to 1.0), and clears it otherwise. It also sets the **active** and **pressed** state flags of individual elements, based on the position and state of the mouse pointer. Example
-------

 
```
set f [frame .f]
ttk::scrollbar $f.hsb -orient horizontal -command [list $f.t xview]
ttk::scrollbar $f.vsb -orient vertical -command [list $f.t yview]
text $f.t -xscrollcommand [list $f.hsb set] -yscrollcommand [list $f.vsb set]
grid $f.t -row 0 -column 0 -sticky nsew
grid $f.vsb -row 0 -column 1 -sticky nsew
grid $f.hsb -row 1 -column 0 -sticky nsew
grid columnconfigure $f 0 -weight 1
grid rowconfigure $f 0 -weight 1
```
 See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[scrollbar](scrollbar.htm)** Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_scrollbar.htm>

tk\_mac
=======

  
[NAME](tk_mac.htm#M2) tk::mac — Access Mac-Specific Functionality on OS X from Tk 
[SYNOPSIS](tk_mac.htm#M3) 
[EVENT HANDLER CALLBACKS](tk_mac.htm#M4)  
[**::tk::mac::ShowPreferences**](tk_mac.htm#M5) 
[**::tk::mac::OpenApplication**](tk_mac.htm#M6) 
[**::tk::mac::ReopenApplication**](tk_mac.htm#M7) 
[**::tk::mac::OpenDocument** *file...*](tk_mac.htm#M8) 
[**::tk::mac::PrintDocument** *file...*](tk_mac.htm#M9) 
[**::tk::mac::Quit**](tk_mac.htm#M10) 
[**::tk::mac::OnHide**](tk_mac.htm#M11) 
[**::tk::mac::OnShow**](tk_mac.htm#M12) 
[**::tk::mac::ShowHelp**](tk_mac.htm#M13) 








 
[ADDITIONAL DIALOGS](tk_mac.htm#M14)  
[**::tk::mac::standardAboutPanel**](tk_mac.htm#M15) 
 
[SYSTEM CONFIGURATION](tk_mac.htm#M16)  
[**::tk::mac::useCompatibilityMetrics** *boolean*](tk_mac.htm#M17) 
[**::tk::mac::CGAntialiasLimit** *limit*](tk_mac.htm#M18) 
[**::tk::mac::antialiasedtext** *number*](tk_mac.htm#M19) 
[**::tk::mac::useThemedToplevel** *boolean*](tk_mac.htm#M20) 



 
[SUPPORT COMMANDS](tk_mac.htm#M21)  
[**::tk::mac::iconBitmap** *name width height -kind value*](tk_mac.htm#M22)  
[**-file**](tk_mac.htm#M23) 
[**-fileType**](tk_mac.htm#M24) 
[**-osType**](tk_mac.htm#M25) 
[**-systemType**](tk_mac.htm#M26) 
[**-namedImage**](tk_mac.htm#M27) 
[**-imageFile**](tk_mac.htm#M28) 





 
 
[SEE ALSO](tk_mac.htm#M29) 
[KEYWORDS](tk_mac.htm#M30) 







 Name
----

 tk::mac — Access Mac-Specific Functionality on OS X from Tk Synopsis
--------

 **::tk::mac::ShowPreferences**  
 **::tk::mac::OpenApplication**  
 **::tk::mac::ReopenApplication**  
 **::tk::mac::OpenDocument** *file...*  
 **::tk::mac::PrintDocument** *file...*  
 **::tk::mac::Quit**  
 **::tk::mac::OnHide**  
 **::tk::mac::OnShow**  
 **::tk::mac::ShowHelp**  
   
 **::tk::mac::standardAboutPanel**  
   
 **::tk::mac::useCompatibilityMetrics** *boolean*  
 **::tk::mac::CGAntialiasLimit** *limit*  
 **::tk::mac::antialiasedtext** *number*  
 **::tk::mac::useThemedToplevel** *boolean*  
   
 **::tk::mac::iconBitmap** *name width height -kind value*  
 Event handler callbacks
-----------------------

 The Aqua/Mac OS X application environment defines a number of additional events that applications should respond to. These events are mapped by Tk to calls to commands in the **::tk::mac** namespace; unless otherwise noted, if the command is absent, no action will be taken. 
 **::tk::mac::ShowPreferences**
 The default Apple Event handler for kAEShowPreferences, “pref”. The application menu “Preferences” menu item is only enabled when this proc is defined. Typically this command is used to wrap a specific own preferences command, which pops up a preferences window. Something like: 

```
proc ::tk::mac::ShowPreferences {} {
    setPref
}
```


**::tk::mac::OpenApplication**
 If a proc of this name is defined, this proc fill fire when your application is intially opened. It is the default Apple Event handler for kAEOpenApplication, “oapp”. 

**::tk::mac::ReopenApplication**
 If a proc of this name is defined it is the default Apple Event handler for kAEReopenApplication, “rapp”, the Apple Event sent when your application is opened when it is already running (e.g. by clicking its icon in the Dock). Here is a sample that raises a minimized window when the Dock icon is clicked: 

```
proc ::tk::mac::ReopenApplication {} {
    if {[wm state .] eq "withdrawn"} {
        wm state . normal
    } else {
        wm deiconify .
    }
    raise .
}
```



**::tk::mac::OpenDocument** *file...*

 If a proc of this name is defined it is the default Apple Event handler for kAEOpenDocuments, “odoc”, the Apple Event sent when your application is asked to open one or more documents (e.g., by drag & drop onto the app or by opening a document of a type associated to the app). The proc should take as arguments paths to the files to be opened, like so: 

```
proc ::tk::mac::OpenDocument {args} {
    foreach f $args {my_open_document $f}
}
```



**::tk::mac::PrintDocument** *file...*

 If a proc of this name is defined it is the default Apple Event handler for kAEPrintDocuments, “pdoc”, the Apple Event sent when your application is asked to print one or more documents (e.g., via the Print menu item in the Finder). It works the same way as **tk::mac::OpenDocument** in terms of arguments. 

**::tk::mac::Quit**
 If a proc of this name is defined it is the default Apple Event handler for kAEQuitApplication, “quit”, the Apple Event sent when your application is asked to be quit, e.g. via the quit menu item in the application menu, the quit menu item in the Dock menu, or during a logout/restart/shutdown etc. If this is not defined, **[exit](../tclcmd/exit.htm)** is called instead. 

**::tk::mac::OnHide**
 If defined, this is called when your application receives a kEventAppHidden event, e.g. via the hide menu item in the application or Dock menus. 

**::tk::mac::OnShow**
 If defined, this is called when your application receives a kEventAppShown event, e.g. via the show all menu item in the application menu, or by clicking the Dock icon of a hidden application. 

**::tk::mac::ShowHelp**
 Customizes behavior of Apple Help menu; if this procedure is not defined, the platform-specific standard Help menu item “YourApp Help” performs the default Cocoa action of showing the Help Book configured in the application's Info.plist (or displaying an alert if no Help Book is set). 

 Additional dialogs
------------------

 The Aqua/Mac OS X defines additional dialogs that applications should support. 
 **::tk::mac::standardAboutPanel**
 Brings the standard Cocoa about panel to the front, with all its information filled in from your application bundle files (standard about panel with no options specified). See Apple Technote TN2179 and the AppKit documentation for -[NSApplication orderFrontStandardAboutPanelWithOptions:] for details on the Info.plist keys and app bundle files used by the about panel. 

 System configuration
--------------------

 There are a number of additional global configuration options that control the details of how Tk renders by default. 
 
**::tk::mac::useCompatibilityMetrics** *boolean*

 Preserves compatibility with older Tk/Aqua metrics; set to **false** for more native spacing. 


**::tk::mac::CGAntialiasLimit** *limit*

 Sets the antialiasing limit; lines thinner that *limit* pixels will not be antialiased. Integer, set to 0 by default, making all lines be antialiased. 


**::tk::mac::antialiasedtext** *number*

 Sets anti-aliased text. Controls text antialiasing, possible values for *number* are -1 (default, use system default for text AA), 0 (no text AA), 1 (use text AA). 


**::tk::mac::useThemedToplevel** *boolean*

 Sets toplevel windows to draw with the modern grayish/ pinstripe Mac background. Equivalent to configuring the toplevel with “**-background systemWindowHeaderBackground**”, or to using a **[ttk::frame](ttk_frame.htm)**. 

 Support commands
----------------

  
**::tk::mac::iconBitmap** *name width height -kind value*

 Renders native icons and bitmaps in Tk applications (including any image file readable by NSImage). A native bitmap name is interpreted as follows (in order): 
* predefined builtin 32x32 icon name (**stop**, **caution**, **document**, etc.)
* *name*, as defined by **tk::mac::iconBitmap**
* NSImage named image name
* NSImage url string
* 4-char OSType of IconServices icon

   The *width* and *height* arguments to **tk::mac::iconBitmap** define the dimensions of the image to create, and *-kind* must be one of: 


 **-file**
 icon of file at given path 

**-fileType**
 icon of given file type 

**-osType**
 icon of given 4-char OSType file type 

**-systemType**
 icon for given IconServices 4-char OSType 

**-namedImage**
 named NSImage for given name 

**-imageFile**
 image at given path 

 

 See also
--------

 **[bind](bind.htm)**, **[wm](wm.htm)** Copyright © 2011 Kevin Walzer.  
 Copyright © 2011 Donal K. Fellows. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/tk_mac.htm>

ttk\_sizegrip
=============

  
[NAME](ttk_sizegrip.htm#M2) ttk::sizegrip — Bottom-right corner resize widget 
[SYNOPSIS](ttk_sizegrip.htm#M3) 
[DESCRIPTION](ttk_sizegrip.htm#M4) 
[STANDARD OPTIONS](ttk_sizegrip.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-state, state, State](ttk_widget.htm#M-state) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 




 
[WIDGET COMMAND](ttk_sizegrip.htm#M6) 
[PLATFORM-SPECIFIC NOTES](ttk_sizegrip.htm#M7) 
[EXAMPLES](ttk_sizegrip.htm#M8) 
[BUGS](ttk_sizegrip.htm#M9) 
[SEE ALSO](ttk_sizegrip.htm#M10) 
[KEYWORDS](ttk_sizegrip.htm#M11) 









 Name
----

 ttk::sizegrip — Bottom-right corner resize widget Synopsis
--------

 **ttk::sizegrip** *pathName* ?*options*?  
 Description
-----------

 A **ttk::sizegrip** widget (also known as a *grow box*) allows the user to resize the containing toplevel window by pressing and dragging the grip. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-state, state, State](ttk_widget.htm#M-state)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 




 Widget command
--------------

 Sizegrip widgets support the standard **cget**, **configure**, **identify**, **instate**, and **state** methods. No other widget methods are used. Platform-specific notes
-----------------------

 On Mac OSX, toplevel windows automatically include a built-in size grip by default. Adding a **ttk::sizegrip** there is harmless, since the built-in grip will just mask the widget. Examples
--------

 Using pack: 
```
pack [ttk::frame $top.statusbar] -side bottom -fill x
pack [**ttk::sizegrip** $top.statusbar.grip] -side right -anchor se
```
  Using grid: 



```
grid [**ttk::sizegrip** $top.statusbar.grip] \
    -row $lastRow -column $lastColumn -sticky se
# ... optional: add vertical scrollbar in $lastColumn,
# ... optional: add horizontal scrollbar in $lastRow
```
 Bugs
----

 If the containing toplevel's position was specified relative to the right or bottom of the screen (e.g., “**wm geometry ...** *w***x***h***-***x***-***y*” instead of “**wm geometry ...** *w***x***h***+***x***+***y*”), the sizegrip widget will not resize the window.  **ttk::sizegrip** widgets only support “southeast” resizing. 


See also
--------

 **[ttk::widget](ttk_widget.htm)** Copyright © 2006 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_sizegrip.htm>

tkerror
=======

 Name
----

 tkerror — Command invoked to process background errors Synopsis
--------

 **tkerror** *message*  
 Description
-----------

 Note: as of Tk 4.1 the **tkerror** command has been renamed to **[bgerror](../tclcmd/bgerror.htm)** because the event loop (which is what usually invokes it) is now part of Tcl. For backward compatibility the **[bgerror](../tclcmd/bgerror.htm)** provided by the current Tk version still tries to call **tkerror** if there is one (or an auto loadable one), so old script defining that error handler should still work, but you should anyhow modify your scripts to use **[bgerror](../tclcmd/bgerror.htm)** instead of **tkerror** because that support for the old name might vanish in the near future. If that call fails, **[bgerror](../tclcmd/bgerror.htm)** posts a dialog showing the error and offering to see the stack trace to the user. If you want your own error management you should directly override **[bgerror](../tclcmd/bgerror.htm)** instead of **tkerror**. Documentation for **[bgerror](../tclcmd/bgerror.htm)** is available as part of Tcl's documentation. Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/tkerror.htm>

tkwait
======

 Name
----

 tkwait — Wait for variable to change or window to be destroyed Synopsis
--------

 **tkwait variable** *name*  
 **tkwait visibility** *name*  
 **tkwait window** *name*  
 Description
-----------

 The **tkwait** command waits for one of several things to happen, then it returns without taking any other actions. The return value is always an empty string. If the first argument is **variable** (or any abbreviation of it) then the second argument is the name of a global variable and the command waits for that variable to be modified. If the first argument is **visibility** (or any abbreviation of it) then the second argument is the name of a window and the **tkwait** command waits for a change in its visibility state (as indicated by the arrival of a VisibilityNotify event). This form is typically used to wait for a newly-created window to appear on the screen before taking some action. If the first argument is **window** (or any abbreviation of it) then the second argument is the name of a window and the **tkwait** command waits for that window to be destroyed. This form is typically used to wait for a user to finish interacting with a dialog box before using the result of that interaction.  While the **tkwait** command is waiting it processes events in the normal fashion, so the application will continue to respond to user interactions. If an event handler invokes **tkwait** again, the nested call to **tkwait** must complete before the outer call can complete. 


See also
--------

 **[bind](bind.htm)**, **[vwait](../tclcmd/vwait.htm)** Copyright © 1992 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/tkwait.htm>

chooseDirectory
===============

  
[NAME](choosedirectory.htm#M2) tk\_chooseDirectory — pops up a dialog box for the user to select a directory. 
[SYNOPSIS](choosedirectory.htm#M3) 
[DESCRIPTION](choosedirectory.htm#M4)  
[**-initialdir** *dirname*](choosedirectory.htm#M5) 
[**-mustexist** *boolean*](choosedirectory.htm#M6) 
[**-parent** *window*](choosedirectory.htm#M7) 
[**-title** *titleString*](choosedirectory.htm#M8) 



 
[EXAMPLE](choosedirectory.htm#M9) 
[SEE ALSO](choosedirectory.htm#M10) 
[KEYWORDS](choosedirectory.htm#M11) 





 Name
----

 tk\_chooseDirectory — pops up a dialog box for the user to select a directory. Synopsis
--------

 **tk\_chooseDirectory** ?*option value ...*?  
 Description
-----------

 The procedure **tk\_chooseDirectory** pops up a dialog box for the user to select a directory. The following *option-value* pairs are possible as command line arguments: 
 
**-initialdir** *dirname*

 Specifies that the directories in *directory* should be displayed when the dialog pops up. If this parameter is not specified, the initial directory defaults to the current working directory on non-Windows systems and on Windows systems prior to Vista. On Vista and later systems, the initial directory defaults to the last user-selected directory for the application. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. 


**-mustexist** *boolean*

 Specifies whether the user may specify non-existent directories. If this parameter is true, then the user may only select directories that already exist. The default value is *false*. 


**-parent** *window*

 Makes *window* the logical parent of the dialog. The dialog is displayed on top of its parent window. On Mac OS X, this turns the file dialog into a sheet attached to the parent window. 


**-title** *titleString*

 Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title will be displayed. 

 Example
-------

 
```
set dir [**tk\_chooseDirectory** \
        -initialdir ~ -title "Choose a directory"]
if {$dir eq ""} {
   label .l -text "No directory selected"
} else {
   label .l -text "Selected $dir"
}
```
 See also
--------

 **tk\_getOpenFile**, **tk\_getSaveFile** Copyright © 1998-2000 by Scriptics Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/chooseDirectory.htm>

keysyms
=======

 Name
----

 keysyms — keysyms recognized by Tk Description
-----------

 Tk recognizes many keysyms when specifying key bindings (e.g., “**[bind](bind.htm)** **. <Key-***keysym***>**”). The following list enumerates the keysyms that will be recognized by Tk. Note that not all keysyms will be valid on all platforms. For example, on Unix systems, the presence of a particular keysym is dependant on the configuration of the keyboard modifier map. This list shows keysyms along with their decimal and hexadecimal values. 

```
space                               32     0x0020
exclam                              33     0x0021
quotedbl                            34     0x0022
numbersign                          35     0x0023
dollar                              36     0x0024
percent                             37     0x0025
ampersand                           38     0x0026
quoteright                          39     0x0027
parenleft                           40     0x0028
parenright                          41     0x0029
asterisk                            42     0x002a
plus                                43     0x002b
comma                               44     0x002c
minus                               45     0x002d
period                              46     0x002e
slash                               47     0x002f
0                                   48     0x0030
1                                   49     0x0031
2                                   50     0x0032
3                                   51     0x0033
4                                   52     0x0034
5                                   53     0x0035
6                                   54     0x0036
7                                   55     0x0037
8                                   56     0x0038
9                                   57     0x0039
colon                               58     0x003a
semicolon                           59     0x003b
less                                60     0x003c
equal                               61     0x003d
greater                             62     0x003e
question                            63     0x003f
at                                  64     0x0040
A                                   65     0x0041
B                                   66     0x0042
C                                   67     0x0043
D                                   68     0x0044
E                                   69     0x0045
F                                   70     0x0046
G                                   71     0x0047
H                                   72     0x0048
I                                   73     0x0049
J                                   74     0x004a
K                                   75     0x004b
L                                   76     0x004c
M                                   77     0x004d
N                                   78     0x004e
O                                   79     0x004f
P                                   80     0x0050
Q                                   81     0x0051
R                                   82     0x0052
S                                   83     0x0053
T                                   84     0x0054
U                                   85     0x0055
V                                   86     0x0056
W                                   87     0x0057
X                                   88     0x0058
Y                                   89     0x0059
Z                                   90     0x005a
bracketleft                         91     0x005b
backslash                           92     0x005c
bracketright                        93     0x005d
asciicircum                         94     0x005e
underscore                          95     0x005f
quoteleft                           96     0x0060
a                                   97     0x0061
b                                   98     0x0062
c                                   99     0x0063
d                                  100     0x0064
e                                  101     0x0065
f                                  102     0x0066
g                                  103     0x0067
h                                  104     0x0068
i                                  105     0x0069
j                                  106     0x006a
k                                  107     0x006b
l                                  108     0x006c
m                                  109     0x006d
n                                  110     0x006e
o                                  111     0x006f
p                                  112     0x0070
q                                  113     0x0071
r                                  114     0x0072
s                                  115     0x0073
t                                  116     0x0074
u                                  117     0x0075
v                                  118     0x0076
w                                  119     0x0077
x                                  120     0x0078
y                                  121     0x0079
z                                  122     0x007a
braceleft                          123     0x007b
bar                                124     0x007c
braceright                         125     0x007d
asciitilde                         126     0x007e
nobreakspace                       160     0x00a0
exclamdown                         161     0x00a1
cent                               162     0x00a2
sterling                           163     0x00a3
currency                           164     0x00a4
yen                                165     0x00a5
brokenbar                          166     0x00a6
section                            167     0x00a7
diaeresis                          168     0x00a8
copyright                          169     0x00a9
ordfeminine                        170     0x00aa
guillemotleft                      171     0x00ab
notsign                            172     0x00ac
hyphen                             173     0x00ad
registered                         174     0x00ae
macron                             175     0x00af
degree                             176     0x00b0
plusminus                          177     0x00b1
twosuperior                        178     0x00b2
threesuperior                      179     0x00b3
acute                              180     0x00b4
mu                                 181     0x00b5
paragraph                          182     0x00b6
periodcentered                     183     0x00b7
cedilla                            184     0x00b8
onesuperior                        185     0x00b9
masculine                          186     0x00ba
guillemotright                     187     0x00bb
onequarter                         188     0x00bc
onehalf                            189     0x00bd
threequarters                      190     0x00be
questiondown                       191     0x00bf
Agrave                             192     0x00c0
Aacute                             193     0x00c1
Acircumflex                        194     0x00c2
Atilde                             195     0x00c3
Adiaeresis                         196     0x00c4
Aring                              197     0x00c5
AE                                 198     0x00c6
Ccedilla                           199     0x00c7
Egrave                             200     0x00c8
Eacute                             201     0x00c9
Ecircumflex                        202     0x00ca
Ediaeresis                         203     0x00cb
Igrave                             204     0x00cc
Iacute                             205     0x00cd
Icircumflex                        206     0x00ce
Idiaeresis                         207     0x00cf
Eth                                208     0x00d0
Ntilde                             209     0x00d1
Ograve                             210     0x00d2
Oacute                             211     0x00d3
Ocircumflex                        212     0x00d4
Otilde                             213     0x00d5
Odiaeresis                         214     0x00d6
multiply                           215     0x00d7
Ooblique                           216     0x00d8
Ugrave                             217     0x00d9
Uacute                             218     0x00da
Ucircumflex                        219     0x00db
Udiaeresis                         220     0x00dc
Yacute                             221     0x00dd
Thorn                              222     0x00de
ssharp                             223     0x00df
agrave                             224     0x00e0
aacute                             225     0x00e1
acircumflex                        226     0x00e2
atilde                             227     0x00e3
adiaeresis                         228     0x00e4
aring                              229     0x00e5
ae                                 230     0x00e6
ccedilla                           231     0x00e7
egrave                             232     0x00e8
eacute                             233     0x00e9
ecircumflex                        234     0x00ea
ediaeresis                         235     0x00eb
igrave                             236     0x00ec
iacute                             237     0x00ed
icircumflex                        238     0x00ee
idiaeresis                         239     0x00ef
eth                                240     0x00f0
ntilde                             241     0x00f1
ograve                             242     0x00f2
oacute                             243     0x00f3
ocircumflex                        244     0x00f4
otilde                             245     0x00f5
odiaeresis                         246     0x00f6
division                           247     0x00f7
oslash                             248     0x00f8
ugrave                             249     0x00f9
uacute                             250     0x00fa
ucircumflex                        251     0x00fb
udiaeresis                         252     0x00fc
yacute                             253     0x00fd
thorn                              254     0x00fe
ydiaeresis                         255     0x00ff
Aogonek                            417     0x01a1
breve                              418     0x01a2
Lstroke                            419     0x01a3
Lcaron                             421     0x01a5
Sacute                             422     0x01a6
Scaron                             425     0x01a9
Scedilla                           426     0x01aa
Tcaron                             427     0x01ab
Zacute                             428     0x01ac
```
 
```
Zcaron                             430     0x01ae
Zabovedot                          431     0x01af
aogonek                            433     0x01b1
ogonek                             434     0x01b2
lstroke                            435     0x01b3
lcaron                             437     0x01b5
sacute                             438     0x01b6
caron                              439     0x01b7
scaron                             441     0x01b9
scedilla                           442     0x01ba
tcaron                             443     0x01bb
zacute                             444     0x01bc
doubleacute                        445     0x01bd
zcaron                             446     0x01be
zabovedot                          447     0x01bf
Racute                             448     0x01c0
Abreve                             451     0x01c3
Cacute                             454     0x01c6
Ccaron                             456     0x01c8
Eogonek                            458     0x01ca
Ecaron                             460     0x01cc
Dcaron                             463     0x01cf
Nacute                             465     0x01d1
Ncaron                             466     0x01d2
Odoubleacute                       469     0x01d5
Rcaron                             472     0x01d8
Uring                              473     0x01d9
Udoubleacute                       475     0x01db
Tcedilla                           478     0x01de
racute                             480     0x01e0
abreve                             483     0x01e3
cacute                             486     0x01e6
ccaron                             488     0x01e8
eogonek                            490     0x01ea
ecaron                             492     0x01ec
dcaron                             495     0x01ef
nacute                             497     0x01f1
ncaron                             498     0x01f2
odoubleacute                       501     0x01f5
rcaron                             504     0x01f8
uring                              505     0x01f9
udoubleacute                       507     0x01fb
tcedilla                           510     0x01fe
abovedot                           511     0x01ff
Hstroke                            673     0x02a1
Hcircumflex                        678     0x02a6
Iabovedot                          681     0x02a9
Gbreve                             683     0x02ab
Jcircumflex                        684     0x02ac
hstroke                            689     0x02b1
hcircumflex                        694     0x02b6
idotless                           697     0x02b9
gbreve                             699     0x02bb
jcircumflex                        700     0x02bc
Cabovedot                          709     0x02c5
Ccircumflex                        710     0x02c6
Gabovedot                          725     0x02d5
Gcircumflex                        728     0x02d8
Ubreve                             733     0x02dd
Scircumflex                        734     0x02de
cabovedot                          741     0x02e5
ccircumflex                        742     0x02e6
gabovedot                          757     0x02f5
gcircumflex                        760     0x02f8
ubreve                             765     0x02fd
scircumflex                        766     0x02fe
kappa                              930     0x03a2
Rcedilla                           931     0x03a3
Itilde                             933     0x03a5
Lcedilla                           934     0x03a6
Emacron                            938     0x03aa
Gcedilla                           939     0x03ab
Tslash                             940     0x03ac
rcedilla                           947     0x03b3
itilde                             949     0x03b5
lcedilla                           950     0x03b6
emacron                            954     0x03ba
gacute                             955     0x03bb
tslash                             956     0x03bc
ENG                                957     0x03bd
eng                                959     0x03bf
Amacron                            960     0x03c0
Iogonek                            967     0x03c7
Eabovedot                          972     0x03cc
Imacron                            975     0x03cf
Ncedilla                           977     0x03d1
Omacron                            978     0x03d2
Kcedilla                           979     0x03d3
Uogonek                            985     0x03d9
Utilde                             989     0x03dd
Umacron                            990     0x03de
amacron                            992     0x03e0
iogonek                            999     0x03e7
eabovedot                         1004     0x03ec
imacron                           1007     0x03ef
ncedilla                          1009     0x03f1
omacron                           1010     0x03f2
kcedilla                          1011     0x03f3
uogonek                           1017     0x03f9
utilde                            1021     0x03fd
umacron                           1022     0x03fe
overline                          1150     0x047e
kana_fullstop                     1185     0x04a1
kana_openingbracket               1186     0x04a2
kana_closingbracket               1187     0x04a3
kana_comma                        1188     0x04a4
kana_middledot                    1189     0x04a5
kana_WO                           1190     0x04a6
kana_a                            1191     0x04a7
kana_i                            1192     0x04a8
kana_u                            1193     0x04a9
kana_e                            1194     0x04aa
kana_o                            1195     0x04ab
kana_ya                           1196     0x04ac
kana_yu                           1197     0x04ad
kana_yo                           1198     0x04ae
kana_tu                           1199     0x04af
prolongedsound                    1200     0x04b0
kana_A                            1201     0x04b1
kana_I                            1202     0x04b2
kana_U                            1203     0x04b3
kana_E                            1204     0x04b4
kana_O                            1205     0x04b5
kana_KA                           1206     0x04b6
kana_KI                           1207     0x04b7
kana_KU                           1208     0x04b8
kana_KE                           1209     0x04b9
kana_KO                           1210     0x04ba
kana_SA                           1211     0x04bb
kana_SHI                          1212     0x04bc
kana_SU                           1213     0x04bd
kana_SE                           1214     0x04be
kana_SO                           1215     0x04bf
kana_TA                           1216     0x04c0
kana_TI                           1217     0x04c1
kana_TU                           1218     0x04c2
kana_TE                           1219     0x04c3
kana_TO                           1220     0x04c4
kana_NA                           1221     0x04c5
kana_NI                           1222     0x04c6
kana_NU                           1223     0x04c7
kana_NE                           1224     0x04c8
kana_NO                           1225     0x04c9
kana_HA                           1226     0x04ca
kana_HI                           1227     0x04cb
kana_HU                           1228     0x04cc
kana_HE                           1229     0x04cd
kana_HO                           1230     0x04ce
kana_MA                           1231     0x04cf
kana_MI                           1232     0x04d0
kana_MU                           1233     0x04d1
kana_ME                           1234     0x04d2
kana_MO                           1235     0x04d3
kana_YA                           1236     0x04d4
kana_YU                           1237     0x04d5
kana_YO                           1238     0x04d6
kana_RA                           1239     0x04d7
kana_RI                           1240     0x04d8
kana_RU                           1241     0x04d9
kana_RE                           1242     0x04da
kana_RO                           1243     0x04db
kana_WA                           1244     0x04dc
kana_N                            1245     0x04dd
voicedsound                       1246     0x04de
semivoicedsound                   1247     0x04df
Arabic_comma                      1452     0x05ac
Arabic_semicolon                  1467     0x05bb
Arabic_question_mark              1471     0x05bf
Arabic_hamza                      1473     0x05c1
Arabic_maddaonalef                1474     0x05c2
Arabic_hamzaonalef                1475     0x05c3
Arabic_hamzaonwaw                 1476     0x05c4
Arabic_hamzaunderalef             1477     0x05c5
Arabic_hamzaonyeh                 1478     0x05c6
Arabic_alef                       1479     0x05c7
Arabic_beh                        1480     0x05c8
Arabic_tehmarbuta                 1481     0x05c9
Arabic_teh                        1482     0x05ca
Arabic_theh                       1483     0x05cb
Arabic_jeem                       1484     0x05cc
Arabic_hah                        1485     0x05cd
Arabic_khah                       1486     0x05ce
Arabic_dal                        1487     0x05cf
Arabic_thal                       1488     0x05d0
Arabic_ra                         1489     0x05d1
Arabic_zain                       1490     0x05d2
Arabic_seen                       1491     0x05d3
Arabic_sheen                      1492     0x05d4
Arabic_sad                        1493     0x05d5
Arabic_dad                        1494     0x05d6
Arabic_tah                        1495     0x05d7
Arabic_zah                        1496     0x05d8
Arabic_ain                        1497     0x05d9
Arabic_ghain                      1498     0x05da
Arabic_tatweel                    1504     0x05e0
Arabic_feh                        1505     0x05e1
Arabic_qaf                        1506     0x05e2
Arabic_kaf                        1507     0x05e3
Arabic_lam                        1508     0x05e4
Arabic_meem                       1509     0x05e5
```
 
```
Arabic_noon                       1510     0x05e6
Arabic_heh                        1511     0x05e7
Arabic_waw                        1512     0x05e8
Arabic_alefmaksura                1513     0x05e9
Arabic_yeh                        1514     0x05ea
Arabic_fathatan                   1515     0x05eb
Arabic_dammatan                   1516     0x05ec
Arabic_kasratan                   1517     0x05ed
Arabic_fatha                      1518     0x05ee
Arabic_damma                      1519     0x05ef
Arabic_kasra                      1520     0x05f0
Arabic_shadda                     1521     0x05f1
Arabic_sukun                      1522     0x05f2
Serbian_dje                       1697     0x06a1
Macedonia_gje                     1698     0x06a2
Cyrillic_io                       1699     0x06a3
Ukranian_je                       1700     0x06a4
Macedonia_dse                     1701     0x06a5
Ukranian_i                        1702     0x06a6
Ukranian_yi                       1703     0x06a7
Serbian_je                        1704     0x06a8
Serbian_lje                       1705     0x06a9
Serbian_nje                       1706     0x06aa
Serbian_tshe                      1707     0x06ab
Macedonia_kje                     1708     0x06ac
Byelorussian_shortu               1710     0x06ae
Serbian_dze                       1711     0x06af
numerosign                        1712     0x06b0
Serbian_DJE                       1713     0x06b1
Macedonia_GJE                     1714     0x06b2
Cyrillic_IO                       1715     0x06b3
Ukranian_JE                       1716     0x06b4
Macedonia_DSE                     1717     0x06b5
Ukranian_I                        1718     0x06b6
Ukranian_YI                       1719     0x06b7
Serbian_JE                        1720     0x06b8
Serbian_LJE                       1721     0x06b9
Serbian_NJE                       1722     0x06ba
Serbian_TSHE                      1723     0x06bb
Macedonia_KJE                     1724     0x06bc
Byelorussian_SHORTU               1726     0x06be
Serbian_DZE                       1727     0x06bf
Cyrillic_yu                       1728     0x06c0
Cyrillic_a                        1729     0x06c1
Cyrillic_be                       1730     0x06c2
Cyrillic_tse                      1731     0x06c3
Cyrillic_de                       1732     0x06c4
Cyrillic_ie                       1733     0x06c5
Cyrillic_ef                       1734     0x06c6
Cyrillic_ghe                      1735     0x06c7
Cyrillic_ha                       1736     0x06c8
Cyrillic_i                        1737     0x06c9
Cyrillic_shorti                   1738     0x06ca
Cyrillic_ka                       1739     0x06cb
Cyrillic_el                       1740     0x06cc
Cyrillic_em                       1741     0x06cd
Cyrillic_en                       1742     0x06ce
Cyrillic_o                        1743     0x06cf
Cyrillic_pe                       1744     0x06d0
Cyrillic_ya                       1745     0x06d1
Cyrillic_er                       1746     0x06d2
Cyrillic_es                       1747     0x06d3
Cyrillic_te                       1748     0x06d4
Cyrillic_u                        1749     0x06d5
Cyrillic_zhe                      1750     0x06d6
Cyrillic_ve                       1751     0x06d7
Cyrillic_softsign                 1752     0x06d8
Cyrillic_yeru                     1753     0x06d9
Cyrillic_ze                       1754     0x06da
Cyrillic_sha                      1755     0x06db
Cyrillic_e                        1756     0x06dc
Cyrillic_shcha                    1757     0x06dd
Cyrillic_che                      1758     0x06de
Cyrillic_hardsign                 1759     0x06df
Cyrillic_YU                       1760     0x06e0
Cyrillic_A                        1761     0x06e1
Cyrillic_BE                       1762     0x06e2
Cyrillic_TSE                      1763     0x06e3
Cyrillic_DE                       1764     0x06e4
Cyrillic_IE                       1765     0x06e5
Cyrillic_EF                       1766     0x06e6
Cyrillic_GHE                      1767     0x06e7
Cyrillic_HA                       1768     0x06e8
Cyrillic_I                        1769     0x06e9
Cyrillic_SHORTI                   1770     0x06ea
Cyrillic_KA                       1771     0x06eb
Cyrillic_EL                       1772     0x06ec
Cyrillic_EM                       1773     0x06ed
Cyrillic_EN                       1774     0x06ee
Cyrillic_O                        1775     0x06ef
Cyrillic_PE                       1776     0x06f0
Cyrillic_YA                       1777     0x06f1
Cyrillic_ER                       1778     0x06f2
Cyrillic_ES                       1779     0x06f3
Cyrillic_TE                       1780     0x06f4
Cyrillic_U                        1781     0x06f5
Cyrillic_ZHE                      1782     0x06f6
Cyrillic_VE                       1783     0x06f7
Cyrillic_SOFTSIGN                 1784     0x06f8
Cyrillic_YERU                     1785     0x06f9
Cyrillic_ZE                       1786     0x06fa
Cyrillic_SHA                      1787     0x06fb
Cyrillic_E                        1788     0x06fc
Cyrillic_SHCHA                    1789     0x06fd
Cyrillic_CHE                      1790     0x06fe
Cyrillic_HARDSIGN                 1791     0x06ff
Greek_ALPHAaccent                 1953     0x07a1
Greek_EPSILONaccent               1954     0x07a2
Greek_ETAaccent                   1955     0x07a3
Greek_IOTAaccent                  1956     0x07a4
Greek_IOTAdiaeresis               1957     0x07a5
Greek_IOTAaccentdiaeresis         1958     0x07a6
Greek_OMICRONaccent               1959     0x07a7
Greek_UPSILONaccent               1960     0x07a8
Greek_UPSILONdieresis             1961     0x07a9
Greek_UPSILONaccentdieresis       1962     0x07aa
Greek_OMEGAaccent                 1963     0x07ab
Greek_alphaaccent                 1969     0x07b1
Greek_epsilonaccent               1970     0x07b2
Greek_etaaccent                   1971     0x07b3
Greek_iotaaccent                  1972     0x07b4
Greek_iotadieresis                1973     0x07b5
Greek_iotaaccentdieresis          1974     0x07b6
Greek_omicronaccent               1975     0x07b7
Greek_upsilonaccent               1976     0x07b8
Greek_upsilondieresis             1977     0x07b9
Greek_upsilonaccentdieresis       1978     0x07ba
Greek_omegaaccent                 1979     0x07bb
Greek_ALPHA                       1985     0x07c1
Greek_BETA                        1986     0x07c2
Greek_GAMMA                       1987     0x07c3
Greek_DELTA                       1988     0x07c4
Greek_EPSILON                     1989     0x07c5
Greek_ZETA                        1990     0x07c6
Greek_ETA                         1991     0x07c7
Greek_THETA                       1992     0x07c8
Greek_IOTA                        1993     0x07c9
Greek_KAPPA                       1994     0x07ca
Greek_LAMBDA                      1995     0x07cb
Greek_MU                          1996     0x07cc
Greek_NU                          1997     0x07cd
Greek_XI                          1998     0x07ce
Greek_OMICRON                     1999     0x07cf
Greek_PI                          2000     0x07d0
Greek_RHO                         2001     0x07d1
Greek_SIGMA                       2002     0x07d2
Greek_TAU                         2004     0x07d4
Greek_UPSILON                     2005     0x07d5
Greek_PHI                         2006     0x07d6
Greek_CHI                         2007     0x07d7
Greek_PSI                         2008     0x07d8
Greek_OMEGA                       2009     0x07d9
Greek_alpha                       2017     0x07e1
Greek_beta                        2018     0x07e2
Greek_gamma                       2019     0x07e3
Greek_delta                       2020     0x07e4
Greek_epsilon                     2021     0x07e5
Greek_zeta                        2022     0x07e6
Greek_eta                         2023     0x07e7
Greek_theta                       2024     0x07e8
Greek_iota                        2025     0x07e9
Greek_kappa                       2026     0x07ea
Greek_lambda                      2027     0x07eb
Greek_mu                          2028     0x07ec
Greek_nu                          2029     0x07ed
Greek_xi                          2030     0x07ee
Greek_omicron                     2031     0x07ef
Greek_pi                          2032     0x07f0
Greek_rho                         2033     0x07f1
Greek_sigma                       2034     0x07f2
Greek_finalsmallsigma             2035     0x07f3
Greek_tau                         2036     0x07f4
Greek_upsilon                     2037     0x07f5
Greek_phi                         2038     0x07f6
Greek_chi                         2039     0x07f7
Greek_psi                         2040     0x07f8
Greek_omega                       2041     0x07f9
leftradical                       2209     0x08a1
topleftradical                    2210     0x08a2
horizconnector                    2211     0x08a3
topintegral                       2212     0x08a4
botintegral                       2213     0x08a5
vertconnector                     2214     0x08a6
topleftsqbracket                  2215     0x08a7
botleftsqbracket                  2216     0x08a8
toprightsqbracket                 2217     0x08a9
botrightsqbracket                 2218     0x08aa
topleftparens                     2219     0x08ab
botleftparens                     2220     0x08ac
toprightparens                    2221     0x08ad
botrightparens                    2222     0x08ae
leftmiddlecurlybrace              2223     0x08af
rightmiddlecurlybrace             2224     0x08b0
topleftsummation                  2225     0x08b1
botleftsummation                  2226     0x08b2
topvertsummationconnector         2227     0x08b3
botvertsummationconnector         2228     0x08b4
toprightsummation                 2229     0x08b5
botrightsummation                 2230     0x08b6
rightmiddlesummation              2231     0x08b7
```
 
```
lessthanequal                     2236     0x08bc
notequal                          2237     0x08bd
greaterthanequal                  2238     0x08be
integral                          2239     0x08bf
therefore                         2240     0x08c0
variation                         2241     0x08c1
infinity                          2242     0x08c2
nabla                             2245     0x08c5
approximate                       2248     0x08c8
similarequal                      2249     0x08c9
ifonlyif                          2253     0x08cd
implies                           2254     0x08ce
identical                         2255     0x08cf
radical                           2262     0x08d6
includedin                        2266     0x08da
includes                          2267     0x08db
intersection                      2268     0x08dc
union                             2269     0x08dd
logicaland                        2270     0x08de
logicalor                         2271     0x08df
partialderivative                 2287     0x08ef
function                          2294     0x08f6
leftarrow                         2299     0x08fb
uparrow                           2300     0x08fc
rightarrow                        2301     0x08fd
downarrow                         2302     0x08fe
blank                             2527     0x09df
soliddiamond                      2528     0x09e0
checkerboard                      2529     0x09e1
ht                                2530     0x09e2
ff                                2531     0x09e3
cr                                2532     0x09e4
lf                                2533     0x09e5
nl                                2536     0x09e8
vt                                2537     0x09e9
lowrightcorner                    2538     0x09ea
uprightcorner                     2539     0x09eb
upleftcorner                      2540     0x09ec
lowleftcorner                     2541     0x09ed
crossinglines                     2542     0x09ee
horizlinescan1                    2543     0x09ef
horizlinescan3                    2544     0x09f0
horizlinescan5                    2545     0x09f1
horizlinescan7                    2546     0x09f2
horizlinescan9                    2547     0x09f3
leftt                             2548     0x09f4
rightt                            2549     0x09f5
bott                              2550     0x09f6
topt                              2551     0x09f7
vertbar                           2552     0x09f8
emspace                           2721     0x0aa1
enspace                           2722     0x0aa2
em3space                          2723     0x0aa3
em4space                          2724     0x0aa4
digitspace                        2725     0x0aa5
punctspace                        2726     0x0aa6
thinspace                         2727     0x0aa7
hairspace                         2728     0x0aa8
emdash                            2729     0x0aa9
endash                            2730     0x0aaa
signifblank                       2732     0x0aac
ellipsis                          2734     0x0aae
doubbaselinedot                   2735     0x0aaf
onethird                          2736     0x0ab0
twothirds                         2737     0x0ab1
onefifth                          2738     0x0ab2
twofifths                         2739     0x0ab3
threefifths                       2740     0x0ab4
fourfifths                        2741     0x0ab5
onesixth                          2742     0x0ab6
fivesixths                        2743     0x0ab7
careof                            2744     0x0ab8
figdash                           2747     0x0abb
leftanglebracket                  2748     0x0abc
decimalpoint                      2749     0x0abd
rightanglebracket                 2750     0x0abe
marker                            2751     0x0abf
oneeighth                         2755     0x0ac3
threeeighths                      2756     0x0ac4
fiveeighths                       2757     0x0ac5
seveneighths                      2758     0x0ac6
trademark                         2761     0x0ac9
signaturemark                     2762     0x0aca
trademarkincircle                 2763     0x0acb
leftopentriangle                  2764     0x0acc
rightopentriangle                 2765     0x0acd
emopencircle                      2766     0x0ace
emopenrectangle                   2767     0x0acf
leftsinglequotemark               2768     0x0ad0
rightsinglequotemark              2769     0x0ad1
leftdoublequotemark               2770     0x0ad2
rightdoublequotemark              2771     0x0ad3
prescription                      2772     0x0ad4
minutes                           2774     0x0ad6
seconds                           2775     0x0ad7
latincross                        2777     0x0ad9
hexagram                          2778     0x0ada
filledrectbullet                  2779     0x0adb
filledlefttribullet               2780     0x0adc
filledrighttribullet              2781     0x0add
emfilledcircle                    2782     0x0ade
emfilledrect                      2783     0x0adf
enopencircbullet                  2784     0x0ae0
enopensquarebullet                2785     0x0ae1
openrectbullet                    2786     0x0ae2
opentribulletup                   2787     0x0ae3
opentribulletdown                 2788     0x0ae4
openstar                          2789     0x0ae5
enfilledcircbullet                2790     0x0ae6
enfilledsqbullet                  2791     0x0ae7
filledtribulletup                 2792     0x0ae8
filledtribulletdown               2793     0x0ae9
leftpointer                       2794     0x0aea
rightpointer                      2795     0x0aeb
club                              2796     0x0aec
diamond                           2797     0x0aed
heart                             2798     0x0aee
maltesecross                      2800     0x0af0
dagger                            2801     0x0af1
doubledagger                      2802     0x0af2
checkmark                         2803     0x0af3
ballotcross                       2804     0x0af4
musicalsharp                      2805     0x0af5
musicalflat                       2806     0x0af6
malesymbol                        2807     0x0af7
femalesymbol                      2808     0x0af8
telephone                         2809     0x0af9
telephonerecorder                 2810     0x0afa
phonographcopyright               2811     0x0afb
caret                             2812     0x0afc
singlelowquotemark                2813     0x0afd
doublelowquotemark                2814     0x0afe
cursor                            2815     0x0aff
leftcaret                         2979     0x0ba3
rightcaret                        2982     0x0ba6
downcaret                         2984     0x0ba8
upcaret                           2985     0x0ba9
overbar                           3008     0x0bc0
downtack                          3010     0x0bc2
upshoe                            3011     0x0bc3
downstile                         3012     0x0bc4
underbar                          3014     0x0bc6
jot                               3018     0x0bca
quad                              3020     0x0bcc
uptack                            3022     0x0bce
circle                            3023     0x0bcf
upstile                           3027     0x0bd3
downshoe                          3030     0x0bd6
rightshoe                         3032     0x0bd8
leftshoe                          3034     0x0bda
lefttack                          3036     0x0bdc
righttack                         3068     0x0bfc
hebrew_aleph                      3296     0x0ce0
hebrew_beth                       3297     0x0ce1
hebrew_gimmel                     3298     0x0ce2
hebrew_daleth                     3299     0x0ce3
hebrew_he                         3300     0x0ce4
hebrew_waw                        3301     0x0ce5
hebrew_zayin                      3302     0x0ce6
hebrew_het                        3303     0x0ce7
hebrew_teth                       3304     0x0ce8
hebrew_yod                        3305     0x0ce9
hebrew_finalkaph                  3306     0x0cea
hebrew_kaph                       3307     0x0ceb
hebrew_lamed                      3308     0x0cec
hebrew_finalmem                   3309     0x0ced
hebrew_mem                        3310     0x0cee
hebrew_finalnun                   3311     0x0cef
hebrew_nun                        3312     0x0cf0
hebrew_samekh                     3313     0x0cf1
hebrew_ayin                       3314     0x0cf2
hebrew_finalpe                    3315     0x0cf3
hebrew_pe                         3316     0x0cf4
hebrew_finalzadi                  3317     0x0cf5
hebrew_zadi                       3318     0x0cf6
hebrew_kuf                        3319     0x0cf7
hebrew_resh                       3320     0x0cf8
hebrew_shin                       3321     0x0cf9
hebrew_taf                        3322     0x0cfa
BackSpace                        65288     0xff08
Tab                              65289     0xff09
Linefeed                         65290     0xff0a
Clear                            65291     0xff0b
Return                           65293     0xff0d
Pause                            65299     0xff13
Scroll_Lock                      65300     0xff14
Sys_Req                          65301     0xff15
Escape                           65307     0xff1b
Multi_key                        65312     0xff20
Kanji                            65313     0xff21
Home                             65360     0xff50
Left                             65361     0xff51
Up                               65362     0xff52
Right                            65363     0xff53
Down                             65364     0xff54
Prior                            65365     0xff55
Next                             65366     0xff56
End                              65367     0xff57
Begin                            65368     0xff58
Win_L                            65371     0xff5b
Win_R                            65372     0xff5c
```
 
```
App                              65373     0xff5d
Select                           65376     0xff60
Print                            65377     0xff61
Execute                          65378     0xff62
Insert                           65379     0xff63
Undo                             65381     0xff65
Redo                             65382     0xff66
Menu                             65383     0xff67
Find                             65384     0xff68
Cancel                           65385     0xff69
Help                             65386     0xff6a
Break                            65387     0xff6b
Hebrew_switch                    65406     0xff7e
Num_Lock                         65407     0xff7f
KP_Space                         65408     0xff80
KP_Tab                           65417     0xff89
KP_Enter                         65421     0xff8d
KP_F1                            65425     0xff91
KP_F2                            65426     0xff92
KP_F3                            65427     0xff93
KP_F4                            65428     0xff94
KP_Multiply                      65450     0xffaa
KP_Add                           65451     0xffab
KP_Separator                     65452     0xffac
KP_Subtract                      65453     0xffad
KP_Decimal                       65454     0xffae
KP_Divide                        65455     0xffaf
KP_0                             65456     0xffb0
KP_1                             65457     0xffb1
KP_2                             65458     0xffb2
KP_3                             65459     0xffb3
KP_4                             65460     0xffb4
KP_5                             65461     0xffb5
KP_6                             65462     0xffb6
KP_7                             65463     0xffb7
KP_8                             65464     0xffb8
KP_9                             65465     0xffb9
KP_Equal                         65469     0xffbd
F1                               65470     0xffbe
F2                               65471     0xffbf
F3                               65472     0xffc0
F4                               65473     0xffc1
F5                               65474     0xffc2
F6                               65475     0xffc3
F7                               65476     0xffc4
F8                               65477     0xffc5
F9                               65478     0xffc6
F10                              65479     0xffc7
L1                               65480     0xffc8
L2                               65481     0xffc9
L3                               65482     0xffca
L4                               65483     0xffcb
L5                               65484     0xffcc
L6                               65485     0xffcd
L7                               65486     0xffce
L8                               65487     0xffcf
L9                               65488     0xffd0
L10                              65489     0xffd1
R1                               65490     0xffd2
R2                               65491     0xffd3
R3                               65492     0xffd4
R4                               65493     0xffd5
R5                               65494     0xffd6
R6                               65495     0xffd7
R7                               65496     0xffd8
R8                               65497     0xffd9
R9                               65498     0xffda
R10                              65499     0xffdb
R11                              65500     0xffdc
R12                              65501     0xffdd
F33                              65502     0xffde
R14                              65503     0xffdf
R15                              65504     0xffe0
Shift_L                          65505     0xffe1
Shift_R                          65506     0xffe2
Control_L                        65507     0xffe3
Control_R                        65508     0xffe4
Caps_Lock                        65509     0xffe5
Shift_Lock                       65510     0xffe6
Meta_L                           65511     0xffe7
Meta_R                           65512     0xffe8
Alt_L                            65513     0xffe9
Alt_R                            65514     0xffea
Super_L                          65515     0xffeb
Super_R                          65516     0xffec
Hyper_L                          65517     0xffed
Hyper_R                          65518     0xffee
Delete                           65535     0xffff
```
 See also
--------

 **[bind](bind.htm)**, **[event](event.htm)** Copyright © 1998-2000 by Scriptics Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/keysyms.htm>

listbox
=======

  
[NAME](listbox.htm#M2) listbox — Create and manipulate 'listbox' item list widgets 
[SYNOPSIS](listbox.htm#M3) 
[STANDARD OPTIONS](listbox.htm#M4)  
[-background or -bg, background, Background](options.htm#M-background) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground) 
[-exportselection, exportSelection, ExportSelection](options.htm#M-exportselection) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-justify, justify, Justify](options.htm#M-justify) 
[-relief, relief, Relief](options.htm#M-relief) 
[-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground) 
[-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth) 
[-selectforeground, selectForeground, Background](options.htm#M-selectforeground) 
[-setgrid, setGrid, SetGrid](options.htm#M-setgrid) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand) 
[-yscrollcommand, yScrollCommand, ScrollCommand](options.htm#M-yscrollcommand) 


















 
[WIDGET-SPECIFIC OPTIONS](listbox.htm#M5)  
[-activestyle, activeStyle, ActiveStyle](listbox.htm#M6) 
[-height, height, Height](listbox.htm#M7) 
[-listvariable, listVariable, Variable](listbox.htm#M8) 
[-selectmode, selectMode, SelectMode](listbox.htm#M9) 
[-state, state, State](listbox.htm#M10) 
[-width, width, Width](listbox.htm#M11) 





 
[DESCRIPTION](listbox.htm#M12) 
[INDICES](listbox.htm#M13)  
[*number*](listbox.htm#M14) 
[**active**](listbox.htm#M15) 
[**anchor**](listbox.htm#M16) 
[**end**](listbox.htm#M17) 
[**@***x***,***y*](listbox.htm#M18) 




 
[WIDGET COMMAND](listbox.htm#M19)  
[*pathName* **activate** *index*](listbox.htm#M20) 
[*pathName* **bbox** *index*](listbox.htm#M21) 
[*pathName* **cget** *option*](listbox.htm#M22) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](listbox.htm#M23) 
[*pathName* **curselection**](listbox.htm#M24) 
[*pathName* **delete** *first* ?*last*?](listbox.htm#M25) 
[*pathName* **get** *first* ?*last*?](listbox.htm#M26) 
[*pathName* **index** *index*](listbox.htm#M27) 
[*pathName* **insert** *index* ?*element element ...*?](listbox.htm#M28) 
[*pathName* **itemcget** *index option*](listbox.htm#M29) 
[*pathName* **itemconfigure** *index* ?*option*? ?*value*? ?*option value ...*?](listbox.htm#M30)  
[**-background** *color*](listbox.htm#M31) 
[**-foreground** *color*](listbox.htm#M32) 
[**-selectbackground** *color*](listbox.htm#M33) 
[**-selectforeground** *color*](listbox.htm#M34) 



 
[*pathName* **nearest** *y*](listbox.htm#M35) 
[*pathName* **scan** *option args*](listbox.htm#M36)  
[*pathName* **scan mark** *x y*](listbox.htm#M37) 
[*pathName* **scan dragto** *x y*.](listbox.htm#M38) 

 
[*pathName* **see** *index*](listbox.htm#M39) 
[*pathName* **selection** *option arg*](listbox.htm#M40)  
[*pathName* **selection anchor** *index*](listbox.htm#M41) 
[*pathName* **selection clear** *first* ?*last*?](listbox.htm#M42) 
[*pathName* **selection includes** *index*](listbox.htm#M43) 
[*pathName* **selection set** *first* ?*last*?](listbox.htm#M44) 



 
[*pathName* **size**](listbox.htm#M45) 
[*pathName* **xview** ?*args*](listbox.htm#M46)  
[*pathName* **xview**](listbox.htm#M47) 
[*pathName* **xview** *index*](listbox.htm#M48) 
[*pathName* **xview moveto** *fraction*](listbox.htm#M49) 
[*pathName* **xview scroll** *number what*](listbox.htm#M50) 



 
[*pathName* **yview** ?*args*?](listbox.htm#M51)  
[*pathName* **yview**](listbox.htm#M52) 
[*pathName* **yview** *index*](listbox.htm#M53) 
[*pathName* **yview moveto** *fraction*](listbox.htm#M54) 
[*pathName* **yview scroll** *number what*](listbox.htm#M55) 



 

















 
[DEFAULT BINDINGS](listbox.htm#M56) 
[SEE ALSO](listbox.htm#M57) 
[KEYWORDS](listbox.htm#M58) 









 Name
----

 listbox — Create and manipulate 'listbox' item list widgets Synopsis
--------

 **listbox** *pathName* ?*options*?  
 Standard options
----------------

  
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground)** 
**[-exportselection, exportSelection, ExportSelection](options.htm#M-exportselection)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-justify, justify, Justify](options.htm#M-justify)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground)** 
**[-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth)** 
**[-selectforeground, selectForeground, Background](options.htm#M-selectforeground)** 
**[-setgrid, setGrid, SetGrid](options.htm#M-setgrid)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand)** 
**[-yscrollcommand, yScrollCommand, ScrollCommand](options.htm#M-yscrollcommand)** 


















 Widget-specific options
-----------------------

  Command-Line Name: **-activestyle** Database Name: **activeStyle** Database Class: **ActiveStyle** 


Specifies the style in which to draw the active element. This must be one of **dotbox** (show a focus ring around the active element), **none** (no special indication of active element) or **underline** (underline the active element). The default is **underline** on Windows, and **dotbox** elsewhere. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies the desired height for the window, in lines. If zero or less, then the desired height for the window is made just large enough to hold all the elements in the listbox. 

Command-Line Name: **-listvariable** Database Name: **listVariable** Database Class: **[Variable](../tclcmd/variable.htm)** 


Specifies the name of a global variable. The value of the variable is a list to be displayed inside the widget; if the variable value changes then the widget will automatically update itself to reflect the new value. Attempts to assign a variable with an invalid list value to **-listvariable** will cause an error. Attempts to unset a variable in use as a **-listvariable** will fail but will not generate an error. 

Command-Line Name: **-selectmode** Database Name: **selectMode** Database Class: **SelectMode** 


Specifies one of several styles for manipulating the selection. The value of the option may be arbitrary, but the default bindings expect it to be either **single**, **browse**, **multiple**, or **extended**; the default value is **browse**. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Specifies one of two states for the listbox: **normal** or **disabled**. If the listbox is disabled then items may not be inserted or deleted, items are drawn in the **-disabledforeground** color, and selection cannot be modified and is not shown (though selection information is retained). 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies the desired width for the window in characters. If the font does not have a uniform width then the width of the character “0” is used in translating from character units to screen units. If zero or less, then the desired width for the window is made just large enough to hold all the elements in the listbox. 
 Description
-----------

 The **listbox** command creates a new window (given by the *pathName* argument) and makes it into a listbox widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the listbox such as its colors, font, text, and relief. The **listbox** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  A listbox is a widget that displays a list of strings, one per line. When first created, a new listbox has no elements. Elements may be added or deleted using widget commands described below. In addition, one or more elements may be selected as described below. If a listbox is exporting its selection (see **-exportselection** option), then it will observe the standard X11 protocols for handling the selection. Listbox selections are available as type **[STRING](../tclcmd/string.htm)**; the value of the selection will be the text of the selected elements, with newlines separating the elements. 


 It is not necessary for all the elements to be displayed in the listbox window at once; commands described below may be used to change the view in the window. Listboxes allow scrolling in both directions using the standard **-xscrollcommand** and **-yscrollcommand** options. They also support scanning, as described below. 


Indices
-------

 Many of the widget commands for listboxes take one or more indices as arguments. An index specifies a particular element of the listbox, in any of the following ways: 
 *number*
 Specifies the element as a numerical index, where 0 corresponds to the first element in the listbox. 

**active**
 Indicates the element that has the location cursor. This element will be displayed as specified by **-activestyle** when the listbox has the keyboard focus, and it is specified with the **activate** widget command. 

**anchor**
 Indicates the anchor point for the selection, which is set with the **[selection anchor](selection.htm)** widget command. 

**end**
 Indicates the end of the listbox. For most commands this refers to the last element in the listbox, but for a few commands such as **index** and **insert** it refers to the element just after the last one. 


**@***x***,***y*

 Indicates the element that covers the point in the listbox window specified by *x* and *y* (in pixel coordinates). If no element covers that point, then the closest element to that point is used. 

  In the widget command descriptions below, arguments named *index*, *first*, and *last* always contain text indices in one of the above forms. 


Widget command
--------------

 The **listbox** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for listbox widgets: 
 
*pathName* **activate** *index*

 Sets the active element to the one indicated by *index*. If *index* is outside the range of elements in the listbox then the closest element is activated. The active element is drawn as specified by **-activestyle** when the widget has the input focus, and its index may be retrieved with the index **active**. 


*pathName* **bbox** *index*

 Returns a list of four numbers describing the bounding box of the text in the element given by *index*. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the text (specified in pixels relative to the widget) and the last two elements give the width and height of the area, in pixels. If no part of the element given by *index* is visible on the screen, or if *index* refers to a non-existent element, then the result is an empty string; if the element is partially visible, the result gives the full area of the element, including any parts that are not visible. 


*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **listbox** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **listbox** command. 


*pathName* **curselection**

 Returns a list containing the numerical indices of all of the elements in the listbox that are currently selected. If there are no elements selected in the listbox then an empty string is returned. 


*pathName* **delete** *first* ?*last*?
 Deletes one or more elements of the listbox. *First* and *last* are indices specifying the first and last elements in the range to delete. If *last* is not specified it defaults to *first*, i.e. a single element is deleted. 


*pathName* **get** *first* ?*last*?
 If *last* is omitted, returns the contents of the listbox element indicated by *first*, or an empty string if *first* refers to a non-existent element. If *last* is specified, the command returns a list whose elements are all of the listbox elements between *first* and *last*, inclusive. Both *first* and *last* may have any of the standard forms for indices. 


*pathName* **index** *index*

 Returns the integer index value that corresponds to *index*. If *index* is **end** the return value is a count of the number of elements in the listbox (not the index of the last element). 


*pathName* **insert** *index* ?*element element ...*?
 Inserts zero or more new elements in the list just before the element given by *index*. If *index* is specified as **end** then the new elements are added to the end of the list. Returns an empty string. 


*pathName* **itemcget** *index option*

 Returns the current value of the item configuration option given by *option*. *Option* may have any of the values accepted by the **itemconfigure** command. 


*pathName* **itemconfigure** *index* ?*option*? ?*value*? ?*option value ...*?
 Query or modify the configuration options of an item in the listbox. If no *option* is specified, returns a list describing all of the available options for the item (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. The following options are currently supported for items: 
 
**-background** *color*

 *Color* specifies the background color to use when displaying the item. It may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. 


**-foreground** *color*

 *Color* specifies the foreground color to use when displaying the item. It may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. 


**-selectbackground** *color*

 *color* specifies the background color to use when displaying the item while it is selected. It may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. 


**-selectforeground** *color*

 *color* specifies the foreground color to use when displaying the item while it is selected. It may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. 




*pathName* **nearest** *y*

 Given a y-coordinate within the listbox window, this command returns the index of the (visible) listbox element nearest to that y-coordinate. 


*pathName* **scan** *option args*

 This command is used to implement scanning on listboxes. It has two forms, depending on *option*: 
 
*pathName* **scan mark** *x y*

 Records *x* and *y* and the current view in the listbox window; used in conjunction with later **scan dragto** commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. 


*pathName* **scan dragto** *x y*.
 This command computes the difference between its *x* and *y* arguments and the *x* and *y* arguments to the last **scan mark** command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the list at high speed through the window. The return value is an empty string. 




*pathName* **see** *index*

 Adjust the view in the listbox so that the element given by *index* is visible. If the element is already visible then the command has no effect; if the element is near one edge of the window then the listbox scrolls to bring the element into view at the edge; otherwise the listbox scrolls to center the element. 


*pathName* **selection** *option arg*

 This command is used to adjust the selection within a listbox. It has several forms, depending on *option*: 
 
*pathName* **selection anchor** *index*

 Sets the selection anchor to the element given by *index*. If *index* refers to a non-existent element, then the closest element is used. The selection anchor is the end of the selection that is fixed while dragging out a selection with the mouse. The index **anchor** may be used to refer to the anchor element. 


*pathName* **selection clear** *first* ?*last*?
 If any of the elements between *first* and *last* (inclusive) are selected, they are deselected. The selection state is not changed for elements outside this range. 


*pathName* **selection includes** *index*

 Returns 1 if the element indicated by *index* is currently selected, 0 if it is not. 


*pathName* **selection set** *first* ?*last*?
 Selects all of the elements in the range between *first* and *last*, inclusive, without affecting the selection state of elements outside that range. 




*pathName* **size**

 Returns a decimal string indicating the total number of elements in the listbox. 


*pathName* **xview** ?*args*

 This command is used to query and change the horizontal position of the information in the widget's window. It can take any of the following forms: 
 
*pathName* **xview**

 Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the listbox's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the **-xscrollcommand** option. 


*pathName* **xview** *index*

 Adjusts the view in the window so that the character position given by *index* is displayed at the left edge of the window. Character positions are defined by the width of the character **0**. 


*pathName* **xview moveto** *fraction*

 Adjusts the view in the window so that *fraction* of the total width of the listbox text is off-screen to the left. *fraction* must be a fraction between 0 and 1. 


*pathName* **xview scroll** *number what*

 This command shifts the view in the window left or right according to *number* and *what*. *Number* must be an integer. *What* must be either **units** or **pages** or an abbreviation of one of these. If *what* is **units**, the view adjusts left or right by *number* character units (the width of the **0** character) on the display; if it is **pages** then the view adjusts by *number* screenfuls. If *number* is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. 




*pathName* **yview** ?*args*?
 This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms: 
 
*pathName* **yview**

 Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the listbox element at the top of the window, relative to the listbox as a whole (0.5 means it is halfway through the listbox, for example). The second element gives the position of the listbox element just after the last one in the window, relative to the listbox as a whole. These are the same values passed to scrollbars via the **-yscrollcommand** option. 


*pathName* **yview** *index*

 Adjusts the view in the window so that the element given by *index* is displayed at the top of the window. 


*pathName* **yview moveto** *fraction*

 Adjusts the view in the window so that the element given by *fraction* appears at the top of the window. *Fraction* is a fraction between 0 and 1; 0 indicates the first element in the listbox, 0.33 indicates the element one-third the way through the listbox, and so on. 


*pathName* **yview scroll** *number what*

 This command adjusts the view in the window up or down according to *number* and *what*. *Number* must be an integer. *What* must be either **units** or **pages**. If *what* is **units**, the view adjusts up or down by *number* lines; if it is **pages** then the view adjusts by *number* screenfuls. If *number* is negative then earlier elements become visible; if it is positive then later elements become visible. 



 Default bindings
----------------

 Tk automatically creates class bindings for listboxes that give them Motif-like behavior. Much of the behavior of a listbox is determined by its **-selectmode** option, which selects one of four ways of dealing with the selection.  If the selection mode is **single** or **browse**, at most one element can be selected in the listbox at once. In both modes, clicking button 1 on an element selects it and deselects any other selected item. In **browse** mode it is also possible to drag the selection with button 1. On button 1, the listbox will also take focus if it has a **normal** state. 


 If the selection mode is **multiple** or **extended**, any number of elements may be selected at once, including discontiguous ranges. In **multiple** mode, clicking button 1 on an element toggles its selection state without affecting any other elements. In **extended** mode, pressing button 1 on an element selects it, deselects everything else, and sets the anchor to the element under the mouse; dragging the mouse with button 1 down extends the selection to include all the elements between the anchor and the element under the mouse, inclusive. 


 Most people will probably want to use **browse** mode for single selections and **extended** mode for multiple selections; the other modes appear to be useful only in special situations. 


 Any time the set of selected item(s) in the listbox is updated by the user through the keyboard or mouse, the virtual event **<<ListboxSelect>>** will be generated. This virtual event will not be generated when adjusting the selection with the *pathName* **[selection](selection.htm)** command. It is easiest to bind to this event to be made aware of any user changes to listbox selection. 


 In addition to the above behavior, the following additional behavior is defined by the default bindings: 


1. In **extended** mode, the selected range can be adjusted by pressing button 1 with the Shift key down: this modifies the selection to consist of the elements between the anchor and the element under the mouse, inclusive. The un-anchored end of this new selection can also be dragged with the button down.
2. In **extended** mode, pressing button 1 with the Control key down starts a toggle operation: the anchor is set to the element under the mouse, and its selection state is reversed. The selection state of other elements is not changed. If the mouse is dragged with button 1 down, then the selection state of all elements between the anchor and the element under the mouse is set to match that of the anchor element; the selection state of all other elements remains what it was before the toggle operation began.
3. If the mouse leaves the listbox window with button 1 down, the window scrolls away from the mouse, making information visible that used to be off-screen on the side of the mouse. The scrolling continues until the mouse re-enters the window, the button is released, or the end of the listbox is reached.
4. Mouse button 2 may be used for scanning. If it is pressed and dragged over the listbox, the contents of the listbox drag at high speed in the direction the mouse moves.
5. If the Up or Down key is pressed, the location cursor (active element) moves up or down one element. If the selection mode is **browse** or **extended** then the new active element is also selected and all other elements are deselected. In **extended** mode the new active element becomes the selection anchor.
6. In **extended** mode, Shift-Up and Shift-Down move the location cursor (active element) up or down one element and also extend the selection to that element in a fashion similar to dragging with mouse button 1.
7. The Left and Right keys scroll the listbox view left and right by the width of the character **0**. Control-Left and Control-Right scroll the listbox view left and right by the width of the window. Control-Prior and Control-Next also scroll left and right by the width of the window.
8. The Prior and Next keys scroll the listbox view up and down by one page (the height of the window).
9. The Home and End keys scroll the listbox horizontally to the left and right edges, respectively.
10. Control-Home sets the location cursor to the first element in the listbox, selects that element, and deselects everything else in the listbox.
11. Control-End sets the location cursor to the last element in the listbox, selects that element, and deselects everything else in the listbox.
12. In **extended** mode, Control-Shift-Home extends the selection to the first element in the listbox and Control-Shift-End extends the selection to the last element.
13. In **multiple** mode, Control-Shift-Home moves the location cursor to the first element in the listbox and Control-Shift-End moves the location cursor to the last element.
14. The space and Select keys make a selection at the location cursor (active element) just as if mouse button 1 had been pressed over this element.
15. In **extended** mode, Control-Shift-space and Shift-Select extend the selection to the active element just as if button 1 had been pressed with the Shift key down.
16. In **extended** mode, the Escape key cancels the most recent selection and restores all the elements in the selected range to their previous selection state.
17. Control-slash selects everything in the widget, except in **single** and **browse** modes, in which case it selects the active element and deselects everything else.
18. Control-backslash deselects everything in the widget, except in **browse** mode where it has no effect.
19. The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection.

  The behavior of listboxes can be changed by defining new bindings for individual widgets or by redefining the class bindings. 


See also
--------

 **[ttk::treeview](ttk_treeview.htm)** Copyright © 1990 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/listbox.htm>

checkbutton
===========

  
[NAME](checkbutton.htm#M2) checkbutton — Create and manipulate 'checkbutton' boolean selection widgets 
[SYNOPSIS](checkbutton.htm#M3) 
[STANDARD OPTIONS](checkbutton.htm#M4)  
[-activebackground, activeBackground, Foreground](options.htm#M-activebackground) 
[-activeforeground, activeForeground, Background](options.htm#M-activeforeground) 
[-anchor, anchor, Anchor](options.htm#M-anchor) 
[-background or -bg, background, Background](options.htm#M-background) 
[-bitmap, bitmap, Bitmap](options.htm#M-bitmap) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-compound, compound, Compound](options.htm#M-compound) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-image, image, Image](options.htm#M-image) 
[-justify, justify, Justify](options.htm#M-justify) 
[-padx, padX, Pad](options.htm#M-padx) 
[-pady, padY, Pad](options.htm#M-pady) 
[-relief, relief, Relief](options.htm#M-relief) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-text, text, Text](options.htm#M-text) 
[-textvariable, textVariable, Variable](options.htm#M-textvariable) 
[-underline, underline, Underline](options.htm#M-underline) 
[-wraplength, wrapLength, WrapLength](options.htm#M-wraplength) 























 
[WIDGET-SPECIFIC OPTIONS](checkbutton.htm#M5)  
[-command, command, Command](checkbutton.htm#M6) 
[-height, height, Height](checkbutton.htm#M7) 
[-indicatoron, indicatorOn, IndicatorOn](checkbutton.htm#M8) 
[-offrelief, offRelief, OffRelief](checkbutton.htm#M9) 
[-offvalue, offValue, Value](checkbutton.htm#M10) 
[-onvalue, onValue, Value](checkbutton.htm#M11) 
[-overrelief, overRelief, OverRelief](checkbutton.htm#M12) 
[-selectcolor, selectColor, Background](checkbutton.htm#M13) 
[-selectimage, selectImage, SelectImage](checkbutton.htm#M14) 
[-state, state, State](checkbutton.htm#M15) 
[-tristateimage, tristateImage, TristateImage](checkbutton.htm#M16) 
[-tristatevalue, tristateValue, Value](checkbutton.htm#M17) 
[-variable, variable, Variable](checkbutton.htm#M18) 
[-width, width, Width](checkbutton.htm#M19) 













 
[DESCRIPTION](checkbutton.htm#M20) 
[WIDGET COMMAND](checkbutton.htm#M21)  
[*pathName* **cget** *option*](checkbutton.htm#M22) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](checkbutton.htm#M23) 
[*pathName* **deselect**](checkbutton.htm#M24) 
[*pathName* **flash**](checkbutton.htm#M25) 
[*pathName* **invoke**](checkbutton.htm#M26) 
[*pathName* **select**](checkbutton.htm#M27) 
[*pathName* **toggle**](checkbutton.htm#M28) 






 
[BINDINGS](checkbutton.htm#M29) 
[EXAMPLE](checkbutton.htm#M30) 
[SEE ALSO](checkbutton.htm#M31) 
[KEYWORDS](checkbutton.htm#M32) 









 Name
----

 checkbutton — Create and manipulate 'checkbutton' boolean selection widgets Synopsis
--------

 **checkbutton** *pathName* ?*options*?  
 Standard options
----------------

  
**[-activebackground, activeBackground, Foreground](options.htm#M-activebackground)** 
**[-activeforeground, activeForeground, Background](options.htm#M-activeforeground)** 
**[-anchor, anchor, Anchor](options.htm#M-anchor)** 
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-bitmap, bitmap, Bitmap](options.htm#M-bitmap)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-compound, compound, Compound](options.htm#M-compound)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-image, image, Image](options.htm#M-image)** 
**[-justify, justify, Justify](options.htm#M-justify)** 
**[-padx, padX, Pad](options.htm#M-padx)** 
**[-pady, padY, Pad](options.htm#M-pady)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-text, text, Text](options.htm#M-text)** 
**[-textvariable, textVariable, Variable](options.htm#M-textvariable)** 
**[-underline, underline, Underline](options.htm#M-underline)** 
**[-wraplength, wrapLength, WrapLength](options.htm#M-wraplength)** 























 Widget-specific options
-----------------------

  Command-Line Name: **-command** Database Name: **command** Database Class: **Command** 


Specifies a Tcl command to associate with the button. This command is typically invoked when mouse button 1 is released over the button window. The button's global variable (**-variable** option) will be updated before the command is invoked. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies a desired height for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**); for text it is in lines of text. If this option is not specified, the button's desired height is computed from the size of the image or bitmap or text being displayed in it. 

Command-Line Name: **-indicatoron** Database Name: **indicatorOn** Database Class: **IndicatorOn** 


Specifies whether or not the indicator should be drawn. Must be a proper boolean value. If false, the **-relief** option is ignored and the widget's relief is always sunken if the widget is selected and raised otherwise. 

Command-Line Name: **-offrelief** Database Name: **offRelief** Database Class: **OffRelief** 


Specifies the relief for the checkbutton when the indicator is not drawn and the checkbutton is off. The default value is “raised”. By setting this option to “flat” and setting **-indicatoron** to false and **-overrelief** to “raised”, the effect is achieved of having a flat button that raises on mouse-over and which is depressed when activated. This is the behavior typically exhibited by the Bold, Italic, and Underline checkbuttons on the toolbar of a word-processor, for example. 

Command-Line Name: **-offvalue** Database Name: **offValue** Database Class: **Value** 


Specifies value to store in the button's associated variable whenever this button is deselected. Defaults to “0”. 

Command-Line Name: **-onvalue** Database Name: **onValue** Database Class: **Value** 


Specifies value to store in the button's associated variable whenever this button is selected. Defaults to “1”. 

Command-Line Name: **-overrelief** Database Name: **overRelief** Database Class: **OverRelief** 


Specifies an alternative relief for the checkbutton, to be used when the mouse cursor is over the widget. This option can be used to make toolbar buttons, by configuring **-relief flat -overrelief raised**. If the value of this option is the empty string, then no alternative relief is used when the mouse cursor is over the checkbutton. The empty string is the default value. 

Command-Line Name: **-selectcolor** Database Name: **selectColor** Database Class: **Background** 


Specifies a background color to use when the button is selected. If **indicatorOn** is true then the color is used as the background for the indicator regardless of the select state. If **indicatorOn** is false, this color is used as the background for the entire widget, in place of **background** or **activeBackground**, whenever the widget is selected. If specified as an empty string then no special color is used for displaying when the widget is selected. 

Command-Line Name: **-selectimage** Database Name: **selectImage** Database Class: **SelectImage** 


Specifies an image to display (in place of the **-image** option) when the checkbutton is selected. This option is ignored unless the **-image** option has been specified. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Specifies one of three states for the checkbutton: **normal**, **active**, or **disabled**. In normal state the checkbutton is displayed using the **-foreground** and **-background** options. The active state is typically used when the pointer is over the checkbutton. In active state the checkbutton is displayed using the **-activeforeground** and **-activebackground** options. Disabled state means that the checkbutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the **-disabledforeground** and **-background** options determine how the checkbutton is displayed. 

Command-Line Name: **-tristateimage** Database Name: **tristateImage** Database Class: **TristateImage** 


Specifies an image to display (in place of the **-image** option) when the checkbutton is in tri-state mode. This option is ignored unless the **-image** option has been specified. 

Command-Line Name: **-tristatevalue** Database Name: **tristateValue** Database Class: **Value** 


Specifies the value that causes the checkbutton to display the multi-value selection, also known as the tri-state mode. Defaults to “”. 

Command-Line Name: **-variable** Database Name: **[variable](../tclcmd/variable.htm)** Database Class: **[Variable](../tclcmd/variable.htm)** 


Specifies the name of a global variable to set to indicate whether or not this button is selected. Defaults to the name of the button within its parent (i.e. the last element of the button window's path name). 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies a desired width for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**); for text it is in characters. If this option is not specified, the button's desired width is computed from the size of the image or bitmap or text being displayed in it. 
 Description
-----------

 The **checkbutton** command creates a new window (given by the *pathName* argument) and makes it into a checkbutton widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the checkbutton such as its colors, font, text, and initial relief. The **checkbutton** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  A checkbutton is a widget that displays a textual string, bitmap or image and a square called an *indicator*. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the **-wraplength** option) and one of the characters may optionally be underlined using the **-underline** option. A checkbutton has all of the behavior of a simple button, including the following: it can display itself in either of three different ways, according to the **-state** option; it can be made to appear raised, sunken, or flat; it can be made to flash; and it invokes a Tcl command whenever mouse button 1 is clicked over the checkbutton. 


 In addition, checkbuttons can be *selected*. If a checkbutton is selected then the indicator is normally drawn with a selected appearance, and a Tcl variable associated with the checkbutton is set to a particular value (normally 1). The indicator is drawn with a check mark inside. If the checkbutton is not selected, then the indicator is drawn with a deselected appearance, and the associated variable is set to a different value (typically 0). The indicator is drawn without a check mark inside. In the special case where the variable (if specified) has a value that matches the tristatevalue, the indicator is drawn with a tri-state appearance and is in the tri-state mode indicating mixed or multiple values. (This is used when the check box represents the state of multiple items.) The indicator is drawn in a platform dependent manner. Under Unix and Windows, the background interior of the box is “grayed”. Under Mac, the indicator is drawn with a dash mark inside. By default, the name of the variable associated with a checkbutton is the same as the *name* used to create the checkbutton. The variable name, and the “on”, “off” and “tristate” values stored in it, may be modified with options on the command line or in the option database. Configuration options may also be used to modify the way the indicator is displayed (or whether it is displayed at all). By default a checkbutton is configured to select and deselect itself on alternate button clicks. In addition, each checkbutton monitors its associated variable and automatically selects and deselects itself when the variables value changes to and from the button's “on”, “off” and “tristate” values. 


Widget command
--------------

 The **checkbutton** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for checkbutton widgets: 
 
*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **checkbutton** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **checkbutton** command. 


*pathName* **deselect**

 Deselects the checkbutton and sets the associated variable to its “off” value. 


*pathName* **flash**

 Flashes the checkbutton. This is accomplished by redisplaying the checkbutton several times, alternating between active and normal colors. At the end of the flash the checkbutton is left in the same normal/active state as when the command was invoked. This command is ignored if the checkbutton's state is **disabled**. 


*pathName* **invoke**

 Does just what would have happened if the user invoked the checkbutton with the mouse: toggle the selection state of the button and invoke the Tcl command associated with the checkbutton, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the checkbutton. This command is ignored if the checkbutton's state is **disabled**. 


*pathName* **select**

 Selects the checkbutton and sets the associated variable to its “on” value. 


*pathName* **toggle**

 Toggles the selection state of the button, redisplaying it and modifying its associated variable to reflect the new state. 

 Bindings
--------

 Tk automatically creates class bindings for checkbuttons that give them the following default behavior: 
1. On Unix systems, a checkbutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves the checkbutton. On Mac and Windows systems, when mouse button 1 is pressed over a checkbutton, the button activates whenever the mouse pointer is inside the button, and deactivates whenever the mouse pointer leaves the button.
2. When mouse button 1 is pressed over a checkbutton, it is invoked (its selection state toggles and the command associated with the button is invoked, if there is one).
3. When a checkbutton has the input focus, the space key causes the checkbutton to be invoked. Under Windows, there are additional key bindings; plus (**+**) and equal (**=**) select the button, and minus (**-**) deselects the button.

  If the checkbutton's state is **disabled** then none of the above actions occur: the checkbutton is completely non-responsive. 


 The behavior of checkbuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. 


Example
-------

 This example shows a group of uncoupled checkbuttons. 

```
labelframe .lbl -text "Steps:"
**checkbutton** .c1 -text Lights  -variable lights
**checkbutton** .c2 -text Cameras -variable cameras
**checkbutton** .c3 -text Action! -variable action
pack .c1 .c2 .c3 -in .lbl
pack .lbl
```
 See also
--------

 **[button](button.htm)**, **[options](options.htm)**, **[radiobutton](radiobutton.htm)**, **[ttk::checkbutton](ttk_checkbutton.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/checkbutton.htm>

menubutton
==========

  
[NAME](menubutton.htm#M2) menubutton — Create and manipulate 'menubutton' pop-up menu indicator widgets 
[SYNOPSIS](menubutton.htm#M3) 
[STANDARD OPTIONS](menubutton.htm#M4)  
[-activebackground, activeBackground, Foreground](options.htm#M-activebackground) 
[-activeforeground, activeForeground, Background](options.htm#M-activeforeground) 
[-anchor, anchor, Anchor](options.htm#M-anchor) 
[-background or -bg, background, Background](options.htm#M-background) 
[-bitmap, bitmap, Bitmap](options.htm#M-bitmap) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-compound, compound, Compound](options.htm#M-compound) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-image, image, Image](options.htm#M-image) 
[-justify, justify, Justify](options.htm#M-justify) 
[-padx, padX, Pad](options.htm#M-padx) 
[-pady, padY, Pad](options.htm#M-pady) 
[-relief, relief, Relief](options.htm#M-relief) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-text, text, Text](options.htm#M-text) 
[-textvariable, textVariable, Variable](options.htm#M-textvariable) 
[-underline, underline, Underline](options.htm#M-underline) 
[-wraplength, wrapLength, WrapLength](options.htm#M-wraplength) 























 
[WIDGET-SPECIFIC OPTIONS](menubutton.htm#M5)  
[-direction, direction, Height](menubutton.htm#M6) 
[-height, height, Height](menubutton.htm#M7) 
[-indicatoron, indicatorOn, IndicatorOn](menubutton.htm#M8) 
[-menu, menu, MenuName](menubutton.htm#M9) 
[-state, state, State](menubutton.htm#M10) 
[-width, width, Width](menubutton.htm#M11) 





 
[INTRODUCTION](menubutton.htm#M12) 
[WIDGET COMMAND](menubutton.htm#M13)  
[*pathName* **cget** *option*](menubutton.htm#M14) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](menubutton.htm#M15) 

 
[DEFAULT BINDINGS](menubutton.htm#M16) 
[SEE ALSO](menubutton.htm#M17) 
[KEYWORDS](menubutton.htm#M18) 








 Name
----

 menubutton — Create and manipulate 'menubutton' pop-up menu indicator widgets Synopsis
--------

 **menubutton** *pathName* ?*options*?  
 Standard options
----------------

  
**[-activebackground, activeBackground, Foreground](options.htm#M-activebackground)** 
**[-activeforeground, activeForeground, Background](options.htm#M-activeforeground)** 
**[-anchor, anchor, Anchor](options.htm#M-anchor)** 
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-bitmap, bitmap, Bitmap](options.htm#M-bitmap)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-compound, compound, Compound](options.htm#M-compound)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-image, image, Image](options.htm#M-image)** 
**[-justify, justify, Justify](options.htm#M-justify)** 
**[-padx, padX, Pad](options.htm#M-padx)** 
**[-pady, padY, Pad](options.htm#M-pady)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-text, text, Text](options.htm#M-text)** 
**[-textvariable, textVariable, Variable](options.htm#M-textvariable)** 
**[-underline, underline, Underline](options.htm#M-underline)** 
**[-wraplength, wrapLength, WrapLength](options.htm#M-wraplength)** 























 Widget-specific options
-----------------------

  Command-Line Name: **-direction** Database Name: **direction** Database Class: **Height** 


Specifies where the menu is going to be popup up. **above** tries to pop the menu above the menubutton. **below** tries to pop the menu below the menubutton. **left** tries to pop the menu to the left of the menubutton. **right** tries to pop the menu to the right of the menu button. **[flush](../tclcmd/flush.htm)** pops the menu directly over the menubutton. In the case of **above** or **below**, the direction will be reversed if the menu would show offscreen. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies a desired height for the menubutton. If an image or bitmap is being displayed in the menubutton then the value is in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**); for text it is in lines of text. If this option is not specified, the menubutton's desired height is computed from the size of the image or bitmap or text being displayed in it. 

Command-Line Name: **-indicatoron** Database Name: **indicatorOn** Database Class: **IndicatorOn** 


The value must be a proper boolean value. If it is true then a small indicator rectangle will be displayed on the right side of the menubutton and the default menu bindings will treat this as an option menubutton. If false then no indicator will be displayed. 

Command-Line Name: **-menu** Database Name: **[menu](menu.htm)** Database Class: **MenuName** 


Specifies the path name of the menu associated with this menubutton. The menu must be a child of the menubutton. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Specifies one of three states for the menubutton: **normal**, **active**, or **disabled**. In normal state the menubutton is displayed using the **foreground** and **background** options. The active state is typically used when the pointer is over the menubutton. In active state the menubutton is displayed using the **-activeforeground** and **-activebackground** options. Disabled state means that the menubutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the **-disabledforeground** and **-background** options determine how the button is displayed. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies a desired width for the menubutton. If an image or bitmap is being displayed in the menubutton then the value is in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**); for text it is in characters. If this option is not specified, the menubutton's desired width is computed from the size of the image or bitmap or text being displayed in it. 
 Introduction
------------

 The **menubutton** command creates a new window (given by the *pathName* argument) and makes it into a menubutton widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the menubutton such as its colors, font, text, and initial relief. The **menubutton** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  A menubutton is a widget that displays a textual string, bitmap, or image and is associated with a menu widget. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the **-wraplength** option) and one of the characters may optionally be underlined using the **-underline** option. In normal usage, pressing mouse button 1 over the menubutton causes the associated menu to be posted just underneath the menubutton. If the mouse is moved over the menu before releasing the mouse button, the button release causes the underlying menu entry to be invoked. When the button is released, the menu is unposted. 


 Menubuttons are used to construct a **tk\_optionMenu**, which is the preferred mechanism for allowing a user to select one item from a list on Mac OS X. 


 Menubuttons were also typically organized into groups called menu bars that allow scanning: if the mouse button is pressed over one menubutton (causing it to post its menu) and the mouse is moved over another menubutton in the same menu bar without releasing the mouse button, then the menu of the first menubutton is unposted and the menu of the new menubutton is posted instead. *This use is deprecated* in favor of setting a **[menu](menu.htm)** directly as a menubar; see the **[toplevel](toplevel.htm)**'s **-menu** option for how to do that. 


 There are several interactions between menubuttons and menus; see the **[menu](menu.htm)** manual entry for information on various menu configurations, such as pulldown menus and option menus. 


Widget command
--------------

 The **menubutton** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for menubutton widgets: 
 
*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **menubutton** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **menubutton** command. 

 Default bindings
----------------

 Tk automatically creates class bindings for menubuttons that give them the following default behavior: 
1. A menubutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves it.
2. Pressing mouse button 1 over a menubutton posts the menubutton: its relief changes to raised and its associated menu is posted under the menubutton. If the mouse is dragged down into the menu with the button still down, and if the mouse button is then released over an entry in the menu, the menubutton is unposted and the menu entry is invoked.
3. If button 1 is pressed over a menubutton and then released over that menubutton, the menubutton stays posted: you can still move the mouse over the menu and click button 1 on an entry to invoke it. Once a menu entry has been invoked, the menubutton unposts itself.
4. If button 1 is pressed over a menubutton and then dragged over some other menubutton, the original menubutton unposts itself and the new menubutton posts.
5. If button 1 is pressed over a menubutton and released outside any menubutton or menu, the menubutton unposts without invoking any menu entry.
6. When a menubutton is posted, its associated menu claims the input focus to allow keyboard traversal of the menu and its submenus. See the **[menu](menu.htm)** manual entry for details on these bindings.
7. If the **-underline** option has been specified for a menubutton then keyboard traversal may be used to post the menubutton: Alt+*x*, where *x* is the underlined character (or its lower-case or upper-case equivalent), may be typed in any window under the menubutton's toplevel to post the menubutton.
8. The F10 key may be typed in any window to post the first menubutton under its toplevel window that is not disabled.
9. If a menubutton has the input focus, the space and return keys post the menubutton.

  If the menubutton's state is **disabled** then none of the above actions occur: the menubutton is completely non-responsive. 


 The behavior of menubuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. 


See also
--------

 **[ttk::menubutton](ttk_menubutton.htm)**, **[menu](menu.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/menubutton.htm>

ttk\_spinbox
============

  
[NAME](ttk_spinbox.htm#M2) ttk::spinbox — Selecting text field widget 
[SYNOPSIS](ttk_spinbox.htm#M3) 
[DESCRIPTION](ttk_spinbox.htm#M4) 
[STANDARD OPTIONS](ttk_spinbox.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 
[-validate, validate, Validate](ttk_entry.htm#M-validate) 
[-validatecommand, validateCommand, ValidateCommand](ttk_entry.htm#M-validatecommand) 
[-xscrollcommand, xScrollCommand, ScrollCommand](ttk_widget.htm#M-xscrollcommand) 






 
[WIDGET-SPECIFIC OPTIONS](ttk_spinbox.htm#M6)  
[-from, from, From](ttk_spinbox.htm#M7) 
[-to, to, To](ttk_spinbox.htm#M8) 
[-increment, increment, Increment](ttk_spinbox.htm#M9) 
[-values, values, Values](ttk_spinbox.htm#M10) 
[-wrap, wrap, Wrap](ttk_spinbox.htm#M11) 
[-format, format, Format](ttk_spinbox.htm#M12) 
[-command, command, Command](ttk_spinbox.htm#M13) 






 
[INDICES](ttk_spinbox.htm#M14) 
[VALIDATION](ttk_spinbox.htm#M15) 
[WIDGET COMMAND](ttk_spinbox.htm#M16)  
[*pathName* **current** *index*](ttk_spinbox.htm#M17) 
[*pathName* **get**](ttk_spinbox.htm#M18) 
[*pathName* **set** *value*](ttk_spinbox.htm#M19) 


 
[VIRTUAL EVENTS](ttk_spinbox.htm#M20) 
[SEE ALSO](ttk_spinbox.htm#M21) 
[KEYWORDS](ttk_spinbox.htm#M22) 










 Name
----

 ttk::spinbox — Selecting text field widget Synopsis
--------

 **ttk::spinbox** *pathName* ?*options*?  
 Description
-----------

 A **ttk::spinbox** widget is a **[ttk::entry](ttk_entry.htm)** widget with built-in up and down buttons that are used to either modify a numeric value or to select among a set of values. The widget implements all the features of the **[ttk::entry](ttk_entry.htm)** widget including support of the **-textvariable** option to link the value displayed by the widget to a Tcl variable. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 
**[-validate, validate, Validate](ttk_entry.htm#M-validate)** 
**[-validatecommand, validateCommand, ValidateCommand](ttk_entry.htm#M-validatecommand)** 
**[-xscrollcommand, xScrollCommand, ScrollCommand](ttk_widget.htm#M-xscrollcommand)** 






 Widget-specific options
-----------------------

  Command-Line Name: **-from** Database Name: **from** Database Class: **From** 


A floating-point value specifying the lowest value for the spinbox. This is used in conjunction with **-to** and **-increment** to set a numerical range. 

Command-Line Name: **-to** Database Name: **to** Database Class: **To** 


A floating-point value specifying the highest permissible value for the widget. See also **-from** and **-increment**. range. 

Command-Line Name: **-increment** Database Name: **increment** Database Class: **Increment** 


A floating-point value specifying the change in value to be applied each time one of the widget spin buttons is pressed. The up button applies a positive increment, the down button applies a negative increment. 

Command-Line Name: **-values** Database Name: **values** Database Class: **Values** 


This must be a Tcl list of values. If this option is set then this will override any range set using the **-from**, **-to** and **-increment** options. The widget will instead use the values specified beginning with the first value. 

Command-Line Name: **-wrap** Database Name: **wrap** Database Class: **Wrap** 


Must be a proper boolean value. If on, the spinbox will wrap around the values of data in the widget. 

Command-Line Name: **-format** Database Name: **format** Database Class: **Format** 


Specifies an alternate format to use when setting the string value when using the **-from** and **-to** range. This must be a format specifier of the form **%<pad>.<pad>f**, as it will format a floating-point number. 

Command-Line Name: **-command** Database Name: **command** Database Class: **Command** 


Specifies a Tcl command to be invoked whenever a spinbutton is invoked. 
 Indices
-------

 See the **[ttk::entry](ttk_entry.htm)** manual for information about indexing characters. Validation
----------

 See the **[ttk::entry](ttk_entry.htm)** manual for information about using the **-validate** and **-validatecommand** options. Widget command
--------------

 The following subcommands are possible for spinbox widgets in addition to the commands described for the **[ttk::entry](ttk_entry.htm)** widget: 
 
*pathName* **current** *index*


*pathName* **get**

 Returns the spinbox's current value. 


*pathName* **set** *value*

 Set the spinbox string to *value*. If a **-format** option has been configured then this format will be applied. If formatting fails or is not set or the **-values** option has been used then the value is set directly. 

 Virtual events
--------------

 The spinbox widget generates a **<<Increment>>** virtual event when the user presses <Up>, and a **<<Decrement>>** virtual event when the user presses <Down>. See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[ttk::entry](ttk_entry.htm)**, **[spinbox](spinbox.htm)** Copyright © 2008 Pat Thoyts 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_spinbox.htm>

console
=======

  
[NAME](console.htm#M2) console — Control the console on systems without a real console 
[SYNOPSIS](console.htm#M3) 
[DESCRIPTION](console.htm#M4)  
[**console eval** *script*](console.htm#M5) 
[**console hide**](console.htm#M6) 
[**console show**](console.htm#M7) 
[**console title** ?*string*?](console.htm#M8) 



 
[ACCESS TO THE MAIN INTERPRETER](console.htm#M9)  
[**consoleinterp eval** *script*](console.htm#M10) 
[**consoleinterp record** *script*](console.htm#M11) 

 
[ADDITIONAL TRAP CALLS](console.htm#M12) 
[DEFAULT BINDINGS](console.htm#M13) 
[EXAMPLE](console.htm#M14) 
[SEE ALSO](console.htm#M15) 
[KEYWORDS](console.htm#M16) 








 Name
----

 console — Control the console on systems without a real console Synopsis
--------

 **console** *subcommand* ?*arg ...*?  
 Description
-----------

 The console window is a replacement for a real console to allow input and output on the standard I/O channels on platforms that do not have a real console. It is implemented as a separate interpreter with the Tk toolkit loaded, and control over this interpreter is given through the **console** command. The behaviour of the console window is defined mainly through the contents of the *console.tcl* file in the Tk library. Except for TkAqua, this command is not available when Tk is loaded into a tclsh interpreter with “**package require Tk**”, as a conventional terminal is expected to be present in that case. In TkAqua, this command is only available when stdin is **/dev/null** (as is the case e.g. when the application embedding Tk is started from the Mac OS X Finder). 

 
**console eval** *script*

 Evaluate the *script* argument as a Tcl script in the console interpreter. The normal interpreter is accessed through the **consoleinterp** command in the console interpreter. 

**console hide**
 Hide the console window from view. Precisely equivalent to withdrawing the **.** window in the console interpreter. 

**console show**
 Display the console window. Precisely equivalent to deiconifying the **.** window in the console interpreter. 


**console title** ?*string*?
 Query or modify the title of the console window. If *string* is not specified, queries the title of the console window, and sets the title of the console window to *string* otherwise. Precisely equivalent to using the **[wm title](wm.htm)** command in the console interpreter. 

 Access to the main interpreter
------------------------------

 The **consoleinterp** command in the console interpreter allows scripts to be evaluated in the main interpreter. It supports two subcommands: **eval** and **record**. 

 
**consoleinterp eval** *script*

 Evaluates *script* as a Tcl script at the global level in the main interpreter. 


**consoleinterp record** *script*

 Records and evaluates *script* as a Tcl script at the global level in the main interpreter as if *script* had been typed in at the console. 

 Additional trap calls
---------------------

 There are several additional commands in the console interpreter that are called in response to activity in the main interpreter. *These are documented here for completeness only; they form part of the internal implementation of the console and are likely to change or be modified without warning.*  Output to the console from the main interpreter via the stdout and stderr channels is handled by invoking the **tk::ConsoleOutput** command in the console interpreter with two arguments. The first argument is the name of the channel being written to, and the second argument is the string being written to the channel (after encoding and end-of-line translation processing has been performed.) 


 When the **.** window of the main interpreter is destroyed, the **tk::ConsoleExit** command in the console interpreter is called (assuming the console interpreter has not already been deleted itself, that is.) 


Default bindings
----------------

 The default script creates a console window (implemented using a text widget) that has the following behaviour: 
1. Pressing the tab key inserts a TAB character (as defined by the Tcl \t escape.)
2. Pressing the return key causes the current line (if complete by the rules of **[info complete](../tclcmd/info.htm)**) to be passed to the main interpreter for evaluation.
3. Pressing the delete key deletes the selected text (if any text is selected) or the character to the right of the cursor (if not at the end of the line.)
4. Pressing the backspace key deletes the selected text (if any text is selected) or the character to the left of the cursor (of not at the start of the line.)
5. Pressing either Control+A or the home key causes the cursor to go to the start of the line (but after the prompt, if a prompt is present on the line.)
6. Pressing either Control+E or the end key causes the cursor to go to the end of the line.
7. Pressing either Control+P or the up key causes the previous entry in the command history to be selected.
8. Pressing either Control+N or the down key causes the next entry in the command history to be selected.
9. Pressing either Control+B or the left key causes the cursor to move one character backward as long as the cursor is not at the prompt.
10. Pressing either Control+F or the right key causes the cursor to move one character forward.
11. Pressing F9 rebuilds the console window by destroying all its children and reloading the Tcl script that defined the console's behaviour.

  Most other behaviour is the same as a conventional text widget except for the way that the *<<Cut>>* event is handled identically to the *<<Copy>>* event. 


Example
-------

 Not all platforms have the **console** command, so debugging code often has the following code fragment in it so output produced by **[puts](../tclcmd/puts.htm)** can be seen while during development: 
```
catch {**console show**}
```
 See also
--------

 **[destroy](destroy.htm)**, **[fconfigure](../tclcmd/fconfigure.htm)**, **[history](../tclcmd/history.htm)**, **[interp](../tclcmd/interp.htm)**, **[puts](../tclcmd/puts.htm)**, **[text](text.htm)**, **[wm](wm.htm)** Copyright © 2001 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/console.htm>

message
=======

  
[NAME](message.htm#M2) message — Create and manipulate 'message' non-interactive text widgets 
[SYNOPSIS](message.htm#M3) 
[STANDARD OPTIONS](message.htm#M4)  
[-anchor, anchor, Anchor](options.htm#M-anchor) 
[-background or -bg, background, Background](options.htm#M-background) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-padx, padX, Pad](options.htm#M-padx) 
[-pady, padY, Pad](options.htm#M-pady) 
[-relief, relief, Relief](options.htm#M-relief) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-text, text, Text](options.htm#M-text) 
[-textvariable, textVariable, Variable](options.htm#M-textvariable) 














 
[WIDGET-SPECIFIC OPTIONS](message.htm#M5)  
[-aspect, aspect, Aspect](message.htm#M6) 
[-justify, justify, Justify](message.htm#M7) 
[-width, width, Width](message.htm#M8) 


 
[DESCRIPTION](message.htm#M9) 
[WIDGET COMMAND](message.htm#M10)  
[*pathName* **cget** *option*](message.htm#M11) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](message.htm#M12) 

 
[DEFAULT BINDINGS](message.htm#M13) 
[BUGS](message.htm#M14) 
[SEE ALSO](message.htm#M15) 
[KEYWORDS](message.htm#M16) 









 Name
----

 message — Create and manipulate 'message' non-interactive text widgets Synopsis
--------

 **message** *pathName* ?*options*?  
 Standard options
----------------

  
**[-anchor, anchor, Anchor](options.htm#M-anchor)** 
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-padx, padX, Pad](options.htm#M-padx)** 
**[-pady, padY, Pad](options.htm#M-pady)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-text, text, Text](options.htm#M-text)** 
**[-textvariable, textVariable, Variable](options.htm#M-textvariable)** 














 Widget-specific options
-----------------------

  Command-Line Name: **-aspect** Database Name: **aspect** Database Class: **Aspect** 


Specifies a non-negative integer value indicating desired aspect ratio for the text. The aspect ratio is specified as 100\*width/height. 100 means the text should be as wide as it is tall, 200 means the text should be twice as wide as it is tall, 50 means the text should be twice as tall as it is wide, and so on. Used to choose line length for text if **-width** option is not specified. Defaults to 150. 

Command-Line Name: **-justify** Database Name: **justify** Database Class: **Justify** 


Specifies how to justify lines of text. Must be one of **left**, **center**, or **right**. Defaults to **left**. This option works together with the **-anchor**, **-aspect**, **-padx**, **-pady**, and **-width** options to provide a variety of arrangements of the text within the window. The **-aspect** and **-width** options determine the amount of screen space needed to display the text. The **-anchor**, **-padx**, and **-pady** options determine where this rectangular area is displayed within the widget's window, and the **-justify** option determines how each line is displayed within that rectangular region. For example, suppose **-anchor** is **e** and **-justify** is **left**, and that the message window is much larger than needed for the text. The text will be displayed so that the left edges of all the lines line up and the right edge of the longest line is **-padx** from the right side of the window; the entire text block will be centered in the vertical span of the window. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies the length of lines in the window. The value may have any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. If this option has a value greater than zero then the **-aspect** option is ignored and the **-width** option determines the line length. If this option has a value less than or equal to zero, then the **-aspect** option determines the line length. 
 Description
-----------

 The **message** command creates a new window (given by the *pathName* argument) and makes it into a message widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the message such as its colors, font, text, and initial relief. The **message** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  A message is a widget that displays a textual string. A message widget has three special features that differentiate it from a **[label](label.htm)** widget. First, it breaks up its string into lines in order to produce a given aspect ratio for the window. The line breaks are chosen at word boundaries wherever possible (if not even a single word would fit on a line, then the word will be split across lines). Newline characters in the string will force line breaks; they can be used, for example, to leave blank lines in the display. 


 The second feature of a message widget is justification. The text may be displayed left-justified (each line starts at the left side of the window), centered on a line-by-line basis, or right-justified (each line ends at the right side of the window). 


 The third feature of a message widget is that it handles control characters and non-printing characters specially. Tab characters are replaced with enough blank space to line up on the next 8-character boundary. Newlines cause line breaks. Other control characters (ASCII code less than 0x20) and characters not defined in the font are displayed as a four-character sequence **\x***hh* where *hh* is the two-digit hexadecimal number corresponding to the character. In the unusual case where the font does not contain all of the characters in “0123456789abcdef\x” then control characters and undefined characters are not displayed at all. 


Widget command
--------------

 The **message** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for message widgets: 
 
*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **message** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **message** command. 

 Default bindings
----------------

 When a new message is created, it has no default event bindings: messages are intended for output purposes only. Bugs
----

 Tabs do not work very well with text that is centered or right-justified. The most common result is that the line is justified wrong. See also
--------

 **[label](label.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/message.htm>

spinbox
=======

  
[NAME](spinbox.htm#M2) spinbox — Create and manipulate 'spinbox' value spinner widgets 
[SYNOPSIS](spinbox.htm#M3) 
[STANDARD OPTIONS](spinbox.htm#M4)  
[-activebackground, activeBackground, Foreground](options.htm#M-activebackground) 
[-background or -bg, background, Background](options.htm#M-background) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-exportselection, exportSelection, ExportSelection](options.htm#M-exportselection) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-insertbackground, insertBackground, Foreground](options.htm#M-insertbackground) 
[-insertborderwidth, insertBorderWidth, BorderWidth](options.htm#M-insertborderwidth) 
[-insertofftime, insertOffTime, OffTime](options.htm#M-insertofftime) 
[-insertontime, insertOnTime, OnTime](options.htm#M-insertontime) 
[-insertwidth, insertWidth, InsertWidth](options.htm#M-insertwidth) 
[-justify, justify, Justify](options.htm#M-justify) 
[-relief, relief, Relief](options.htm#M-relief) 
[-repeatdelay, repeatDelay, RepeatDelay](options.htm#M-repeatdelay) 
[-repeatinterval, repeatInterval, RepeatInterval](options.htm#M-repeatinterval) 
[-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground) 
[-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth) 
[-selectforeground, selectForeground, Background](options.htm#M-selectforeground) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-textvariable, textVariable, Variable](options.htm#M-textvariable) 
[-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand) 
























 
[WIDGET-SPECIFIC OPTIONS](spinbox.htm#M5)  
[-buttonbackground, buttonBackground, Background](spinbox.htm#M6) 
[-buttoncursor, buttonCursor, Cursor](spinbox.htm#M7) 
[-buttondownrelief, buttonDownRelief, Relief](spinbox.htm#M8) 
[-buttonuprelief, buttonUpRelief, Relief](spinbox.htm#M9) 
[-command, command, Command](spinbox.htm#M10) 
[-disabledbackground, disabledBackground, DisabledBackground](spinbox.htm#M11) 
[-disabledforeground, disabledForeground, DisabledForeground](spinbox.htm#M12) 
[-format, format, Format](spinbox.htm#M13) 
[-from, from, From](spinbox.htm#M14) 
[-invalidcommand or -invcmd, invalidCommand, InvalidCommand](spinbox.htm#M15) 
[-increment, increment, Increment](spinbox.htm#M16) 
[-readonlybackground, readonlyBackground, ReadonlyBackground](spinbox.htm#M17) 
[-state, state, State](spinbox.htm#M18) 
[-to, to, To](spinbox.htm#M19) 
[-validate, validate, Validate](spinbox.htm#M20) 
[-validatecommand or -vcmd, validateCommand, ValidateCommand](spinbox.htm#M21) 
[-values, values, Values](spinbox.htm#M22) 
[-width, width, Width](spinbox.htm#M23) 
[-wrap, wrap, wrap](spinbox.htm#M24) 


















 
[DESCRIPTION](spinbox.htm#M25) 
[VALIDATION](spinbox.htm#M26)  
[**none**](spinbox.htm#M27) 
[**focus**](spinbox.htm#M28) 
[**focusin**](spinbox.htm#M29) 
[**focusout**](spinbox.htm#M30) 
[**key**](spinbox.htm#M31) 
[**all**](spinbox.htm#M32) 





  
[**%d**](spinbox.htm#M33) 
[**%i**](spinbox.htm#M34) 
[**%P**](spinbox.htm#M35) 
[**%s**](spinbox.htm#M36) 
[**%S**](spinbox.htm#M37) 
[**%v**](spinbox.htm#M38) 
[**%V**](spinbox.htm#M39) 
[**%W**](spinbox.htm#M40) 







 
[WIDGET COMMAND](spinbox.htm#M41) 
[INDICES](spinbox.htm#M42)  
[*number*](spinbox.htm#M43) 
[**anchor**](spinbox.htm#M44) 
[**end**](spinbox.htm#M45) 
[**insert**](spinbox.htm#M46) 
[**sel.first**](spinbox.htm#M47) 
[**sel.last**](spinbox.htm#M48) 
[**@***number*](spinbox.htm#M49) 






 
[SUBCOMMANDS](spinbox.htm#M50)  
[*pathName* **bbox** *index*](spinbox.htm#M51) 
[*pathName* **cget** *option*](spinbox.htm#M52) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](spinbox.htm#M53) 
[*pathName* **delete** *first* ?*last*?](spinbox.htm#M54) 
[*pathName* **get**](spinbox.htm#M55) 
[*pathName* **icursor** *index*](spinbox.htm#M56) 
[*pathName* **identify** *x y*](spinbox.htm#M57) 
[*pathName* **index** *index*](spinbox.htm#M58) 
[*pathName* **insert** *index string*](spinbox.htm#M59) 
[*pathName* **invoke** *element*](spinbox.htm#M60) 
[*pathName* **scan** *option args*](spinbox.htm#M61)  
[*pathName* **scan mark** *x*](spinbox.htm#M62) 
[*pathName* **scan dragto** *x*](spinbox.htm#M63) 

 
[*pathName* **selection** *option arg*](spinbox.htm#M64)  
[*pathName* **selection adjust** *index*](spinbox.htm#M65) 
[*pathName* **selection clear**](spinbox.htm#M66) 
[*pathName* **selection element** ?*element*?](spinbox.htm#M67) 
[*pathName* **selection from** *index*](spinbox.htm#M68) 
[*pathName* **selection present**](spinbox.htm#M69) 
[*pathName* **selection range** *start end*](spinbox.htm#M70) 
[*pathName* **selection to** *index*](spinbox.htm#M71) 






 
[*pathName* **set** ?*string*?](spinbox.htm#M72) 
[*pathName* **validate**](spinbox.htm#M73) 
[*pathName* **xview** *args*](spinbox.htm#M74)  
[*pathName* **xview**](spinbox.htm#M75) 
[*pathName* **xview** *index*](spinbox.htm#M76) 
[*pathName* **xview moveto** *fraction*](spinbox.htm#M77) 
[*pathName* **xview scroll** *number what*](spinbox.htm#M78) 



 














 
[DEFAULT BINDINGS](spinbox.htm#M79) 
[SEE ALSO](spinbox.htm#M80) 
[KEYWORDS](spinbox.htm#M81) 











 Name
----

 spinbox — Create and manipulate 'spinbox' value spinner widgets Synopsis
--------

 **spinbox** *pathName* ?*options*?  
 Standard options
----------------

  
**[-activebackground, activeBackground, Foreground](options.htm#M-activebackground)** 
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-exportselection, exportSelection, ExportSelection](options.htm#M-exportselection)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-insertbackground, insertBackground, Foreground](options.htm#M-insertbackground)** 
**[-insertborderwidth, insertBorderWidth, BorderWidth](options.htm#M-insertborderwidth)** 
**[-insertofftime, insertOffTime, OffTime](options.htm#M-insertofftime)** 
**[-insertontime, insertOnTime, OnTime](options.htm#M-insertontime)** 
**[-insertwidth, insertWidth, InsertWidth](options.htm#M-insertwidth)** 
**[-justify, justify, Justify](options.htm#M-justify)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-repeatdelay, repeatDelay, RepeatDelay](options.htm#M-repeatdelay)** 
**[-repeatinterval, repeatInterval, RepeatInterval](options.htm#M-repeatinterval)** 
**[-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground)** 
**[-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth)** 
**[-selectforeground, selectForeground, Background](options.htm#M-selectforeground)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-textvariable, textVariable, Variable](options.htm#M-textvariable)** 
**[-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand)** 
























 Widget-specific options
-----------------------

  Command-Line Name: **-buttonbackground** Database Name: **buttonBackground** Database Class: **Background** 


The background color to be used for the spin buttons. 

Command-Line Name: **-buttoncursor** Database Name: **buttonCursor** Database Class: **Cursor** 


The cursor to be used when over the spin buttons. If this is empty (the default), a default cursor will be used. 

Command-Line Name: **-buttondownrelief** Database Name: **buttonDownRelief** Database Class: **Relief** 


The relief to be used for the upper spin button. 

Command-Line Name: **-buttonuprelief** Database Name: **buttonUpRelief** Database Class: **Relief** 


The relief to be used for the lower spin button. 

Command-Line Name: **-command** Database Name: **command** Database Class: **Command** 


Specifies a Tcl command to invoke whenever a spinbutton is invoked. The command recognizes several percent substitutions: **%W** for the widget path, **%s** for the current value of the widget, and **%d** for the direction of the button pressed (**up** or **down**). 

Command-Line Name: **-disabledbackground** Database Name: **disabledBackground** Database Class: **DisabledBackground** 


Specifies the background color to use when the spinbox is disabled. If this option is the empty string, the normal background color is used. 

Command-Line Name: **-disabledforeground** Database Name: **disabledForeground** Database Class: **DisabledForeground** 


Specifies the foreground color to use when the spinbox is disabled. If this option is the empty string, the normal foreground color is used. 

Command-Line Name: **-format** Database Name: **[format](../tclcmd/format.htm)** Database Class: **[Format](../tclcmd/format.htm)** 


Specifies an alternate format to use when setting the string value when using the **-from** and **-to** range. This must be a format specifier of the form **%<pad>.<pad>f**, as it will format a floating-point number. 

Command-Line Name: **-from** Database Name: **from** Database Class: **From** 


A floating-point value corresponding to the lowest value for a spinbox, to be used in conjunction with **-to** and **-increment**. When all are specified correctly, the spinbox will use these values to control its contents. This value must be less than the **-to** option. If **-values** is specified, it supersedes this option. 

Command-Line Name: **-invalidcommand or -invcmd** Database Name: **invalidCommand** Database Class: **InvalidCommand** 


Specifies a script to eval when **-validatecommand** returns 0. Setting it to an empty string disables this feature (the default). The best use of this option is to set it to *bell*. See **[VALIDATION](#M26)** below for more information. 

Command-Line Name: **-increment** Database Name: **increment** Database Class: **Increment** 


A floating-point value specifying the increment. When used with **-from** and **-to**, the value in the widget will be adjusted by **-increment** when a spin button is pressed (up adds the value, down subtracts the value). 

Command-Line Name: **-readonlybackground** Database Name: **readonlyBackground** Database Class: **ReadonlyBackground** 


Specifies the background color to use when the spinbox is readonly. If this option is the empty string, the normal background color is used. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Specifies one of three states for the spinbox: **normal**, **disabled**, or **readonly**. If the spinbox is readonly, then the value may not be changed using widget commands and no insertion cursor will be displayed, even if the input focus is in the widget; the contents of the widget may still be selected. If the spinbox is disabled, the value may not be changed, no insertion cursor will be displayed, the contents will not be selectable, and the spinbox may be displayed in a different color, depending on the values of the **-disabledforeground** and **-disabledbackground** options. 

Command-Line Name: **-to** Database Name: **to** Database Class: **To** 


A floating-point value corresponding to the highest value for the spinbox, to be used in conjunction with **-from** and **-increment**. When all are specified correctly, the spinbox will use these values to control its contents. This value must be greater than the **-from** option. If **-values** is specified, it supersedes this option. 

Command-Line Name: **-validate** Database Name: **validate** Database Class: **Validate** 


Specifies the mode in which validation should operate: **none**, **[focus](focus.htm)**, **focusin**, **focusout**, **key**, or **all**. It defaults to **none**. When you want validation, you must explicitly state which mode you wish to use. See **[VALIDATION](#M26)** below for more. 

Command-Line Name: **-validatecommand or -vcmd** Database Name: **validateCommand** Database Class: **ValidateCommand** 


Specifies a script to evaluate when you want to validate the input in the widget. Setting it to an empty string disables this feature (the default). Validation occurs according to the value of **-validate**. This command must return a valid Tcl boolean value. If it returns 0 (or the valid Tcl boolean equivalent) then the value of the widget will not change and the **-invalidcommand** will be evaluated if it is set. If it returns 1, then value will be changed. See **[VALIDATION](#M26)** below for more information. 

Command-Line Name: **-values** Database Name: **values** Database Class: **Values** 


Must be a proper list value. If specified, the spinbox will use these values as to control its contents, starting with the first value. This option has precedence over the **-from** and **-to** range. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies an integer value indicating the desired width of the spinbox window, in average-size characters of the widget's font. If the value is less than or equal to zero, the widget picks a size just large enough to hold its current text. 

Command-Line Name: **-wrap** Database Name: **wrap** Database Class: **wrap** 


Must be a proper boolean value. If on, the spinbox will wrap around the values of data in the widget. 
 Description
-----------

 The **spinbox** command creates a new window (given by the *pathName* argument) and makes it into a spinbox widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the spinbox such as its colors, font, and relief. The **spinbox** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  A **spinbox** is an extended **[entry](entry.htm)** widget that allows he user to move, or spin, through a fixed set of ascending or descending values such as times or dates in addition to editing the value as in an **[entry](entry.htm)**. When first created, a spinbox's string is empty. A portion of the spinbox may be selected as described below. If a spinbox is exporting its selection (see the **-exportselection** option), then it will observe the standard protocols for handling the selection; spinbox selections are available as type **[STRING](../tclcmd/string.htm)**. Spinboxes also observe the standard Tk rules for dealing with the input focus. When a spinbox has the input focus it displays an *insertion cursor* to indicate where new characters will be inserted. 


 Spinboxes are capable of displaying strings that are too long to fit entirely within the widget's window. In this case, only a portion of the string will be displayed; commands described below may be used to change the view in the window. Spinboxes use the standard **-xscrollcommand** mechanism for interacting with scrollbars (see the description of the **-xscrollcommand** option for details). They also support scanning, as described below. 


Validation
----------

 Validation works by setting the **-validatecommand** option to a script which will be evaluated according to the **-validate** option as follows: 

 **none**
 Default. This means no validation will occur. 

**focus**
 The **-validatecommand** will be called when the spinbox receives or loses focus. 

**focusin**
 The **-validatecommand** will be called when the spinbox receives focus. 

**focusout**
 The **-validatecommand** will be called when the spinbox loses focus. 

**key**
 The **-validatecommand** will be called when the spinbox is edited. 

**all**
 The **-validatecommand** will be called for all above conditions. 

  It is possible to perform percent substitutions on the **-validatecommand** and **-invalidcommand** scripts, just as you would in a **[bind](bind.htm)** script. The following substitutions are recognized: 


 **%d**
 Type of action: 1 for **insert**, 0 for **delete**, or -1 for focus, forced or textvariable validation. 

**%i**
 Index of char string to be inserted/deleted, if any, otherwise -1. 

**%P**
 The value of the spinbox should edition occur. If you are configuring the spinbox widget to have a new textvariable, this will be the value of that textvariable. 

**%s**
 The current value of spinbox before edition. 

**%S**
 The text string being inserted/deleted, if any. Otherwise it is an empty string. 

**%v**
 The type of validation currently set. 

**%V**
 The type of validation that triggered the callback (key, focusin, focusout, forced). 

**%W**
 The name of the spinbox widget. 

  In general, the **-textvariable** and **-validatecommand** can be dangerous to mix. Any problems have been overcome so that using the **-validatecommand** will not interfere with the traditional behavior of the spinbox widget. Using the **-textvariable** for read-only purposes will never cause problems. The danger comes when you try set the **-textvariable** to something that the **-validatecommand** would not accept, which causes **-validate** to become **none** (the **-invalidcommand** will not be triggered). The same happens when an error occurs evaluating the **-validatecommand**. 


 Primarily, an error will occur when the **-validatecommand** or **-invalidcommand** encounters an error in its script while evaluating or **-validatecommand** does not return a valid Tcl boolean value. The **-validate** option will also set itself to **none** when you edit the spinbox widget from within either the **-validatecommand** or the **-invalidcommand**. Such editions will override the one that was being validated. If you wish to edit the value of the widget during validation and still have the **-validate** option set, you should include the command 



```
*%W config -validate %v*
```
 in the **-validatecommand** or **-invalidcommand** (whichever one you were editing the spinbox widget from). It is also recommended to not set an associated **-textvariable** during validation, as that can cause the spinbox widget to become out of sync with the **-textvariable**.  Also, the **validate** option will set itself to **none** when the spinbox value gets changed because of adjustment of **from** or **to** and the **validateCommand** returns false. For instance 



```
*spinbox pathName -from 1 -to 10 -validate all -vcmd {return 0}*
```
 will in fact set the **validate** option to **none** because the default value for the spinbox gets changed (due to the **from** and **to** options) to a value not accepted by the validation script. Widget command
--------------

 The **spinbox** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command. ### Indices

 Many of the widget commands for spinboxes take one or more indices as arguments. An index specifies a particular character in the spinbox's string, in any of the following ways: 
 *number*
 Specifies the character as a numerical index, where 0 corresponds to the first character in the string. 

**anchor**
 Indicates the anchor point for the selection, which is set with the **select from** and **select adjust** widget commands. 

**end**
 Indicates the character just after the last one in the spinbox's string. This is equivalent to specifying a numerical index equal to the length of the spinbox's string. 

**insert**
 Indicates the character adjacent to and immediately following the insertion cursor. 

**sel.first**
 Indicates the first character in the selection. It is an error to use this form if the selection is not in the spinbox window. 

**sel.last**
 Indicates the character just after the last one in the selection. It is an error to use this form if the selection is not in the spinbox window. 


**@***number*

 In this form, *number* is treated as an x-coordinate in the spinbox's window; the character spanning that x-coordinate is used. For example, “**@0**” indicates the left-most character in the window. 

  Abbreviations may be used for any of the forms above, e.g. “**e**” or “**sel.f**”. In general, out-of-range indices are automatically rounded to the nearest legal value. 


### Subcommands

 The following commands are possible for spinbox widgets: 
 
*pathName* **bbox** *index*

 Returns a list of four numbers describing the bounding box of the character given by *index*. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window. 


*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **spinbox** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **spinbox** command. 


*pathName* **delete** *first* ?*last*?
 Delete one or more elements of the spinbox. *First* is the index of the first character to delete, and *last* is the index of the character just after the last one to delete. If *last* is not specified it defaults to *first*+1, i.e. a single character is deleted. This command returns an empty string. 


*pathName* **get**

 Returns the spinbox's string. 


*pathName* **icursor** *index*

 Arrange for the insertion cursor to be displayed just before the character given by *index*. Returns an empty string. 


*pathName* **identify** *x y*

 Returns the name of the window element corresponding to coordinates *x* and *y* in the spinbox. Return value is one of: **none**, **buttondown**, **buttonup**, **[entry](entry.htm)**. 


*pathName* **index** *index*

 Returns the numerical index corresponding to *index*. 


*pathName* **insert** *index string*

 Insert the characters of *string* just before the character indicated by *index*. Returns an empty string. 


*pathName* **invoke** *element*

 Causes the specified element, either **buttondown** or **buttonup**, to be invoked, triggering the action associated with it. 


*pathName* **scan** *option args*

 This command is used to implement scanning on spinboxes. It has two forms, depending on *option*: 
 
*pathName* **scan mark** *x*

 Records *x* and the current view in the spinbox window; used in conjunction with later **scan dragto** commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. 


*pathName* **scan dragto** *x*

 This command computes the difference between its *x* argument and the *x* argument to the last **scan mark** command for the widget. It then adjusts the view left or right by 10 times the difference in x-coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the spinbox at high speed through the window. The return value is an empty string. 




*pathName* **selection** *option arg*

 This command is used to adjust the selection within a spinbox. It has several forms, depending on *option*: 
 
*pathName* **selection adjust** *index*

 Locate the end of the selection nearest to the character given by *index*, and adjust that end of the selection to be at *index* (i.e. including but not going beyond *index*). The other end of the selection is made the anchor point for future **select to** commands. If the selection is not currently in the spinbox, then a new selection is created to include the characters between *index* and the most recent selection anchor point, inclusive. Returns an empty string. 


*pathName* **selection clear**

 Clear the selection if it is currently in this widget. If the selection is not in this widget then the command has no effect. Returns an empty string. 


*pathName* **selection element** ?*element*?
 Sets or gets the currently selected element. If a spinbutton element is specified, it will be displayed depressed. 


*pathName* **selection from** *index*

 Set the selection anchor point to just before the character given by *index*. Does not change the selection. Returns an empty string. 


*pathName* **selection present**

 Returns 1 if there is are characters selected in the spinbox, 0 if nothing is selected. 


*pathName* **selection range** *start end*

 Sets the selection to include the characters starting with the one indexed by *start* and ending with the one just before *end*. If *end* refers to the same character as *start* or an earlier one, then the spinbox's selection is cleared. 


*pathName* **selection to** *index*

 If *index* is before the anchor point, set the selection to the characters from *index* up to but not including the anchor point. If *index* is the same as the anchor point, do nothing. If *index* is after the anchor point, set the selection to the characters from the anchor point up to but not including *index*. The anchor point is determined by the most recent **select from** or **select adjust** command in this widget. If the selection is not in this widget then a new selection is created using the most recent anchor point specified for the widget. Returns an empty string. 




*pathName* **set** ?*string*?
 If *string* is specified, the spinbox will try and set it to this value, otherwise it just returns the spinbox's string. If validation is on, it will occur when setting the string. 


*pathName* **validate**

 This command is used to force an evaluation of the **-validatecommand** independent of the conditions specified by the **-validate** option. This is done by temporarily setting the **-validate** option to **all**. It returns 0 or 1. 


*pathName* **xview** *args*

 This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: 
 
*pathName* **xview**

 Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the spinbox's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the **-xscrollcommand** option. 


*pathName* **xview** *index*

 Adjusts the view in the window so that the character given by *index* is displayed at the left edge of the window. 


*pathName* **xview moveto** *fraction*

 Adjusts the view in the window so that the character *fraction* of the way through the text appears at the left edge of the window. *Fraction* must be a fraction between 0 and 1. 


*pathName* **xview scroll** *number what*

 This command shifts the view in the window left or right according to *number* and *what*. *Number* must be an integer. *What* must be either **units** or **pages** or an abbreviation of one of these. If *what* is **units**, the view adjusts left or right by *number* average-width characters on the display; if it is **pages** then the view adjusts by *number* screenfuls. If *number* is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. 



 Default bindings
----------------

 Tk automatically creates class bindings for spinboxes that give them the following default behavior. In the descriptions below, “word” refers to a contiguous group of letters, digits, or “\_” characters, or any single character other than these. 
1. Clicking mouse button 1 positions the insertion cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse.
2. Double-clicking with mouse button 1 selects the word under the mouse and positions the insertion cursor at the beginning of the word. Dragging after a double click will stroke out a selection consisting of whole words.
3. Triple-clicking with mouse button 1 selects all of the text in the spinbox and positions the insertion cursor before the first character.
4. The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down; this will adjust the end of the selection that was nearest to the mouse cursor when button 1 was pressed. If the button is double-clicked before dragging then the selection will be adjusted in units of whole words.
5. Clicking mouse button 1 with the Control key down will position the insertion cursor in the spinbox without affecting the selection.
6. If any normal printing characters are typed in a spinbox, they are inserted at the point of the insertion cursor.
7. The view in the spinbox can be adjusted by dragging with mouse button 2. If mouse button 2 is clicked without moving the mouse, the selection is copied into the spinbox at the position of the mouse cursor.
8. If the mouse is dragged out of the spinbox on the left or right sides while button 1 is pressed, the spinbox will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window).
9. The Left and Right keys move the insertion cursor one character to the left or right; they also clear any selection in the spinbox and set the selection anchor. If Left or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Left and Control-Right move the insertion cursor by words, and Control-Shift-Left and Control-Shift-Right move the insertion cursor by words and also extend the selection. Control-b and Control-f behave the same as Left and Right, respectively. Meta-b and Meta-f behave the same as Control-Left and Control-Right, respectively.
10. The Home key, or Control-a, will move the insertion cursor to the beginning of the spinbox and clear any selection in the spinbox. Shift-Home moves the insertion cursor to the beginning of the spinbox and also extends the selection to that point.
11. The End key, or Control-e, will move the insertion cursor to the end of the spinbox and clear any selection in the spinbox. Shift-End moves the cursor to the end and extends the selection to that point.
12. The Select key and Control-Space set the selection anchor to the position of the insertion cursor. They do not affect the current selection. Shift-Select and Control-Shift-Space adjust the selection to the current position of the insertion cursor, selecting from the anchor to the insertion cursor if there was not any selection previously.
13. Control-/ selects all the text in the spinbox.
14. Control-\ clears any selection in the spinbox.
15. The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection.
16. The F20 key (labelled Cut on many Sun workstations) or Control-w copies the selection in the widget to the clipboard and deletes the selection. If there is no selection in the widget then these keys have no effect.
17. The F18 key (labelled Paste on many Sun workstations) or Control-y inserts the contents of the clipboard at the position of the insertion cursor.
18. The Delete key deletes the selection, if there is one in the spinbox. If there is no selection, it deletes the character to the right of the insertion cursor.
19. The BackSpace key and Control-h delete the selection, if there is one in the spinbox. If there is no selection, it deletes the character to the left of the insertion cursor.
20. Control-d deletes the character to the right of the insertion cursor.
21. Meta-d deletes the word to the right of the insertion cursor.
22. Control-k deletes all the characters to the right of the insertion cursor.
23. Control-t reverses the order of the two characters to the right of the insertion cursor.

  If the spinbox is disabled using the **-state** option, then the spinbox's view can still be adjusted and text in the spinbox can still be selected, but no insertion cursor will be displayed and no text modifications will take place. 


 The behavior of spinboxes can be changed by defining new bindings for individual widgets or by redefining the class bindings. 


See also
--------

 **[ttk::spinbox](ttk_spinbox.htm)** Copyright © 2000 Jeffrey Hobbs.  
 Copyright © 2000 Ajuba Solutions. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/spinbox.htm>

cursors
=======

 Name
----

 cursors — mouse cursors available in Tk Description
-----------

 The **-cursor** widget option allows a Tk programmer to change the mouse cursor for a particular widget. The cursor names recognized by Tk on all platforms are: 
```
X_cursor
arrow
based_arrow_down
based_arrow_up
boat
bogosity
bottom_left_corner
bottom_right_corner
bottom_side
bottom_tee
box_spiral
center_ptr
circle
clock
coffee_mug
cross
cross_reverse
crosshair
diamond_cross
dot
dotbox
double_arrow
draft_large
draft_small
draped_box
exchange
fleur
gobbler
gumby
hand1
hand2
heart
icon
iron_cross
left_ptr
left_side
left_tee
leftbutton
ll_angle
lr_angle
man
middlebutton
mouse
none
pencil
pirate
plus
question_arrow
right_ptr
right_side
right_tee
rightbutton
rtl_logo
sailboat
sb_down_arrow
sb_h_double_arrow
sb_left_arrow
sb_right_arrow
sb_up_arrow
sb_v_double_arrow
shuttle
sizing
spider
spraycan
star
target
tcross
top_left_arrow
top_left_corner
top_right_corner
top_side
top_tee
trek
ul_angle
umbrella
ur_angle
watch
xterm
```
  The **none** cursor can be specified to eliminate the cursor. 


Portability issues
------------------

  **Windows**
 On Windows systems, the following cursors are mapped to native cursors: 
```
arrow
center_ptr
crosshair
fleur
ibeam
icon
none
sb_h_double_arrow
sb_v_double_arrow
watch
xterm
```
 And the following additional cursors are available: 
```
no
starting
size
size_ne_sw
size_ns
size_nw_se
size_we
uparrow
wait
```


**Mac OS X**
 On Mac OS X systems, the following cursors are mapped to native cursors: 
```
arrow
top_left_arrow
left_ptr
cross
crosshair
tcross
ibeam
none
xterm
```
 And the following additional native cursors are available: 
```
copyarrow
aliasarrow
contextualmenuarrow
movearrow
text
cross-hair
hand
openhand
closedhand
fist
pointinghand
resize
resizeleft
resizeright
resizeleftright
resizeup
resizedown
resizeupdown
resizebottomleft
resizetopleft
resizebottomright
resizetopright
notallowed
poof
wait
countinguphand
countingdownhand
countingupanddownhand
spinning
help
bucket
cancel
eyedrop
eyedrop-full
zoom-in
zoom-out
```


 Copyright © 1998-2000 by Scriptics Corporation.  
 Copyright © 2006-2007 Daniel A. Steffen <das(at)users.sourceforge.net> 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/cursors.htm>

destroy
=======

 Name
----

 destroy — Destroy one or more windows Synopsis
--------

 **destroy** ?*window window ...*?  
 Description
-----------

 This command deletes the windows given by the *window* arguments, plus all of their descendants. If a *window* “.” is deleted then all windows will be destroyed and the application will (normally) exit. The *window*s are destroyed in order, and if an error occurs in destroying a window the command aborts without destroying the remaining windows. No error is returned if *window* does not exist. Example
-------

 Destroy all checkbuttons that are direct children of the given widget: 
```
proc killCheckbuttonChildren {parent} {
   foreach w [winfo children $parent] {
      if {[winfo class $w] eq "Checkbutton"} {
         **destroy** $w
      }
   }
}
```
 Copyright © 1990 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/destroy.htm>

dialog
======

  
[NAME](dialog.htm#M2) tk\_dialog — Create modal dialog and wait for response 
[SYNOPSIS](dialog.htm#M3) 
[DESCRIPTION](dialog.htm#M4)  
[*window*](dialog.htm#M5) 
[*title*](dialog.htm#M6) 
[*text*](dialog.htm#M7) 
[*bitmap*](dialog.htm#M8) 
[*default*](dialog.htm#M9) 
[*string*](dialog.htm#M10) 





 
[EXAMPLE](dialog.htm#M11) 
[SEE ALSO](dialog.htm#M12) 
[KEYWORDS](dialog.htm#M13) 





 Name
----

 tk\_dialog — Create modal dialog and wait for response Synopsis
--------

 **tk\_dialog** *window title text bitmap default string string ...*  
 Description
-----------

 This procedure is part of the Tk script library. It is largely *deprecated* by the **tk\_messageBox**. Its arguments describe a dialog box: 
 *window*
 Name of top-level window to use for dialog. Any existing window by this name is destroyed. 

*title*
 Text to appear in the window manager's title bar for the dialog. 

*text*
 Message to appear in the top portion of the dialog box. 

*bitmap*
 If non-empty, specifies a bitmap (in a form suitable for [Tk\_GetBitmap](https://www.tcl.tk/man/tcl/TkLib/GetBitmap.htm)) to display in the top portion of the dialog, to the left of the text. If this is an empty string then no bitmap is displayed in the dialog. 

*default*
 If this is an integer greater than or equal to zero, then it gives the index of the button that is to be the default button for the dialog (0 for the leftmost button, and so on). If less than zero or an empty string then there will not be any default button. 

*string*
 There will be one button for each of these arguments. Each *string* specifies text to display in a button, in order from left to right. 

  After creating a dialog box, **tk\_dialog** waits for the user to select one of the buttons either by clicking on the button with the mouse or by typing return to invoke the default button (if any). Then it returns the index of the selected button: 0 for the leftmost button, 1 for the button next to it, and so on. If the dialog's window is destroyed before the user selects one of the buttons, then -1 is returned. 


 While waiting for the user to respond, **tk\_dialog** sets a local grab. This prevents the user from interacting with the application in any way except to invoke the dialog box. 


Example
-------

 
```
set reply [**tk\_dialog** .foo "The Title" "Do you want to say yes?" \
        questhead 0 Yes No "I'm not sure"]
```
 See also
--------

 **tk\_messageBox** Copyright © 1992 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/dialog.htm>

focusNext
=========

 Name
----

 tk\_focusNext, tk\_focusPrev, tk\_focusFollowsMouse — Utility procedures for managing the input focus. Synopsis
--------

 **tk\_focusNext** *window*  
 **tk\_focusPrev** *window*  
 **tk\_focusFollowsMouse**  
 Description
-----------

 **tk\_focusNext** is a utility procedure used for keyboard traversal. It returns the “next” window after *window* in focus order. The focus order is determined by the stacking order of windows and the structure of the window hierarchy. Among siblings, the focus order is the same as the stacking order, with the lowest window being first. If a window has children, the window is visited first, followed by its children (recursively), followed by its next sibling. Top-level windows other than *window* are skipped, so that **tk\_focusNext** never returns a window in a different top-level from *window*.  After computing the next window, **tk\_focusNext** examines the window's **-takefocus** option to see whether it should be skipped. If so, **tk\_focusNext** continues on to the next window in the focus order, until it eventually finds a window that will accept the focus or returns back to *window*. 


 **tk\_focusPrev** is similar to **tk\_focusNext** except that it returns the window just before *window* in the focus order. 


 **tk\_focusFollowsMouse** changes the focus model for the application to an implicit one where the window under the mouse gets the focus. After this procedure is called, whenever the mouse enters a window Tk will automatically give it the input focus. The **[focus](focus.htm)** command may be used to move the focus to a window other than the one under the mouse, but as soon as the mouse moves into a new window the focus will jump to that window. Note: at present there is no built-in support for returning the application to an explicit focus model; to do this you will have to write a script that deletes the bindings created by **tk\_focusFollowsMouse**. 

 Copyright © 1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/focusNext.htm>

ttk\_style
==========

  
[NAME](ttk_style.htm#M2) ttk::style — Manipulate style database 
[SYNOPSIS](ttk_style.htm#M3) 
[NOTES](ttk_style.htm#M4) 
[DEFINITIONS](ttk_style.htm#M5) 
[DESCRIPTION](ttk_style.htm#M6)  
[**ttk::style configure** *style* ?*-option* ?*value option value...*? ?](ttk_style.htm#M7) 
[**ttk::style map** *style* ?*-option* **{** *statespec value...* **}**?](ttk_style.htm#M8) 
[**ttk::style lookup** *style* *-option* ?*state* ?*default*??](ttk_style.htm#M9) 
[**ttk::style layout** *style* ?*layoutSpec*?](ttk_style.htm#M10) 
[**ttk::style element create** *elementName* *type* ?*args...*?](ttk_style.htm#M11) 
[**ttk::style element names**](ttk_style.htm#M12) 
[**ttk::style element options** *element*](ttk_style.htm#M13) 
[**ttk::style theme create** *themeName* ?**-parent** *basedon*? ?**-settings** *script...* ?](ttk_style.htm#M14) 
[**ttk::style theme settings** *themeName* *script*](ttk_style.htm#M15) 
[**ttk::style theme names**](ttk_style.htm#M16) 
[**ttk::style theme use** ?*themeName*?](ttk_style.htm#M17) 










 
[LAYOUTS](ttk_style.htm#M18)  
[**-side** *side*](ttk_style.htm#M19) 
[**-sticky** **[***nswe***]**](ttk_style.htm#M20) 
[**-children {** *sublayout...* **}**](ttk_style.htm#M21) 


 
[SEE ALSO](ttk_style.htm#M22) 
[KEYWORDS](ttk_style.htm#M23) 







 Name
----

 ttk::style — Manipulate style database Synopsis
--------

 **ttk::style** *option* ?*args*?  
 Notes
-----

 See also the Tcl'2004 conference presentation, available at <http://tktable.sourceforge.net/tile/tile>-tcl2004.pdf Definitions
-----------

 Each widget is assigned a *style*, which specifies the set of elements making up the widget and how they are arranged, along with dynamic and default settings for element options. By default, the style name is the same as the widget's class; this may be overridden by the **-style** option.  A *theme* is a collection of elements and styles which controls the overall look and feel of an application. 


Description
-----------

 The **ttk::style** command takes the following arguments: 
 
**ttk::style configure** *style* ?*-option* ?*value option value...*? ?
 Sets the default value of the specified option(s) in *style*. 


**ttk::style map** *style* ?*-option* **{** *statespec value...* **}**?
 Sets dynamic values of the specified option(s) in *style*. Each *statespec / value* pair is examined in order; the value corresponding to the first matching *statespec* is used. 


**ttk::style lookup** *style* *-option* ?*state* ?*default*??
 Returns the value specified for *-option* in style *style* in state *state*, using the standard lookup rules for element options. *state* is a list of state names; if omitted, it defaults to all bits off (the “normal” state). If the *default* argument is present, it is used as a fallback value in case no specification for *-option* is found. 


**ttk::style layout** *style* ?*layoutSpec*?
 Define the widget layout for style *style*. See **[LAYOUTS](#M18)** below for the format of *layoutSpec*. If *layoutSpec* is omitted, return the layout specification for style *style*. 


**ttk::style element create** *elementName* *type* ?*args...*?
 Creates a new element in the current theme of type *type*. The only cross-platform built-in element type is *image* (see **[ttk\_image](ttk_image.htm)**(n)) but themes may define other element types (see **Ttk\_RegisterElementFactory**). On suitable versions of Windows an element factory is registered to create Windows theme elements (see **[ttk\_vsapi](ttk_vsapi.htm)**(n)). 

**ttk::style element names**
 Returns the list of elements defined in the current theme. 


**ttk::style element options** *element*

 Returns the list of *element*'s options. 


**ttk::style theme create** *themeName* ?**-parent** *basedon*? ?**-settings** *script...* ?
 Creates a new theme. It is an error if *themeName* already exists. If **-parent** is specified, the new theme will inherit styles, elements, and layouts from the parent theme *basedon*. If **-settings** is present, *script* is evaluated in the context of the new theme as per **ttk::style theme settings**. 


**ttk::style theme settings** *themeName* *script*

 Temporarily sets the current theme to *themeName*, evaluate *script*, then restore the previous theme. Typically *script* simply defines styles and elements, though arbitrary Tcl code may appear. 

**ttk::style theme names**
 Returns a list of all known themes. 


**ttk::style theme use** ?*themeName*?
 Without an argument the result is the name of the current theme. Otherwise this command sets the current theme to *themeName*, and refreshes all widgets. 

 Layouts
-------

 A *layout* specifies a list of elements, each followed by one or more options specifying how to arrange the element. The layout mechanism uses a simplified version of the **[pack](pack.htm)** geometry manager: given an initial cavity, each element is allocated a parcel. Valid options are: 
 
**-side** *side*

 Specifies which side of the cavity to place the element; one of **left**, **right**, **top**, or **bottom**. If omitted, the element occupies the entire cavity. 


**-sticky** **[***nswe***]**

 Specifies where the element is placed inside its allocated parcel. 


**-children {** *sublayout...* **}**

 Specifies a list of elements to place inside the element. 

  For example: 



```
ttk::style layout Horizontal.TScrollbar {
    Scrollbar.trough -children {
        Scrollbar.leftarrow -side left
        Scrollbar.rightarrow -side right
        Horizontal.Scrollbar.thumb -side left -sticky ew
    }
}
```
 See also
--------

 **[ttk::intro](ttk_intro.htm)**, **[ttk::widget](ttk_widget.htm)**, **[photo](photo.htm)**, **[ttk\_image](ttk_image.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_style.htm>

option
======

  
[NAME](option.htm#M2) option — Add/retrieve window options to/from the option database 
[SYNOPSIS](option.htm#M3) 
[DESCRIPTION](option.htm#M4)  
[**widgetDefault**](option.htm#M5) 
[**startupFile**](option.htm#M6) 
[**userDefault**](option.htm#M7) 
[**interactive**](option.htm#M8) 



 
[PATTERN FORMAT](option.htm#M9) 
[EXAMPLES](option.htm#M10) 
[SEE ALSO](option.htm#M11) 
[KEYWORDS](option.htm#M12) 






 Name
----

 option — Add/retrieve window options to/from the option database Synopsis
--------

 **option add** *pattern value* ?*priority*?  
 **option clear**  
 **option get** *window name class*  
 **option readfile** *fileName* ?*priority*?  
 Description
-----------

 The **option** command allows you to add entries to the Tk option database or to retrieve options from the database. The **add** form of the command adds a new option to the database. *Pattern* contains the option being specified, and consists of names and/or classes separated by asterisks or dots, in the usual X format (see **[PATTERN FORMAT](#M9)**). *Value* contains a text string to associate with *pattern*; this is the value that will be returned in calls to **[Tk\_GetOption](https://www.tcl.tk/man/tcl/TkLib/GetOption.htm)** or by invocations of the **option get** command. If *priority* is specified, it indicates the priority level for this option (see below for legal values); it defaults to **interactive**. This command always returns an empty string.  The **option clear** command clears the option database. Default options (from the **RESOURCE\_MANAGER** property or the **.Xdefaults** file) will be reloaded automatically the next time an option is added to the database or removed from it. This command always returns an empty string. 


 The **option get** command returns the value of the option specified for *window* under *name* and *class*. If several entries in the option database match *window*, *name*, and *class*, then the command returns whichever was created with highest *priority* level. If there are several matching entries at the same priority level, then it returns whichever entry was most recently entered into the option database. If there are no matching entries, then the empty string is returned. 


 The **readfile** form of the command reads *fileName*, which should have the standard format for an X resource database such as **.Xdefaults**, and adds all the options specified in that file to the option database. If *priority* is specified, it indicates the priority level at which to enter the options; *priority* defaults to **interactive**. 


 The file is read through a channel which is in "utf-8" encoding, invalid byte sequences are automatically converted to valid ones. This means that encodings like ISO 8859-1 or cp1252 with high probability will work as well, but this cannot be guaranteed. This cannot be changed, setting the [encoding system] has no effect. 


 The *priority* arguments to the **option** command are normally specified symbolically using one of the following values: 


 **widgetDefault**
 Level 20. Used for default values hard-coded into widgets. 

**startupFile**
 Level 40. Used for options specified in application-specific startup files. 

**userDefault**
 Level 60. Used for options specified in user-specific defaults files, such as **.Xdefaults**, resource databases loaded into the X server, or user-specific startup files. 

**interactive**
 Level 80. Used for options specified interactively after the application starts running. If *priority* is not specified, it defaults to this level. 

  Any of the above keywords may be abbreviated. In addition, priorities may be specified numerically using integers between 0 and 100, inclusive. The numeric form is probably a bad idea except for new priority levels other than the ones given above. 


Pattern format
--------------

 Patterns consist of a sequence of words separated by either periods, “.”, or asterisks “\*”. The overall pattern may also be optionally preceded by an asterisk.  Each word in the pattern conventionally starts with either an upper-case letter (in which case it denotes the class of either a widget or an option) or any other character, when it denotes the name of a widget or option. The last word in the pattern always indicates the option; the preceding ones constrain which widgets that option will be looked for in. 


 When two words are separated by a period, the latter widget must be a direct child of the former (or the option must apply to only the indicated widgets). When two words are separated by an asterisk, any depth of widgets may lie between the former and latter widgets (and the option applies to all widgets that are children of the former widget). 


 If the overall pattern is preceded by an asterisk, then the overall pattern applies anywhere it can throughout the whole widget hierarchy. Otherwise the first word of the pattern is matched against the name and class of the “**.**” **[toplevel](toplevel.htm)**, which are usually set by options to **[wish](../usercmd/wish.htm)**. 


Examples
--------

 Instruct every button in the application to have red text on it unless explicitly overridden, by setting the **foreground** for the **[Button](button.htm)** class (note that on some platforms the option is ignored): 
```
**option add** *Button.foreground red startupFile
```
  Allow users to control what happens in an entry widget when the Return key is pressed by specifying a script in the option database and add a default option for that which rings the bell: 



```
entry .e
bind .e <Return> [**option get** .e returnCommand Command]
**option add** *.e.returnCommand bell widgetDefault
```
 See also
--------

 **[options](options.htm)**, **[wish](../usercmd/wish.htm)** Copyright © 1990 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/option.htm>

toplevel
========

  
[NAME](toplevel.htm#M2) toplevel — Create and manipulate 'toplevel' main and popup window widgets 
[SYNOPSIS](toplevel.htm#M3) 
[STANDARD OPTIONS](toplevel.htm#M4)  
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-padx, padX, Pad](options.htm#M-padx) 
[-pady, padY, Pad](options.htm#M-pady) 
[-relief, relief, Relief](options.htm#M-relief) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 








 
[WIDGET-SPECIFIC OPTIONS](toplevel.htm#M5)  
[-background, background, Background](toplevel.htm#M6) 
[-class, class, Class](toplevel.htm#M7) 
[-colormap, colormap, Colormap](toplevel.htm#M8) 
[-container, container, Container](toplevel.htm#M9) 
[-height, height, Height](toplevel.htm#M10) 
[-menu, menu, Menu](toplevel.htm#M11) 
[-screen, ,](toplevel.htm#M12)  
[-use, use, Use](toplevel.htm#M13) 
[-visual, visual, Visual](toplevel.htm#M14) 
[-width, width, Width](toplevel.htm#M15) 









 
[DESCRIPTION](toplevel.htm#M16) 
[WIDGET COMMAND](toplevel.htm#M17)  
[*pathName* **cget** *option*](toplevel.htm#M18) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](toplevel.htm#M19) 

 
[BINDINGS](toplevel.htm#M20) 
[SEE ALSO](toplevel.htm#M21) 
[KEYWORDS](toplevel.htm#M22) 








 Name
----

 toplevel — Create and manipulate 'toplevel' main and popup window widgets Synopsis
--------

 **toplevel** *pathName* ?*options*?  
 Standard options
----------------

  
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-padx, padX, Pad](options.htm#M-padx)** 
**[-pady, padY, Pad](options.htm#M-pady)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 








 Widget-specific options
-----------------------

  Command-Line Name: **-background** Database Name: **background** Database Class: **Background** 


This option is the same as the standard **-background** option except that its value may also be specified as an empty string. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border. 

Command-Line Name: **-class** Database Name: **class** Database Class: **Class** 


Specifies a class for the window. This class will be used when querying the option database for the window's other options, and it will also be used later for other purposes such as bindings. The **-class** option may not be changed with the **configure** widget command. 

Command-Line Name: **-colormap** Database Name: **colormap** Database Class: **Colormap** 


Specifies a colormap to use for the window. The value may be either **new**, in which case a new colormap is created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as *pathName*), in which case the new window will use the colormap from the specified window. If the **-colormap** option is not specified, the new window uses the default colormap of its screen. This option may not be changed with the **configure** widget command. 

Command-Line Name: **-container** Database Name: **container** Database Class: **Container** 


The value must be a boolean. If true, it means that this window will be used as a container in which some other application will be embedded (for example, a Tk toplevel can be embedded using the **-use** option). The window will support the appropriate window manager protocols for things like geometry requests. The window should not have any children of its own in this application. This option may not be changed with the **configure** widget command. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies the desired height for the window in any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. If this option is less than or equal to zero then the window will not request any size at all. 

Command-Line Name: **-menu** Database Name: **[menu](menu.htm)** Database Class: **[Menu](menu.htm)** 


Specifies a menu widget to be used as a menubar. On the Macintosh, the menubar will be displayed across the top of the main monitor. On Microsoft Windows and all UNIX platforms, the menu will appear across the toplevel window as part of the window dressing maintained by the window manager. 

Command-Line Name: **-screen** Database Name: Database Class: 


Specifies the screen on which to place the new window. Any valid screen name may be used, even one associated with a different display. Defaults to the same screen as its parent. This option is special in that it may not be specified via the option database, and it may not be modified with the **configure** widget command. 

Command-Line Name: **-use** Database Name: **use** Database Class: **Use** 


This option is used for embedding. If the value is not an empty string, it must be the window identifier of a container window, specified as a hexadecimal string like the ones returned by the **[winfo id](winfo.htm)** command. The toplevel widget will be created as a child of the given container instead of the root window for the screen. If the container window is in a Tk application, it must be a frame or toplevel widget for which the **-container** option was specified. This option may not be changed with the **configure** widget command. 

Command-Line Name: **-visual** Database Name: **visual** Database Class: **Visual** 


Specifies visual information for the new window in any of the forms accepted by **[Tk\_GetVisual](https://www.tcl.tk/man/tcl/TkLib/GetVisual.htm)**. If this option is not specified, the new window will use the default visual for its screen. The **-visual** option may not be modified with the **configure** widget command. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies the desired width for the window in any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. If this option is less than or equal to zero then the window will not request any size at all. 
 Description
-----------

 The **toplevel** command creates a new toplevel widget (given by the *pathName* argument). Additional options, described above, may be specified on the command line or in the option database to configure aspects of the toplevel such as its background color and relief. The **toplevel** command returns the path name of the new window.  A toplevel is similar to a frame except that it is created as a top-level window: its X parent is the root window of a screen rather than the logical parent from its path name. The primary purpose of a toplevel is to serve as a container for dialog boxes and other collections of widgets. The only visible features of a toplevel are its background color and an optional 3-D border to make the toplevel appear raised or sunken. 


Widget command
--------------

 The **toplevel** command creates a new Tcl command whose name is the same as the path name of the toplevel's window. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *PathName* is the name of the command, which is the same as the toplevel widget's path name. *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for toplevel widgets: 
 
*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **toplevel** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **toplevel** command. 

 Bindings
--------

 When a new toplevel is created, it has no default event bindings: toplevels are not intended to be interactive. See also
--------

 **[frame](frame.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/toplevel.htm>

ttk\_button
===========

  
[NAME](ttk_button.htm#M2) ttk::button — Widget that issues a command when pressed 
[SYNOPSIS](ttk_button.htm#M3) 
[DESCRIPTION](ttk_button.htm#M4) 
[STANDARD OPTIONS](ttk_button.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-compound, compound, Compound](ttk_widget.htm#M-compound) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-image, image, Image](ttk_widget.htm#M-image) 
[-state, state, State](ttk_widget.htm#M-state) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 
[-text, text, Text](ttk_widget.htm#M-text) 
[-textvariable, textVariable, Variable](ttk_widget.htm#M-textvariable) 
[-underline, underline, Underline](ttk_widget.htm#M-underline) 
[-width, width, Width](ttk_widget.htm#M-width) 










 
[WIDGET-SPECIFIC OPTIONS](ttk_button.htm#M6)  
[-command, command, Command](ttk_button.htm#M7) 
[-default, default, Default](ttk_button.htm#M8) 
[-width, width, Width](ttk_button.htm#M9) 


 
[WIDGET COMMAND](ttk_button.htm#M10)  
[*pathName* **invoke**](ttk_button.htm#M11) 
 
[STANDARD STYLES](ttk_button.htm#M12) 
[COMPATIBILITY OPTIONS](ttk_button.htm#M13)  
[-state, state, State](ttk_button.htm#M14) 
 
[SEE ALSO](ttk_button.htm#M15) 
[KEYWORDS](ttk_button.htm#M16) 









 Name
----

 ttk::button — Widget that issues a command when pressed Synopsis
--------

 **ttk::button** *pathName* ?*options*?  
 Description
-----------

 A **ttk::button** widget displays a textual label and/or image, and evaluates a command when pressed. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-compound, compound, Compound](ttk_widget.htm#M-compound)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-image, image, Image](ttk_widget.htm#M-image)** 
**[-state, state, State](ttk_widget.htm#M-state)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 
**[-text, text, Text](ttk_widget.htm#M-text)** 
**[-textvariable, textVariable, Variable](ttk_widget.htm#M-textvariable)** 
**[-underline, underline, Underline](ttk_widget.htm#M-underline)** 
**[-width, width, Width](ttk_widget.htm#M-width)** 










 Widget-specific options
-----------------------

  Command-Line Name: **-command** Database Name: **command** Database Class: **Command** 


A script to evaluate when the widget is invoked. 

Command-Line Name: **-default** Database Name: **default** Database Class: **Default** 


May be set to one of **normal**, **active**, or **disabled**. In a dialog box, one button may be designated the “default” button (meaning, roughly, “the one that gets invoked when the user presses <Enter>”). **active** indicates that this is currently the default button; **normal** means that it may become the default button, and **disabled** means that it is not defaultable. The default is **normal**.  Depending on the theme, the default button may be displayed with an extra highlight ring, or with a different border color. 



Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


If greater than zero, specifies how much space, in character widths, to allocate for the text label. If less than zero, specifies a minimum width. If zero or unspecified, the natural width of the text label is used. Note that some themes may specify a non-zero **-width** in the style. 
 Widget command
--------------

 In addition to the standard **cget**, **configure**, **identify**, **instate**, and **state** commands, buttons support the following additional widget commands: 
 
*pathName* **invoke**

 Invokes the command associated with the button. 

 Standard styles
---------------

 **Ttk::button** widgets support the **Toolbutton** style in all standard themes, which is useful for creating widgets for toolbars. Compatibility options
---------------------

  Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


May be set to **normal** or **disabled** to control the **disabled** state bit. This is a “write-only” option: setting it changes the widget state, but the **state** widget command does not affect the state option. 
 See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[button](button.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_button.htm>

ttk\_checkbutton
================

  
[NAME](ttk_checkbutton.htm#M2) ttk::checkbutton — On/off widget 
[SYNOPSIS](ttk_checkbutton.htm#M3) 
[DESCRIPTION](ttk_checkbutton.htm#M4) 
[STANDARD OPTIONS](ttk_checkbutton.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-compound, compound, Compound](ttk_widget.htm#M-compound) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-image, image, Image](ttk_widget.htm#M-image) 
[-state, state, State](ttk_widget.htm#M-state) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 
[-text, text, Text](ttk_widget.htm#M-text) 
[-textvariable, textVariable, Variable](ttk_widget.htm#M-textvariable) 
[-underline, underline, Underline](ttk_widget.htm#M-underline) 
[-width, width, Width](ttk_widget.htm#M-width) 










 
[WIDGET-SPECIFIC OPTIONS](ttk_checkbutton.htm#M6)  
[-command, command, Command](ttk_checkbutton.htm#M7) 
[-offvalue, offValue, OffValue](ttk_checkbutton.htm#M8) 
[-onvalue, onValue, OnValue](ttk_checkbutton.htm#M9) 
[-variable, variable, Variable](ttk_checkbutton.htm#M10) 



 
[WIDGET COMMAND](ttk_checkbutton.htm#M11)  
[*pathname* **invoke**](ttk_checkbutton.htm#M12) 
 
[WIDGET STATES](ttk_checkbutton.htm#M13) 
[STANDARD STYLES](ttk_checkbutton.htm#M14) 
[SEE ALSO](ttk_checkbutton.htm#M15) 
[KEYWORDS](ttk_checkbutton.htm#M16) 









 Name
----

 ttk::checkbutton — On/off widget Synopsis
--------

 **ttk::checkbutton** *pathName* ?*options*?  
 Description
-----------

 A **ttk::checkbutton** widget is used to show or change a setting. It has two states, selected and deselected. The state of the checkbutton may be linked to a Tcl variable. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-compound, compound, Compound](ttk_widget.htm#M-compound)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-image, image, Image](ttk_widget.htm#M-image)** 
**[-state, state, State](ttk_widget.htm#M-state)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 
**[-text, text, Text](ttk_widget.htm#M-text)** 
**[-textvariable, textVariable, Variable](ttk_widget.htm#M-textvariable)** 
**[-underline, underline, Underline](ttk_widget.htm#M-underline)** 
**[-width, width, Width](ttk_widget.htm#M-width)** 










 Widget-specific options
-----------------------

  Command-Line Name: **-command** Database Name: **command** Database Class: **Command** 


A Tcl script to execute whenever the widget is invoked. 

Command-Line Name: **-offvalue** Database Name: **offValue** Database Class: **OffValue** 


The value to store in the associated **-variable** when the widget is deselected. Defaults to **0**. 

Command-Line Name: **-onvalue** Database Name: **onValue** Database Class: **OnValue** 


The value to store in the associated **-variable** when the widget is selected. Defaults to **1**. 

Command-Line Name: **-variable** Database Name: **variable** Database Class: **Variable** 


The name of a global variable whose value is linked to the widget. Defaults to the widget pathname if not specified. 
 Widget command
--------------

 In addition to the standard **cget**, **configure**, **identify**, **instate**, and **state** commands, checkbuttons support the following additional widget commands: 
 
*pathname* **invoke**

 Toggles between the selected and deselected states and evaluates the associated **-command**. If the widget is currently selected, sets the **-variable** to the **-offvalue** and deselects the widget; otherwise, sets the **-variable** to the **-onvalue** Returns the result of the **-command**. 

 Widget states
-------------

 The widget does not respond to user input if the **disabled** state is set. The widget sets the **selected** state whenever the linked **-variable** is set to the widget's **-onvalue**, and clears it otherwise. The widget sets the **alternate** state whenever the linked **-variable** is unset. (The **alternate** state may be used to indicate a “tri-state” or “indeterminate” selection.) Standard styles
---------------

 **Ttk::checkbutton** widgets support the **Toolbutton** style in all standard themes, which is useful for creating widgets for toolbars. See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[ttk::radiobutton](ttk_radiobutton.htm)**, **[checkbutton](checkbutton.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_checkbutton.htm>

ttk\_image
==========

  
[NAME](ttk_image.htm#M2) ttk\_image — Define an element based on an image 
[SYNOPSIS](ttk_image.htm#M3) 
[DESCRIPTION](ttk_image.htm#M4) 
[OPTIONS](ttk_image.htm#M5)  
[**-border** *padding*](ttk_image.htm#M6) 
[**-height** *height*](ttk_image.htm#M7) 
[**-padding** *padding*](ttk_image.htm#M8) 
[**-sticky** *spec*](ttk_image.htm#M9) 
[**-width** *width*](ttk_image.htm#M10) 




 
[IMAGE STRETCHING](ttk_image.htm#M11) 
[EXAMPLE](ttk_image.htm#M12) 
[SEE ALSO](ttk_image.htm#M13) 
[KEYWORDS](ttk_image.htm#M14) 







 Name
----

 ttk\_image — Define an element based on an image Synopsis
--------

 **ttk::style element create** *name* **[image](image.htm)** *imageSpec* ?*options*?  
 Description
-----------

 The *image* element factory creates a new element in the current theme whose visual appearance is determined by Tk images. *imageSpec* is a list of one or more elements. The first element is the default image name. The rest of the list is a sequence of *statespec / value* pairs specifying other images to use when the element is in a particular state or combination of states. Options
-------

 Valid *options* are: 
 
**-border** *padding*

 *padding* is a list of up to four integers, specifying the left, top, right, and bottom borders, respectively. See **[IMAGE STRETCHING](#M11)**, below. 


**-height** *height*

 Specifies a minimum height for the element. If less than zero, the base image's height is used as a default. 


**-padding** *padding*

 Specifies the element's interior padding. Defaults to **-border** if not specified. 


**-sticky** *spec*

 Specifies how the image is placed within the final parcel. *spec* contains zero or more characters “n”, “s”, “w”, or “e”. 


**-width** *width*

 Specifies a minimum width for the element. If less than zero, the base image's width is used as a default. 

 Image stretching
----------------

 If the element's allocated parcel is larger than the image, the image will be placed in the parcel based on the **-sticky** option. If the image needs to stretch horizontally (i.e., **-sticky ew**) or vertically (**-sticky ns**), subregions of the image are replicated to fill the parcel based on the **-border** option. The **-border** divides the image into 9 regions: four fixed corners, top and left edges (which may be tiled horizontally), left and right edges (which may be tiled vertically), and the central area (which may be tiled in both directions). Example
-------

 
```
set img1 [image create photo -file button.png]
set img2 [image create photo -file button-pressed.png]
set img3 [image create photo -file button-active.png]
style element create Button.button image \
    [list $img1  pressed $img2  active $img3] \
    -border {2 4} -sticky we
```
 See also
--------

 **[ttk::intro](ttk_intro.htm)**, **[ttk::style](ttk_style.htm)**, **[ttk\_vsapi](ttk_vsapi.htm)**, **[image](image.htm)**, **[photo](photo.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_image.htm>

ttk\_vsapi
==========

  
[NAME](ttk_vsapi.htm#M2) ttk\_vsapi — Define a Microsoft Visual Styles element 
[SYNOPSIS](ttk_vsapi.htm#M3) 
[DESCRIPTION](ttk_vsapi.htm#M4) 
[OPTIONS](ttk_vsapi.htm#M5)  
[**-padding** *padding*](ttk_vsapi.htm#M6) 
[**-margins** *padding*](ttk_vsapi.htm#M7) 
[**-width** *width*](ttk_vsapi.htm#M8) 
[**-height** *height*](ttk_vsapi.htm#M9) 



 
[STATE MAP](ttk_vsapi.htm#M10) 
[EXAMPLE](ttk_vsapi.htm#M11) 
[SEE ALSO](ttk_vsapi.htm#M12) 
[KEYWORDS](ttk_vsapi.htm#M13) 







 Name
----

 ttk\_vsapi — Define a Microsoft Visual Styles element Synopsis
--------

 **ttk::style element create** *name* **vsapi** *className* *partId* ?*stateMap*? ?*options*?  
 Description
-----------

 The **vsapi** element factory creates a new element in the current theme whose visual appearance is drawn using the Microsoft Visual Styles API which is responsible for the themed styles on Windows XP and Vista. This factory permits any of the Visual Styles parts to be declared as Ttk elements that can then be included in a style layout to modify the appearance of Ttk widgets.  *className* and *partId* are required parameters and specify the Visual Styles class and part as given in the Microsoft documentation. The *stateMap* may be provided to map Ttk states to Visual Styles API states (see **[STATE MAP](#M10)**). 


Options
-------

 Valid *options* are: 
 
**-padding** *padding*

 Specify the element's interior padding. *padding* is a list of up to four integers specifying the left, top, right and bottom padding quantities respectively. This option may not be mixed with any other options. 


**-margins** *padding*

 Specifies the elements exterior padding. *padding* is a list of up to four integers specifying the left, top, right and bottom padding quantities respectively. This option may not be mixed with any other options. 


**-width** *width*

 Specifies the height for the element. If this option is set then the Visual Styles API will not be queried for the recommended size or the part. If this option is set then **-height** should also be set. The **-width** and **-height** options cannot be mixed with the **-padding** or **-margins** options. 


**-height** *height*

 Specifies the height of the element. See the comments for **-width**. 

 State map
---------

 The *stateMap* parameter is a list of ttk states and the corresponding Visual Styles API state value. This permits the element appearance to respond to changes in the widget state such as becoming active or being pressed. The list should be as described for the **[ttk::style map](ttk_style.htm)** command but note that the last pair in the list should be the default state and is typically and empty list and 1. Unfortunately all the Visual Styles parts have different state values and these must be looked up either in the Microsoft documentation or more likely in the header files. The original header to use was *tmschema.h*, but in more recent versions of the Windows Development Kit this is *vssym32.h*.  If no *stateMap* parameter is given there is an implicit default map of {{} 1} 


Example
-------

 Create a correctly themed close button by changing the layout of a **[ttk::button](ttk_button.htm)**(n). This uses the WINDOW part WP\_SMALLCLOSEBUTTON and as documented the states CBS\_DISABLED, CBS\_HOT, CBS\_NORMAL and CBS\_PUSHED are mapped from ttk states. 
```
ttk::style element create smallclose **vsapi** WINDOW 19 \
    {disabled 4 pressed 3 active 2 {} 1}
ttk::style layout CloseButton {CloseButton.smallclose -sticky news}
pack [ttk::button .close -style CloseButton]
```
  Change the appearance of a **[ttk::checkbutton](ttk_checkbutton.htm)**(n) to use the Explorer pin part EBP\_HEADERPIN. 



```
ttk::style element create pin **vsapi** EXPLORERBAR 3 {
    {pressed !selected} 3
    {active !selected} 2
    {pressed selected} 6
    {active selected} 5
    {selected} 4
    {} 1
}
ttk::style layout Explorer.Pin {Explorer.Pin.pin -sticky news}
pack [ttk::checkbutton .pin -style Explorer.Pin]
```
 See also
--------

 **[ttk::intro](ttk_intro.htm)**, **[ttk::widget](ttk_widget.htm)**, **[ttk::style](ttk_style.htm)**, **[ttk\_image](ttk_image.htm)** Copyright © 2008 Pat Thoyts 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_vsapi.htm>

focus
=====

  
[NAME](focus.htm#M2) focus — Manage the input focus 
[SYNOPSIS](focus.htm#M3) 
[DESCRIPTION](focus.htm#M4)  
[**focus**](focus.htm#M5) 
[**focus** *window*](focus.htm#M6) 
[**focus -displayof** *window*](focus.htm#M7) 
[**focus -force** *window*](focus.htm#M8) 
[**focus -lastfor** *window*](focus.htm#M9) 




 
[QUIRKS](focus.htm#M10) 
[EXAMPLE](focus.htm#M11) 
[KEYWORDS](focus.htm#M12) 





 Name
----

 focus — Manage the input focus Synopsis
--------

 **focus**  
 **focus** *window*  
 **focus** *option* ?*arg arg ...*?  
 Description
-----------

 The **focus** command is used to manage the Tk input focus. At any given time, one window on each display is designated as the *focus window*; any key press or key release events for the display are sent to that window. It is normally up to the window manager to redirect the focus among the top-level windows of a display. For example, some window managers automatically set the input focus to a top-level window whenever the mouse enters it; others redirect the input focus only when the user clicks on a window. Usually the window manager will set the focus only to top-level windows, leaving it up to the application to redirect the focus among the children of the top-level.  Tk remembers one focus window for each top-level (the most recent descendant of that top-level to receive the focus); when the window manager gives the focus to a top-level, Tk automatically redirects it to the remembered window. Within a top-level Tk uses an *explicit* focus model by default. Moving the mouse within a top-level does not normally change the focus; the focus changes only when a widget decides explicitly to claim the focus (e.g., because of a button click), or when the user types a key such as Tab that moves the focus. 


 The Tcl procedure **tk\_focusFollowsMouse** may be invoked to create an *implicit* focus model: it reconfigures Tk so that the focus is set to a window whenever the mouse enters it. The Tcl procedures **tk\_focusNext** and **tk\_focusPrev** implement a focus order among the windows of a top-level; they are used in the default bindings for Tab and Shift-Tab, among other things. 


 The **focus** command can take any of the following forms: 


 **focus**
 Returns the path name of the focus window on the display containing the application's main window, or an empty string if no window in this application has the focus on that display. Note: it is better to specify the display explicitly using **-displayof** (see below) so that the code will work in applications using multiple displays. 


**focus** *window*

 If the application currently has the input focus on *window*'s display, this command resets the input focus for *window*'s display to *window* and returns an empty string. If the application does not currently have the input focus on *window*'s display, *window* will be remembered as the focus for its top-level; the next time the focus arrives at the top-level, Tk will redirect it to *window*. If *window* is an empty string then the command does nothing. 


**focus -displayof** *window*

 Returns the name of the focus window on the display containing *window*. If the focus window for *window*'s display is not in this application, the return value is an empty string. 


**focus -force** *window*

 Sets the focus of *window*'s display to *window*, even if the application does not currently have the input focus for the display. This command should be used sparingly, if at all. In normal usage, an application should not claim the focus for itself; instead, it should wait for the window manager to give it the focus. If *window* is an empty string then the command does nothing. 


**focus -lastfor** *window*

 Returns the name of the most recent window to have the input focus among all the windows in the same top-level as *window*. If no window in that top-level has ever had the input focus, or if the most recent focus window has been deleted, then the name of the top-level is returned. The return value is the window that will receive the input focus the next time the window manager gives the focus to the top-level. 

 Quirks
------

 When an internal window receives the input focus, Tk does not actually set the X focus to that window; as far as X is concerned, the focus will stay on the top-level window containing the window with the focus. However, Tk generates FocusIn and FocusOut events just as if the X focus were on the internal window. This approach gets around a number of problems that would occur if the X focus were actually moved; the fact that the X focus is on the top-level is invisible unless you use C code to query the X server directly. Example
-------

 To make a window that only participates in the focus traversal ring when a variable is set, add the following bindings to the widgets *before* and *after* it in that focus ring: 
```
button .before -text "Before"
button .middle -text "Middle"
button .after  -text "After"
checkbutton .flag -variable traverseToMiddle -takefocus 0
pack .flag -side left
pack .before .middle .after
bind .before <Tab> {
   if {!$traverseToMiddle} {
      **focus** .after
      break
   }
}
bind .after <Shift-Tab> {
   if {!$traverseToMiddle} {
      **focus** .before
      break
   }
}
**focus** .before
```
 Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/focus.htm>

menu
====

  
[NAME](menu.htm#M2) menu, tk\_menuSetFocus — Create and manipulate 'menu' widgets and menubars 
[SYNOPSIS](menu.htm#M3) 
[STANDARD OPTIONS](menu.htm#M4)  
[-activebackground, activeBackground, Foreground](options.htm#M-activebackground) 
[-activeborderwidth, activeBorderWidth, BorderWidth](options.htm#M-activeborderwidth) 
[-activeforeground, activeForeground, Background](options.htm#M-activeforeground) 
[-background or -bg, background, Background](options.htm#M-background) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-relief, relief, Relief](options.htm#M-relief) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 










 
[WIDGET-SPECIFIC OPTIONS](menu.htm#M5)  
[-postcommand, postCommand, Command](menu.htm#M6) 
[-selectcolor, selectColor, Background](menu.htm#M7) 
[-tearoff, tearOff, TearOff](menu.htm#M8) 
[-tearoffcommand, tearOffCommand, TearOffCommand](menu.htm#M9) 
[-title, title, Title](menu.htm#M10) 
[-type, type, Type](menu.htm#M11) 





 
[INTRODUCTION](menu.htm#M12) 
[TYPES OF ENTRIES](menu.htm#M13) 
[COMMAND ENTRIES](menu.htm#M14) 
[SEPARATOR ENTRIES](menu.htm#M15) 
[CHECKBUTTON ENTRIES](menu.htm#M16) 
[RADIOBUTTON ENTRIES](menu.htm#M17) 
[CASCADE ENTRIES](menu.htm#M18) 
[TEAR-OFF ENTRIES](menu.htm#M19) 
[MENUBARS](menu.htm#M20) 
[SPECIAL MENUS IN MENUBARS](menu.htm#M21) 
[CLONES](menu.htm#M22) 
[WIDGET COMMAND](menu.htm#M23)  
[**active**](menu.htm#M24) 
[**end**](menu.htm#M25) 
[**last**](menu.htm#M26) 
[**none**](menu.htm#M27) 
[**@***number*](menu.htm#M28) 
[*number*](menu.htm#M29) 
[*pattern*](menu.htm#M30) 






  
[*pathName* **activate** *index*](menu.htm#M31) 
[*pathName* **add** *type* ?*option value option value ...*?](menu.htm#M32) 
[*pathName* **cget** *option*](menu.htm#M33) 
[*pathName* **clone** *newPathname* ?*cloneType*?](menu.htm#M34) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](menu.htm#M35) 
[*pathName* **delete** *index1* ?*index2*?](menu.htm#M36) 
[*pathName* **entrycget** *index option*](menu.htm#M37) 
[*pathName* **entryconfigure** *index* ?*options...*?](menu.htm#M38) 
[*pathName* **index** *index*](menu.htm#M39) 
[*pathName* **insert** *index type* ?*option value option value ...*?](menu.htm#M40) 
[*pathName* **invoke** *index*](menu.htm#M41) 
[*pathName* **post** *x y*](menu.htm#M42) 
[*pathName* **postcascade** *index*](menu.htm#M43) 
[*pathName* **type** *index*](menu.htm#M44) 
[*pathName* **unpost**](menu.htm#M45) 
[*pathName* **xposition** *index*](menu.htm#M46) 
[*pathName* **yposition** *index*](menu.htm#M47) 
















 
[MENU ENTRY OPTIONS](menu.htm#M48)  
[**-activebackground** *value*](menu.htm#M49) 
[**-activeforeground** *value*](menu.htm#M50) 
[**-accelerator** *value*](menu.htm#M51) 
[**-background** *value*](menu.htm#M52) 
[**-bitmap** *value*](menu.htm#M53) 
[**-columnbreak** *value*](menu.htm#M54) 
[**-command** *value*](menu.htm#M55) 
[**-compound** *value*](menu.htm#M56) 
[**-font** *value*](menu.htm#M57) 
[**-foreground** *value*](menu.htm#M58) 
[**-hidemargin** *value*](menu.htm#M59) 
[**-image** *value*](menu.htm#M60) 
[**-indicatoron** *value*](menu.htm#M61) 
[**-label** *value*](menu.htm#M62) 
[**-menu** *value*](menu.htm#M63) 
[**-offvalue** *value*](menu.htm#M64) 
[**-onvalue** *value*](menu.htm#M65) 
[**-selectcolor** *value*](menu.htm#M66) 
[**-selectimage** *value*](menu.htm#M67) 
[**-state** *value*](menu.htm#M68) 
[**-underline** *value*](menu.htm#M69) 
[**-value** *value*](menu.htm#M70) 
[**-variable** *value*](menu.htm#M71) 






















 
[MENU CONFIGURATIONS](menu.htm#M72)  
[**Pulldown Menus in Menubar**](menu.htm#M73) 
[**Pulldown Menus in Menu Buttons**](menu.htm#M74) 
[**Popup Menus**](menu.htm#M75) 
[**Option Menus**](menu.htm#M76) 
[**Torn-off Menus**](menu.htm#M77) 




 
[DEFAULT BINDINGS](menu.htm#M78) 
[BUGS](menu.htm#M79) 
[SEE ALSO](menu.htm#M80) 
[KEYWORDS](menu.htm#M81) 





















 Name
----

 menu, tk\_menuSetFocus — Create and manipulate 'menu' widgets and menubars Synopsis
--------

 **menu** *pathName* ?*options*?  
 **tk\_menuSetFocus** *pathName*  
 Standard options
----------------

  
**[-activebackground, activeBackground, Foreground](options.htm#M-activebackground)** 
**[-activeborderwidth, activeBorderWidth, BorderWidth](options.htm#M-activeborderwidth)** 
**[-activeforeground, activeForeground, Background](options.htm#M-activeforeground)** 
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 










 Widget-specific options
-----------------------

  Command-Line Name: **-postcommand** Database Name: **postCommand** Database Class: **Command** 


If this option is specified then it provides a Tcl command to execute each time the menu is posted. The command is invoked by the **post** widget command before posting the menu. Note that in Tk 8.0 on Macintosh and Windows, all post-commands in a system of menus are executed before any of those menus are posted. This is due to the limitations in the individual platforms' menu managers. 

Command-Line Name: **-selectcolor** Database Name: **selectColor** Database Class: **Background** 


For menu entries that are check buttons or radio buttons, this option specifies the color to display in the indicator when the check button or radio button is selected. 

Command-Line Name: **-tearoff** Database Name: **tearOff** Database Class: **TearOff** 


This option must have a proper boolean value, which specifies whether or not the menu should include a tear-off entry at the top. If so, it will exist as entry 0 of the menu and the other entries will number starting at 1. The default menu bindings arrange for the menu to be torn off when the tear-off entry is invoked. This option is ignored under Aqua/Mac OS X, where menus cannot be torn off. 

Command-Line Name: **-tearoffcommand** Database Name: **tearOffCommand** Database Class: **TearOffCommand** 


If this option has a non-empty value, then it specifies a Tcl command to invoke whenever the menu is torn off. The actual command will consist of the value of this option, followed by a space, followed by the name of the menu window, followed by a space, followed by the name of the name of the torn off menu window. For example, if the option's value is “**a b**” and menu **.x.y** is torn off to create a new menu **.x.tearoff1**, then the command “**a b .x.y .x.tearoff1**” will be invoked. This option is ignored under Aqua/Mac OS X, where menus cannot be torn off. 

Command-Line Name: **-title** Database Name: **title** Database Class: **Title** 


The string will be used to title the window created when this menu is torn off. If the title is NULL, then the window will have the title of the menubutton or the text of the cascade item from which this menu was invoked. 

Command-Line Name: **-type** Database Name: **type** Database Class: **Type** 


This option can be one of **menubar**, **tearoff**, or **normal**, and is set when the menu is created. While the string returned by the configuration database will change if this option is changed, this does not affect the menu widget's behavior. This is used by the cloning mechanism and is not normally set outside of the Tk library. 
 Introduction
------------

 The **menu** command creates a new top-level window (given by the *pathName* argument) and makes it into a menu widget. That menu widget can either be used as a pop-up window or applied to a **[toplevel](toplevel.htm)** (with its **-menu** option) to make it into the menubar for that toplevel. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the menu such as its colors and font. The **menu** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  A menu is a widget that displays a collection of one-line entries arranged in one or more columns. There exist several different types of entries, each with different properties. Entries of different types may be combined in a single menu. Menu entries are not the same as entry widgets. In fact, menu entries are not even distinct widgets; the entire menu is one widget. 


 Menu entries are displayed with up to three separate fields. The main field is a label in the form of a text string, a bitmap, or an image, controlled by the **-label**, **-bitmap**, and **-image** options for the entry. If the **-accelerator** option is specified for an entry then a second textual field is displayed to the right of the label. The accelerator typically describes a keystroke sequence that may be typed in the application to cause the same result as invoking the menu entry. The third field is an *indicator*. The indicator is present only for checkbutton or radiobutton entries. It indicates whether the entry is selected or not, and is displayed to the left of the entry's string. 


 In normal use, an entry becomes active (displays itself differently) whenever the mouse pointer is over the entry. If a mouse button is released over the entry then the entry is *invoked*. The effect of invocation is different for each type of entry; these effects are described below in the sections on individual entries. 


 Entries may be *disabled*, which causes their labels and accelerators to be displayed with dimmer colors. The default menu bindings will not allow a disabled entry to be activated or invoked. Disabled entries may be re-enabled, at which point it becomes possible to activate and invoke them again. 


 Whenever a menu's active entry is changed, a <<MenuSelect>> virtual event is send to the menu. The active item can then be queried from the menu, and an action can be taken, such as setting context-sensitive help text for the entry. 


Types of entries
----------------

 ### Command entries

 The most common kind of menu entry is a command entry, which behaves much like a button widget. When a command entry is invoked, a Tcl command is executed. The Tcl command is specified with the **-command** option. ### Separator entries

 A separator is an entry that is displayed as a horizontal dividing line. A separator may not be activated or invoked, and it has no behavior other than its display appearance. ### Checkbutton entries

 A checkbutton menu entry behaves much like a checkbutton widget. When it is invoked it toggles back and forth between the selected and deselected states. When the entry is selected, a particular value is stored in a particular global variable (as determined by the **-onvalue** and **-variable** options for the entry); when the entry is deselected another value (determined by the **-offvalue** option) is stored in the global variable. An indicator box is displayed to the left of the label in a checkbutton entry. If the entry is selected then the indicator's center is displayed in the color given by the **-selectcolor** option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If a **-command** option is specified for a checkbutton entry, then its value is evaluated as a Tcl command each time the entry is invoked; this happens after toggling the entry's selected state. ### Radiobutton entries

 A radiobutton menu entry behaves much like a radiobutton widget. Radiobutton entries are organized in groups of which only one entry may be selected at a time. Whenever a particular entry becomes selected it stores a particular value into a particular global variable (as determined by the **-value** and **-variable** options for the entry). This action causes any previously-selected entry in the same group to deselect itself. Once an entry has become selected, any change to the entry's associated variable will cause the entry to deselect itself. Grouping of radiobutton entries is determined by their associated variables: if two entries have the same associated variable then they are in the same group. An indicator diamond is displayed to the left of the label in each radiobutton entry. If the entry is selected then the indicator's center is displayed in the color given by the **-selectcolor** option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If a **-command** option is specified for a radiobutton entry, then its value is evaluated as a Tcl command each time the entry is invoked; this happens after selecting the entry. ### Cascade entries

 A cascade entry is one with an associated menu (determined by the **-menu** option). Cascade entries allow the construction of cascading menus. The **postcascade** widget command can be used to post and unpost the associated menu just next to of the cascade entry. The associated menu must be a child of the menu containing the cascade entry (this is needed in order for menu traversal to work correctly).  A cascade entry posts its associated menu by invoking a Tcl command of the form 



```
*menu* **post** *x y*
```
 where *menu* is the path name of the associated menu, and *x* and *y* are the root-window coordinates of the upper-right corner of the cascade entry. On Unix, the lower-level menu is unposted by executing a Tcl command with the form 
```
*menu* **unpost**
```
 where *menu* is the name of the associated menu. On other platforms, the platform's native code takes care of unposting the menu.  If a **-command** option is specified for a cascade entry then it is evaluated as a Tcl command whenever the entry is invoked. This is not supported on Windows. 


### Tear-off entries

 A tear-off entry appears at the top of the menu if enabled with the **-tearoff** option. It is not like other menu entries in that it cannot be created with the **add** widget command and cannot be deleted with the **delete** widget command. When a tear-off entry is created it appears as a dashed line at the top of the menu. Under the default bindings, invoking the tear-off entry causes a torn-off copy to be made of the menu and all of its submenus. Menubars
--------

 Any menu can be set as a menubar for a toplevel window (see **[toplevel](toplevel.htm)** command for syntax). On the Macintosh, whenever the toplevel is in front, this menu's cascade items will appear in the menubar across the top of the main monitor. On Windows and Unix, this menu's items will be displayed in a menubar across the top of the window. These menus will behave according to the interface guidelines of their platforms. For every menu set as a menubar, a clone menu is made. See the **[CLONES](#M22)** section for more information.  As noted, menubars may behave differently on different platforms. One example of this concerns the handling of checkbuttons and radiobuttons within the menu. While it is permitted to put these menu elements on menubars, they may not be drawn with indicators on some platforms, due to system restrictions. 


### Special menus in menubars

 Certain menus in a menubar will be treated specially. On the Macintosh, access to the special Application, Window and Help menus is provided. On Windows, access to the Windows System menu in each window is provided. On X Windows, a special right-justified help menu may be provided if Motif menu compatibility is enabled. In all cases, these menus must be created with the command name of the menubar menu concatenated with the special name. So for a menubar named .menubar, on the Macintosh, the special menus would be .menubar.apple, .menubar.window and .menubar.help; on Windows, the special menu would be .menubar.system; on X Windows, the help menu would be .menubar.help.  When Tk sees a .menubar.apple menu as the first menu in a menubar on the Macintosh, that menu's contents make up the first items of the Application menu whenever the window containing the menubar is in front. After all of the Tk-defined items, the menu will have a separator, followed by all standard Application menu items. Such a .apple menu must be present in a menu when that menu is first configured as a toplevel's menubar, otherwise a default application menu (hidden from Tk) will be inserted into the menubar at that time and subsequent addition of a .apple menu will no longer result in it becoming the Application menu. 


 When Tk sees a .menubar.window menu on the Macintosh, the menu's contents are inserted into the standard Window menu of the user's menubar whenever the window's menubar is in front. The first items in the menu are provided by Mac OS X, and the names of the current toplevels are automatically appended after all the Tk-defined items and a separator. 


 When Tk sees a .menubar.help menu on the Macintosh, the menu's contents are appended to the standard Help menu of the user's menubar whenever the window's menubar is in front. The first items in the menu are provided by Mac OS X. 


 When Tk sees a System menu on Windows, its items are appended to the system menu that the menubar is attached to. This menu is tied to the application icon and can be invoked with the mouse or by typing Alt+Spacebar. Due to limitations in the Windows API, any font changes, colors, images, bitmaps, or tearoff images will not appear in the system menu. 


 When Tk sees a Help menu on X Windows and Motif menu compatibility is enabled the menu is moved to be last in the menubar and is right justified. Motif menu compatibility is enabled by setting the Tk option **\*Menu.useMotifHelp** to true or by calling **tk::classic::restore menu**. 


Clones
------

 When a menu is set as a menubar for a toplevel window, or when a menu is torn off, a clone of the menu is made. This clone is a menu widget in its own right, but it is a child of the original. Changes in the configuration of the original are reflected in the clone. Additionally, any cascades that are pointed to are also cloned so that menu traversal will work right. Clones are destroyed when either the tearoff or menubar goes away, or when the original menu is destroyed. Widget command
--------------

 The **menu** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command.  Many of the widget commands for a menu take as one argument an indicator of which entry of the menu to operate on. These indicators are called *index*es and may be specified in any of the following forms: 


 **active**
 Indicates the entry that is currently active. If no entry is active then this form is equivalent to **none**. This form may not be abbreviated. 

**end**
 Indicates the bottommost entry in the menu. If there are no entries in the menu then this form is equivalent to **none**. This form may not be abbreviated. 

**last**
 Same as **end**. 

**none**
 Indicates “no entry at all”; this is used most commonly with the **activate** option to deactivate all the entries in the menu. In most cases the specification of **none** causes nothing to happen in the widget command. This form may not be abbreviated. 


**@***number*

 In this form, *number* is treated as a y-coordinate in the menu's window; the entry closest to that y-coordinate is used. For example, “**@0**” indicates the top-most entry in the window. 

*number*
 Specifies the entry numerically, where 0 corresponds to the top-most entry of the menu, 1 to the entry below it, and so on. 

*pattern*
 If the index does not satisfy one of the above forms then this form is used. *Pattern* is pattern-matched against the label of each entry in the menu, in order from the top down, until a matching entry is found. The rules of **[string match](../tclcmd/string.htm)** are used. 

  If the index could match more than one of the above forms, then the form earlier in the above list takes precedence. 


 The following widget commands are possible for menu widgets: 


 
*pathName* **activate** *index*

 Change the state of the entry indicated by *index* to **active** and redisplay it using its active colors. Any previously-active entry is deactivated. If *index* is specified as **none**, or if the specified entry is disabled, then the menu ends up with no active entry. Returns an empty string. 


*pathName* **add** *type* ?*option value option value ...*?
 Add a new entry to the bottom of the menu. The new entry's type is given by *type* and must be one of **cascade**, **checkbutton**, **command**, **radiobutton**, or **separator**, or a unique abbreviation of one of the above. If additional arguments are present, they specify the options listed in the **[MENU ENTRY OPTIONS](#M48)** section below. The **add** widget command returns an empty string. 


*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **menu** command. 


*pathName* **clone** *newPathname* ?*cloneType*?
 Makes a clone of the current menu named *newPathName*. This clone is a menu in its own right, but any changes to the clone are propagated to the original menu and vice versa. *cloneType* can be **normal**, **menubar**, or **tearoff**. Should not normally be called outside of the Tk library. See the **[CLONES](#M22)** section for more information. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **menu** command. 


*pathName* **delete** *index1* ?*index2*?
 Delete all of the menu entries between *index1* and *index2* inclusive. If *index2* is omitted then it defaults to *index1*. Attempts to delete a tear-off menu entry are ignored (instead, you should change the **-tearoff** option to remove the tear-off entry). 


*pathName* **entrycget** *index option*

 Returns the current value of a configuration option for the entry given by *index*. *Option* may have any of the names described in the **[MENU ENTRY OPTIONS](#M48)** section below. 


*pathName* **entryconfigure** *index* ?*options...*?
 This command is similar to the **configure** command, except that it applies to the options for an individual entry, whereas **configure** applies to the options for the menu as a whole. *Options* may have any of the values described in the **[MENU ENTRY OPTIONS](#M48)** section below. If *options* are specified, options are modified as indicated in the command and the command returns an empty string. If no *options* are specified, returns a list describing the current options for entry *index* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). 


*pathName* **index** *index*

 Returns the numerical index corresponding to *index*, or **none** if *index* was specified as **none**. 


*pathName* **insert** *index type* ?*option value option value ...*?
 Same as the **add** widget command except that it inserts the new entry just before the entry given by *index*, instead of appending to the end of the menu. The *type*, *option*, and *value* arguments have the same interpretation as for the **add** widget command. It is not possible to insert new menu entries before the tear-off entry, if the menu has one. 


*pathName* **invoke** *index*

 Invoke the action of the menu entry. See the sections on the individual entries above for details on what happens. If the menu entry is disabled then nothing happens. If the entry has a command associated with it then the result of that command is returned as the result of the **invoke** widget command. Otherwise the result is an empty string. Note: invoking a menu entry does not automatically unpost the menu; the default bindings normally take care of this before invoking the **invoke** widget command. 


*pathName* **post** *x y*

 Arrange for the menu to be displayed on the screen at the root-window coordinates given by *x* and *y*. These coordinates are adjusted if necessary to guarantee that the entire menu is visible on the screen. This command normally returns an empty string. If the **-postcommand** option has been specified, then its value is executed as a Tcl script before posting the menu and the result of that script is returned as the result of the **post** widget command. If an error returns while executing the command, then the error is returned without posting the menu. 


*pathName* **postcascade** *index*

 Posts the submenu associated with the cascade entry given by *index*, and unposts any previously posted submenu. If *index* does not correspond to a cascade entry, or if *pathName* is not posted, the command has no effect except to unpost any currently posted submenu. 


*pathName* **type** *index*

 Returns the type of the menu entry given by *index*. This is the *type* argument passed to the **add** or **insert** widget command when the entry was created, such as **command** or **separator**, or **tearoff** for a tear-off entry. 


*pathName* **unpost**

 Unmap the window so that it is no longer displayed. If a lower-level cascaded menu is posted, unpost that menu. Returns an empty string. This subcommand does not work on Windows and the Macintosh, as those platforms have their own way of unposting menus. 


*pathName* **xposition** *index*

 Returns a decimal string giving the x-coordinate within the menu window of the leftmost pixel in the entry specified by *index*. 


*pathName* **yposition** *index*

 Returns a decimal string giving the y-coordinate within the menu window of the topmost pixel in the entry specified by *index*. 

 Menu entry options
------------------

 The following options are allowed on menu entries. Most options are not supported by all entry types. 
 
**-activebackground** *value*

 Specifies a background color to use for displaying this entry when it is active. If this option is specified as an empty string (the default), then the **-activebackground** option for the overall menu is used. If the **tk\_strictMotif** variable has been set to request strict Motif compliance, then this option is ignored and the **-background** option is used in its place. This option is not available for separator or tear-off entries. 


**-activeforeground** *value*

 Specifies a foreground color to use for displaying this entry when it is active. If this option is specified as an empty string (the default), then the **-activeforeground** option for the overall menu is used. This option is not available for separator or tear-off entries. 


**-accelerator** *value*

 Specifies a string to display at the right side of the menu entry. Normally describes an accelerator keystroke sequence that may be typed to invoke the same function as the menu entry. This option is not available for separator or tear-off entries. 


**-background** *value*

 Specifies a background color to use for displaying this entry when it is in the normal state (neither active nor disabled). If this option is specified as an empty string (the default), then the **-background** option for the overall menu is used. This option is not available for separator or tear-off entries. 


**-bitmap** *value*

 Specifies a bitmap to display in the menu instead of a textual label, in any of the forms accepted by **[Tk\_GetBitmap](https://www.tcl.tk/man/tcl/TkLib/GetBitmap.htm)**. This option overrides the **-label** option (as controlled by the **-compound** option) but may be reset to an empty string to enable a textual label to be displayed. If a **-image** option has been specified, it overrides **-bitmap**. This option is not available for separator or tear-off entries. 


**-columnbreak** *value*

 When this option is zero, the entry appears below the previous entry. When this option is one, the entry appears at the top of a new column in the menu. This option is ignored on Aqua/Mac OS X, where menus are always a single column. 


**-command** *value*

 Specifies a Tcl command to execute when the menu entry is invoked. Not available for separator or tear-off entries. 


**-compound** *value*

 Specifies whether the menu entry should display both an image and text, and if so, where the image should be placed relative to the text. Valid values for this option are **bottom**, **center**, **left**, **none**, **right** and **top**. The default value is **none**, meaning that the button will display either an image or text, depending on the values of the **-image** and **-bitmap** options. 


**-font** *value*

 Specifies the font to use when drawing the label or accelerator string in this entry. If this option is specified as an empty string (the default) then the **-font** option for the overall menu is used. This option is not available for separator or tear-off entries. 


**-foreground** *value*

 Specifies a foreground color to use for displaying this entry when it is in the normal state (neither active nor disabled). If this option is specified as an empty string (the default), then the **-foreground** option for the overall menu is used. This option is not available for separator or tear-off entries. 


**-hidemargin** *value*

 Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. 1 indicates that the margin for the entry is hidden; 0 means that the margin is used. 


**-image** *value*

 Specifies an image to display in the menu instead of a text string or bitmap. The image must have been created by some previous invocation of **[image create](image.htm)**. This option overrides the **-label** and **-bitmap** options (as controlled by the **-compound** option) but may be reset to an empty string to enable a textual or bitmap label to be displayed. This option is not available for separator or tear-off entries. 


**-indicatoron** *value*

 Available only for checkbutton and radiobutton entries. *Value* is a boolean that determines whether or not the indicator should be displayed. 


**-label** *value*

 Specifies a string to display as an identifying label in the menu entry. Not available for separator or tear-off entries. 


**-menu** *value*

 Available only for cascade entries. Specifies the path name of the submenu associated with this entry. The submenu must be a child of the menu. 


**-offvalue** *value*

 Available only for checkbutton entries. Specifies the value to store in the entry's associated variable when the entry is deselected. 


**-onvalue** *value*

 Available only for checkbutton entries. Specifies the value to store in the entry's associated variable when the entry is selected. 


**-selectcolor** *value*

 Available only for checkbutton and radiobutton entries. Specifies the color to display in the indicator when the entry is selected. If the value is an empty string (the default) then the **-selectcolor** option for the menu determines the indicator color. 


**-selectimage** *value*

 Available only for checkbutton and radiobutton entries. Specifies an image to display in the entry (in place of the **-image** option) when it is selected. *Value* is the name of an image, which must have been created by some previous invocation of **[image create](image.htm)**. This option is ignored unless the **-image** option has been specified. 


**-state** *value*

 Specifies one of three states for the entry: **normal**, **active**, or **disabled**. In normal state the entry is displayed using the **-foreground** option for the menu and the **-background** option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the **-activeforeground** option for the menu along with the **-activebackground** option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the **-disabledforeground** option for the menu and the **-background** option from the entry. This option is not available for separator entries. 


**-underline** *value*

 Specifies the integer index of a character to underline in the entry. This option is also queried by the default bindings and used to implement keyboard traversal. 0 corresponds to the first character of the text displayed in the entry, 1 to the next character, and so on. If a bitmap or image is displayed in the entry then this option is ignored. This option is not available for separator or tear-off entries. 


**-value** *value*

 Available only for radiobutton entries. Specifies the value to store in the entry's associated variable when the entry is selected. If an empty string is specified, then the **-label** option for the entry as the value to store in the variable. 


**-variable** *value*

 Available only for checkbutton and radiobutton entries. Specifies the name of a global variable to set when the entry is selected. For checkbutton entries the variable is also set when the entry is deselected. For radiobutton entries, changing the variable causes the currently-selected entry to deselect itself.  For checkbutton entries, the default value of this option is taken from the **-label** option, and for radiobutton entries a single fixed value is used. It is recommended that you always set the **-variable** option when creating either a checkbutton or a radiobutton. 



 Menu configurations
-------------------

 The default bindings support four different ways of using menus: 
 **Pulldown Menus in Menubar**
 This is the most common case. You create a menu widget that will become the menu bar. You then add cascade entries to this menu, specifying the pull down menus you wish to use in your menu bar. You then create all of the pulldowns. Once you have done this, specify the menu using the **-menu** option of the toplevel's widget command. See the **[toplevel](toplevel.htm)** manual entry for details. 

**Pulldown Menus in Menu Buttons**
 This is the compatible way to do menu bars. You create one menubutton widget for each top-level menu, and typically you arrange a series of menubuttons in a row in a menubar window. You also create the top-level menus and any cascaded submenus, and tie them together with **-menu** options in menubuttons and cascade menu entries. The top-level menu must be a child of the menubutton, and each submenu must be a child of the menu that refers to it. Once you have done this, the default bindings will allow users to traverse and invoke the tree of menus via its menubutton; see the **[menubutton](menubutton.htm)** manual entry for details. 

**Popup Menus**
 Popup menus typically post in response to a mouse button press or keystroke. You create the popup menus and any cascaded submenus, then you call the **[tk\_popup](popup.htm)** procedure at the appropriate time to post the top-level menu. 

**Option Menus**
 An option menu consists of a menubutton with an associated menu that allows you to select one of several values. The current value is displayed in the menubutton and is also stored in a global variable. Use the **tk\_optionMenu** procedure to create option menubuttons and their menus. 

**Torn-off Menus**
 You create a torn-off menu by invoking the tear-off entry at the top of an existing menu. The default bindings will create a new menu that is a copy of the original menu and leave it permanently posted as a top-level window. The torn-off menu behaves just the same as the original menu. 

 Default bindings
----------------

 Tk automatically creates class bindings for menus that give them the following default behavior: 
1. When the mouse enters a menu, the entry underneath the mouse cursor activates; as the mouse moves around the menu, the active entry changes to track the mouse.
2. When the mouse leaves a menu all of the entries in the menu deactivate, except in the special case where the mouse moves from a menu to a cascaded submenu.
3. When a button is released over a menu, the active entry (if any) is invoked. The menu also unposts unless it is a torn-off menu.
4. The Space and Return keys invoke the active entry and unpost the menu.
5. If any of the entries in a menu have letters underlined with the **-underline** option, then pressing one of the underlined letters (or its upper-case or lower-case equivalent) invokes that entry and unposts the menu.
6. The Escape key aborts a menu selection in progress without invoking any entry. It also unposts the menu unless it is a torn-off menu.
7. The Up and Down keys activate the next higher or lower entry in the menu. When one end of the menu is reached, the active entry wraps around to the other end.
8. The Left key moves to the next menu to the left. If the current menu is a cascaded submenu, then the submenu is unposted and the current menu entry becomes the cascade entry in the parent. If the current menu is a top-level menu posted from a menubutton, then the current menubutton is unposted and the next menubutton to the left is posted. Otherwise the key has no effect. The left-right order of menubuttons is determined by their stacking order: Tk assumes that the lowest menubutton (which by default is the first one created) is on the left.
9. The Right key moves to the next menu to the right. If the current entry is a cascade entry, then the submenu is posted and the current menu entry becomes the first entry in the submenu. Otherwise, if the current menu was posted from a menubutton, then the current menubutton is unposted and the next menubutton to the right is posted.

  Disabled menu entries are non-responsive: they do not activate and they ignore mouse button presses and releases. 


 Several of the bindings make use of the command **tk\_menuSetFocus**. It saves the current focus and sets the focus to its *pathName* argument, which is a menu widget. 


 The behavior of menus can be changed by defining new bindings for individual widgets or by redefining the class bindings. 


Bugs
----

 At present it is not possible to use the option database to specify values for the options to individual entries. See also
--------

 **[bind](bind.htm)**, **[menubutton](menubutton.htm)**, **[ttk::menubutton](ttk_menubutton.htm)**, **[toplevel](toplevel.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/menu.htm>

ttk\_widget
===========

  
[NAME](ttk_widget.htm#M2) ttk::widget — Standard options and commands supported by Tk themed widgets 
[DESCRIPTION](ttk_widget.htm#M3) 
[STANDARD OPTIONS](ttk_widget.htm#M4)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 
[-style, style, Style](ttk_widget.htm#M-style) 



 
[SCROLLABLE WIDGET OPTIONS](ttk_widget.htm#M5)  
[-xscrollcommand, xScrollCommand, ScrollCommand](ttk_widget.htm#M-xscrollcommand) 
[-yscrollcommand, yScrollCommand, ScrollCommand](ttk_widget.htm#M-yscrollcommand) 

 
[LABEL OPTIONS](ttk_widget.htm#M6)  
[-text, text, Text](ttk_widget.htm#M-text) 
[-textvariable, textVariable, Variable](ttk_widget.htm#M-textvariable) 
[-underline, underline, Underline](ttk_widget.htm#M-underline) 
[-image, image, Image](ttk_widget.htm#M-image) 
[-compound, compound, Compound](ttk_widget.htm#M-compound)  
[text](ttk_widget.htm#M7) 
[image](ttk_widget.htm#M8) 
[center](ttk_widget.htm#M9) 
[top](ttk_widget.htm#M10) 
[bottom](ttk_widget.htm#M11) 
[left](ttk_widget.htm#M12) 
[right](ttk_widget.htm#M13) 
[none](ttk_widget.htm#M14) 







 
[-width, width, Width](ttk_widget.htm#M-width) 





 
[COMPATIBILITY OPTIONS](ttk_widget.htm#M15)  
[-state, state, State](ttk_widget.htm#M-state) 
 
[COMMANDS](ttk_widget.htm#M16)  
[*pathName* **cget** *option*](ttk_widget.htm#M17) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](ttk_widget.htm#M18) 
[*pathName* **identify element** *x y*](ttk_widget.htm#M19) 
[*pathName* **instate** *statespec* ?*script*?](ttk_widget.htm#M20) 
[*pathName* **state** ?*stateSpec*?](ttk_widget.htm#M21) 




 
[WIDGET STATES](ttk_widget.htm#M22)  
[**active**](ttk_widget.htm#M23) 
[**disabled**](ttk_widget.htm#M24) 
[**focus**](ttk_widget.htm#M25) 
[**pressed**](ttk_widget.htm#M26) 
[**selected**](ttk_widget.htm#M27) 
[**background**](ttk_widget.htm#M28) 
[**readonly**](ttk_widget.htm#M29) 
[**alternate**](ttk_widget.htm#M30) 
[**invalid**](ttk_widget.htm#M31) 
[**hover**](ttk_widget.htm#M32) 









 
[EXAMPLES](ttk_widget.htm#M33) 
[SEE ALSO](ttk_widget.htm#M34) 
[KEYWORDS](ttk_widget.htm#M35) 










 Name
----

 ttk::widget — Standard options and commands supported by Tk themed widgets Description
-----------

 This manual describes common widget options and commands. Standard options
----------------

 The following options are supported by all Tk themed widgets:  Command-Line Name: **-class** Database Name: **undefined** Database Class: **undefined** 


Specifies the window class. The class is used when querying the option database for the window's other options, to determine the default bindtags for the window, and to select the widget's default layout and style. This is a read-only option: it may only be specified when the window is created, and may not be changed with the **configure** widget command. 

Command-Line Name: **-cursor** Database Name: **cursor** Database Class: **Cursor** 


Specifies the mouse cursor to be used for the widget. See **[Tk\_GetCursor](https://www.tcl.tk/man/tcl/TkLib/GetCursor.htm)** and *cursors(n)* in the Tk reference manual for the legal values. If set to the empty string (the default), the cursor is inherited from the parent widget. 

Command-Line Name: **-takefocus** Database Name: **takeFocus** Database Class: **TakeFocus** 


Determines whether the window accepts the focus during keyboard traversal. Either **0**, **1**, a command prefix (to which the widget path is appended, and which should return **0** or **1**), or the empty string. See *options(n)* in the Tk reference manual for the full description. 

Command-Line Name: **-style** Database Name: **[style](ttk_style.htm)** Database Class: **[Style](ttk_style.htm)** 


May be used to specify a custom widget style. 
 Scrollable widget options
-------------------------

 The following options are supported by widgets that are controllable by a scrollbar. See *scrollbar(n)* for more information  Command-Line Name: **-xscrollcommand** Database Name: **xScrollCommand** Database Class: **ScrollCommand** 


A command prefix, used to communicate with horizontal scrollbars. When the view in the widget's window changes, the widget will generate a Tcl command by concatenating the scroll command and two numbers. Each of the numbers is a fraction between 0 and 1 indicating a position in the document; 0 indicates the beginning, and 1 indicates the end. The first fraction indicates the first information in the widget that is visible in the window, and the second fraction indicates the information just after the last portion that is visible.  Typically the **-xscrollcommand** option consists of the path name of a **[scrollbar](scrollbar.htm)** widget followed by “set”, e.g. “.x.scrollbar set”. This will cause the scrollbar to be updated whenever the view in the window changes. 


 If this option is set to the empty string (the default), then no command will be executed. 



Command-Line Name: **-yscrollcommand** Database Name: **yScrollCommand** Database Class: **ScrollCommand** 


A command prefix, used to communicate with vertical scrollbars. See the description of **-xscrollcommand** above for details. 
 Label options
-------------

 The following options are supported by labels, buttons, and other button-like widgets:  Command-Line Name: **-text** Database Name: **text** Database Class: **Text** 


Specifies a text string to be displayed inside the widget (unless overridden by **-textvariable**). 

Command-Line Name: **-textvariable** Database Name: **textVariable** Database Class: **Variable** 


Specifies the name of a global variable whose value will be used in place of the **-text** resource. 

Command-Line Name: **-underline** Database Name: **underline** Database Class: **Underline** 


If set, specifies the integer index (0-based) of a character to underline in the text string. The underlined character is used for mnemonic activation. 

Command-Line Name: **-image** Database Name: **image** Database Class: **Image** 


Specifies an image to display. This is a list of 1 or more elements. The first element is the default image name. The rest of the list is a sequence of *statespec / value* pairs as per **[style map](ttk_style.htm)**, specifying different images to use when the widget is in a particular state or combination of states. All images in the list should have the same size. 

Command-Line Name: **-compound** Database Name: **compound** Database Class: **Compound** 


Specifies how to display the image relative to the text, in the case both **-text** and **-image** are present. Valid values are: 
 text
 Display text only. 

image
 Display image only. 

center
 Display text centered on top of image. 

top
bottom
left
right
 Display image above, below, left of, or right of the text, respectively. 

none
 The default; display the image if present, otherwise the text. 



Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


If greater than zero, specifies how much space, in character widths, to allocate for the text label. If less than zero, specifies a minimum width. If zero or unspecified, the natural width of the text label is used. 
 Compatibility options
---------------------

  Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


May be set to **normal** or **disabled** to control the **disabled** state bit. This is a write-only option: setting it changes the widget state, but the **state** widget command does not affect the **-state** option. 
 Commands
--------

  
*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. If *option* is specified with no *value*, then the command returns a list describing the named option: the elements of the list are the option name, database name, database class, default value, and current value. If no *option* is specified, returns a list describing all of the available options for *pathName*. 


*pathName* **identify element** *x y*

 Returns the name of the element under the point given by *x* and *y*, or an empty string if the point does not lie within any element. *x* and *y* are pixel coordinates relative to the widget. Some widgets accept other **identify** subcommands. 


*pathName* **instate** *statespec* ?*script*?
 Test the widget's state. If *script* is not specified, returns 1 if the widget state matches *statespec* and 0 otherwise. If *script* is specified, equivalent to 
```
if {[*pathName* instate *stateSpec*]} *script*
```



*pathName* **state** ?*stateSpec*?
 Modify or inquire widget state. If *stateSpec* is present, sets the widget state: for each flag in *stateSpec*, sets the corresponding flag or clears it if prefixed by an exclamation point.  Returns a new state spec indicating which flags were changed: 
```
set changes [*pathName* state *spec*]
*pathName* state $changes
```
 will restore *pathName* to the original state. If *stateSpec* is not specified, returns a list of the currently-enabled state flags. 

 Widget states
-------------

 The widget state is a bitmap of independent state flags. Widget state flags include: 
 **active**
 The mouse cursor is over the widget and pressing a mouse button will cause some action to occur. (aka “prelight” (Gnome), “hot” (Windows), “hover”). 

**disabled**
 Widget is disabled under program control (aka “unavailable”, “inactive”). 

**focus**
 Widget has keyboard focus. 

**pressed**
 Widget is being pressed (aka “armed” in Motif). 

**selected**
 “On”, “true”, or “current” for things like checkbuttons and radiobuttons. 

**background**
 Windows and the Mac have a notion of an “active” or foreground window. The **background** state is set for widgets in a background window, and cleared for those in the foreground window. 

**readonly**
 Widget should not allow user modification. 

**alternate**
 A widget-specific alternate display format. For example, used for checkbuttons and radiobuttons in the “tristate” or “mixed” state, and for buttons with **-default active**. 

**invalid**
 The widget's value is invalid. (Potential uses: scale widget value out of bounds, entry widget value failed validation.) 

**hover**
 The mouse cursor is within the widget. This is similar to the **active** state; it is used in some themes for widgets that provide distinct visual feedback for the active widget in addition to the active element within the widget. 

  A *state specification* or *stateSpec* is a list of state names, optionally prefixed with an exclamation point (!) indicating that the bit is off. 


Examples
--------

 
```
set b [ttk::button .b]

# Disable the widget:
$b **state** disabled

# Invoke the widget only if it is currently pressed and enabled:
$b **instate** {pressed !disabled} { .b invoke }

# Reenable widget:
$b **state** !disabled
```
 See also
--------

 **[ttk::intro](ttk_intro.htm)**, **[ttk::style](ttk_style.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_widget.htm>

pack
====

  
[NAME](pack.htm#M2) pack — Geometry manager that packs around edges of cavity 
[SYNOPSIS](pack.htm#M3) 
[DESCRIPTION](pack.htm#M4)  
[**pack** *slave* ?*slave ...*? ?*options*?](pack.htm#M5) 
[**pack configure** *slave* ?*slave ...*? ?*options*?](pack.htm#M6)  
[**-after** *other*](pack.htm#M7) 
[**-anchor** *anchor*](pack.htm#M8) 
[**-before** *other*](pack.htm#M9) 
[**-expand** *boolean*](pack.htm#M10) 
[**-fill** *style*](pack.htm#M11)  
[**none**](pack.htm#M12) 
[**x**](pack.htm#M13) 
[**y**](pack.htm#M14) 
[**both**](pack.htm#M15) 



 
[**-in** *other*](pack.htm#M16) 
[**-ipadx** *amount*](pack.htm#M17) 
[**-ipady** *amount*](pack.htm#M18) 
[**-padx** *amount*](pack.htm#M19) 
[**-pady** *amount*](pack.htm#M20) 
[**-side** *side*](pack.htm#M21) 










 
[**pack forget** *slave* ?*slave ...*?](pack.htm#M22) 
[**pack info** *slave*](pack.htm#M23) 
[**pack propagate** *master* ?*boolean*?](pack.htm#M24) 
[**pack slaves** *master*](pack.htm#M25) 





 
[THE PACKER ALGORITHM](pack.htm#M26) 
[EXPANSION](pack.htm#M27) 
[GEOMETRY PROPAGATION](pack.htm#M28) 
[RESTRICTIONS ON MASTER WINDOWS](pack.htm#M29) 
[PACKING ORDER](pack.htm#M30) 
[EXAMPLE](pack.htm#M31) 
[SEE ALSO](pack.htm#M32) 
[KEYWORDS](pack.htm#M33) 










 Name
----

 pack — Geometry manager that packs around edges of cavity Synopsis
--------

 **pack** *option arg* ?*arg ...*?  
 Description
-----------

 The **pack** command is used to communicate with the packer, a geometry manager that arranges the children of a parent by packing them in order around the edges of the parent. The **pack** command can have any of several forms, depending on the *option* argument: 
 
**pack** *slave* ?*slave ...*? ?*options*?
 If the first argument to **pack** is a window name (any value starting with “.”), then the command is processed in the same way as **pack configure**. 


**pack configure** *slave* ?*slave ...*? ?*options*?
 The arguments consist of the names of one or more slave windows followed by pairs of arguments that specify how to manage the slaves. See **[THE PACKER ALGORITHM](#M26)** below for details on how the options are used by the packer. The following options are supported: 
 
**-after** *other*

 *Other* must the name of another window. Use its master as the master for the slaves, and insert the slaves just after *other* in the packing order. 


**-anchor** *anchor*

 *Anchor* must be a valid anchor position such as **n** or **sw**; it specifies where to position each slave in its parcel. Defaults to **center**. 


**-before** *other*

 *Other* must the name of another window. Use its master as the master for the slaves, and insert the slaves just before *other* in the packing order. 


**-expand** *boolean*

 Specifies whether the slaves should be expanded to consume extra space in their master. *Boolean* may have any proper boolean value, such as **1** or **no**. Defaults to 0. 


**-fill** *style*

 If a slave's parcel is larger than its requested dimensions, this option may be used to stretch the slave. *Style* must have one of the following values: 
 **none**
 Give the slave its requested dimensions plus any internal padding requested with **-ipadx** or **-ipady**. This is the default. 

**x**
 Stretch the slave horizontally to fill the entire width of its parcel (except leave external padding as specified by **-padx**). 

**y**
 Stretch the slave vertically to fill the entire height of its parcel (except leave external padding as specified by **-pady**). 

**both**
 Stretch the slave both horizontally and vertically. 




**-in** *other*

 Insert the slave(s) at the end of the packing order for the master window given by *other*. 


**-ipadx** *amount*

 *Amount* specifies how much horizontal internal padding to leave on each side of the slave(s). *Amount* must be a valid screen distance, such as **2** or **.5c**. It defaults to 0. 


**-ipady** *amount*

 *Amount* specifies how much vertical internal padding to leave on each side of the slave(s). *Amount* defaults to 0. 


**-padx** *amount*

 *Amount* specifies how much horizontal external padding to leave on each side of the slave(s). *Amount* may be a list of two values to specify padding for left and right separately. *Amount* defaults to 0. 


**-pady** *amount*

 *Amount* specifies how much vertical external padding to leave on each side of the slave(s). *Amount* may be a list of two values to specify padding for top and bottom separately. *Amount* defaults to 0. 


**-side** *side*

 Specifies which side of the master the slave(s) will be packed against. Must be **left**, **right**, **top**, or **bottom**. Defaults to **top**. 

If no **-in**, **-after** or **-before** option is specified then each of the slaves will be inserted at the end of the packing list for its parent unless it is already managed by the packer (in which case it will be left where it is). If one of these options is specified then all the slaves will be inserted at the specified point. If any of the slaves are already managed by the geometry manager then any unspecified options for them retain their previous values rather than receiving default values.




**pack forget** *slave* ?*slave ...*?
 Removes each of the *slave*s from the packing order for its master and unmaps their windows. The slaves will no longer be managed by the packer. 


**pack info** *slave*

 Returns a list whose elements are the current configuration state of the slave given by *slave* in the same option-value form that might be specified to **pack configure**. The first two elements of the list are “**-in** *master*” where *master* is the slave's master. 


**pack propagate** *master* ?*boolean*?
 If *boolean* has a true boolean value such as **1** or **on** then propagation is enabled for *master*, which must be a window name (see **[GEOMETRY PROPAGATION](#M28)** below). If *boolean* has a false boolean value then propagation is disabled for *master*. In either of these cases an empty string is returned. If *boolean* is omitted then the command returns **0** or **1** to indicate whether propagation is currently enabled for *master*. Propagation is enabled by default. 


**pack slaves** *master*

 Returns a list of all of the slaves in the packing order for *master*. The order of the slaves in the list is the same as their order in the packing order. If *master* has no slaves then an empty string is returned. 

 The packer algorithm
--------------------

 For each master the packer maintains an ordered list of slaves called the *packing list*. The **-in**, **-after**, and **-before** configuration options are used to specify the master for each slave and the slave's position in the packing list. If none of these options is given for a slave then the slave is added to the end of the packing list for its parent.  The packer arranges the slaves for a master by scanning the packing list in order. At the time it processes each slave, a rectangular area within the master is still unallocated. This area is called the *cavity*; for the first slave it is the entire area of the master. 


 For each slave the packer carries out the following steps: 


1. The packer allocates a rectangular *parcel* for the slave along the side of the cavity given by the slave's **-side** option. If the side is top or bottom then the width of the parcel is the width of the cavity and its height is the requested height of the slave plus the **-ipady** and **-pady** options. For the left or right side the height of the parcel is the height of the cavity and the width is the requested width of the slave plus the **-ipadx** and **-padx** options. The parcel may be enlarged further because of the **-expand** option (see **[EXPANSION](#M27)** below)
2. The packer chooses the dimensions of the slave. The width will normally be the slave's requested width plus twice its **-ipadx** option and the height will normally be the slave's requested height plus twice its **-ipady** option. However, if the **-fill** option is **x** or **both** then the width of the slave is expanded to fill the width of the parcel, minus twice the **-padx** option. If the **-fill** option is **y** or **both** then the height of the slave is expanded to fill the width of the parcel, minus twice the **-pady** option.
3. The packer positions the slave over its parcel. If the slave is smaller than the parcel then the **-anchor** option determines where in the parcel the slave will be placed. If **-padx** or **-pady** is non-zero, then the given amount of external padding will always be left between the slave and the edges of the parcel.

  Once a given slave has been packed, the area of its parcel is subtracted from the cavity, leaving a smaller rectangular cavity for the next slave. If a slave does not use all of its parcel, the unused space in the parcel will not be used by subsequent slaves. If the cavity should become too small to meet the needs of a slave then the slave will be given whatever space is left in the cavity. If the cavity shrinks to zero size, then all remaining slaves on the packing list will be unmapped from the screen until the master window becomes large enough to hold them again. 


### Expansion

 If a master window is so large that there will be extra space left over after all of its slaves have been packed, then the extra space is distributed uniformly among all of the slaves for which the **-expand** option is set. Extra horizontal space is distributed among the expandable slaves whose **-side** is **left** or **right**, and extra vertical space is distributed among the expandable slaves whose **-side** is **top** or **bottom**. ### Geometry propagation

 The packer normally computes how large a master must be to just exactly meet the needs of its slaves, and it sets the requested width and height of the master to these dimensions. This causes geometry information to propagate up through a window hierarchy to a top-level window so that the entire sub-tree sizes itself to fit the needs of the leaf windows. However, the **pack propagate** command may be used to turn off propagation for one or more masters. If propagation is disabled then the packer will not set the requested width and height of the packer. This may be useful if, for example, you wish for a master window to have a fixed size that you specify. Restrictions on master windows
------------------------------

 The master for each slave must either be the slave's parent (the default) or a descendant of the slave's parent. This restriction is necessary to guarantee that the slave can be placed over any part of its master that is visible without danger of the slave being clipped by its parent. Packing order
-------------

 If the master for a slave is not its parent then you must make sure that the slave is higher in the stacking order than the master. Otherwise the master will obscure the slave and it will appear as if the slave has not been packed correctly. The easiest way to make sure the slave is higher than the master is to create the master window first: the most recently created window will be highest in the stacking order. Or, you can use the **[raise](raise.htm)** and **[lower](lower.htm)** commands to change the stacking order of either the master or the slave. Example
-------

 
```
# Make the widgets
label .t -text "This widget is at the top"    -bg red
label .b -text "This widget is at the bottom" -bg green
label .l -text "Left\nHand\nSide"
label .r -text "Right\nHand\nSide"
text .mid
	.mid insert end "This layout is like Java's BorderLayout"
# Lay them out
**pack** .t   -side top    -fill x
**pack** .b   -side bottom -fill x
**pack** .l   -side left   -fill y
**pack** .r   -side right  -fill y
**pack** .mid -expand 1    -fill both
```
 See also
--------

 **[grid](grid.htm)**, **[place](place.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/pack.htm>

ttk\_combobox
=============

  
[NAME](ttk_combobox.htm#M2) ttk::combobox — text field with popdown selection list 
[SYNOPSIS](ttk_combobox.htm#M3) 
[DESCRIPTION](ttk_combobox.htm#M4) 
[STANDARD OPTIONS](ttk_combobox.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 



 
[WIDGET-SPECIFIC OPTIONS](ttk_combobox.htm#M6)  
[-exportselection, exportSelection, ExportSelection](ttk_combobox.htm#M7) 
[-justify, justify, Justify](ttk_combobox.htm#M8) 
[-height, height, Height](ttk_combobox.htm#M9) 
[-postcommand, postCommand, PostCommand](ttk_combobox.htm#M10) 
[-state, state, State](ttk_combobox.htm#M11) 
[-textvariable, textVariable, TextVariable](ttk_combobox.htm#M12) 
[-values, values, Values](ttk_combobox.htm#M13) 
[-width, width, Width](ttk_combobox.htm#M14) 







 
[WIDGET COMMAND](ttk_combobox.htm#M15)  
[*pathName* **current** ?*newIndex*?](ttk_combobox.htm#M16) 
[*pathName* **get**](ttk_combobox.htm#M17) 
[*pathName* **set** *value*](ttk_combobox.htm#M18) 


 
[VIRTUAL EVENTS](ttk_combobox.htm#M19) 
[SEE ALSO](ttk_combobox.htm#M20) 
[KEYWORDS](ttk_combobox.htm#M21) 








 Name
----

 ttk::combobox — text field with popdown selection list Synopsis
--------

 **ttk::combobox** *pathName* ?*options*?  
 Description
-----------

 A **ttk::combobox** combines a text field with a pop-down list of values; the user may select the value of the text field from among the values in the list. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 



 Widget-specific options
-----------------------

  Command-Line Name: **-exportselection** Database Name: **exportSelection** Database Class: **ExportSelection** 


Boolean value. If set, the widget selection is linked to the X selection. 

Command-Line Name: **-justify** Database Name: **justify** Database Class: **Justify** 


Specifies how the text is aligned within the widget. Must be one of **left**, **center**, or **right**. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies the height of the pop-down listbox, in rows. 

Command-Line Name: **-postcommand** Database Name: **postCommand** Database Class: **PostCommand** 


A Tcl script to evaluate immediately before displaying the listbox. The **-postcommand** script may specify the **-values** to display. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


One of **normal**, **readonly**, or **disabled**. In the **readonly** state, the value may not be edited directly, and the user can only select one of the **-values** from the dropdown list. In the **normal** state, the text field is directly editable. In the **disabled** state, no interaction is possible. 

Command-Line Name: **-textvariable** Database Name: **textVariable** Database Class: **TextVariable** 


Specifies the name of a global variable whose value is linked to the widget value. Whenever the variable changes value the widget value is updated, and vice versa. 

Command-Line Name: **-values** Database Name: **values** Database Class: **Values** 


Specifies the list of values to display in the drop-down listbox. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies an integer value indicating the desired width of the entry window, in average-size characters of the widget's font. 
 Widget command
--------------

 The following subcommands are possible for combobox widgets: 
 
*pathName* **current** ?*newIndex*?
 If *newIndex* is supplied, sets the combobox value to the element at position *newIndex* in the list of **-values**. Otherwise, returns the index of the current value in the list of **-values** or **-1** if the current value does not appear in the list. 


*pathName* **get**

 Returns the current value of the combobox. 


*pathName* **set** *value*

 Sets the value of the combobox to *value*. 

  The combobox widget also supports the following **[ttk::entry](ttk_entry.htm)** widget subcommands (see *ttk::entry(n)* for details): 




|  |  |  |
| --- | --- | --- |
| **bbox** | **delete** | **icursor** |
| **index** | **insert** | **selection** |
| **xview** |

 The combobox widget also supports the following generic **[ttk::widget](ttk_widget.htm)** widget subcommands (see *ttk::widget(n)* for details): 

|  |  |  |
| --- | --- | --- |
| **cget** | **configure** | **identify** |
| **instate** | **state** |

 Virtual events
--------------

 The combobox widget generates a **<<ComboboxSelected>>** virtual event when the user selects an element from the list of values. If the selection action unposts the listbox, this event is delivered after the listbox is unposted. See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[ttk::entry](ttk_entry.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_combobox.htm>

getOpenFile
===========

  
[NAME](getopenfile.htm#M2) tk\_getOpenFile, tk\_getSaveFile — pop up a dialog box for the user to select a file to open or save. 
[SYNOPSIS](getopenfile.htm#M3) 
[DESCRIPTION](getopenfile.htm#M4)  
[**-confirmoverwrite** *boolean*](getopenfile.htm#M5) 
[**-defaultextension** *extension*](getopenfile.htm#M6) 
[**-filetypes** *filePatternList*](getopenfile.htm#M7) 
[**-initialdir** *directory*](getopenfile.htm#M8) 
[**-initialfile** *filename*](getopenfile.htm#M9) 
[**-message** *string*](getopenfile.htm#M10) 
[**-multiple** *boolean*](getopenfile.htm#M11) 
[**-parent** *window*](getopenfile.htm#M12) 
[**-title** *titleString*](getopenfile.htm#M13) 
[**-typevariable** *variableName*](getopenfile.htm#M14) 









 
[SPECIFYING FILE PATTERNS](getopenfile.htm#M15) 
[SPECIFYING EXTENSIONS](getopenfile.htm#M16) 
[EXAMPLE](getopenfile.htm#M17) 
[SEE ALSO](getopenfile.htm#M18) 
[KEYWORDS](getopenfile.htm#M19) 







 Name
----

 tk\_getOpenFile, tk\_getSaveFile — pop up a dialog box for the user to select a file to open or save. Synopsis
--------

 **tk\_getOpenFile** ?*option value ...*?  
 **tk\_getSaveFile** ?*option value ...*?  
 Description
-----------

 The procedures **tk\_getOpenFile** and **tk\_getSaveFile** pop up a dialog box for the user to select a file to open or save. The **tk\_getOpenFile** command is usually associated with the **Open** command in the **File** menu. Its purpose is for the user to select an existing file *only*. If the user enters a non-existent file, the dialog box gives the user an error prompt and requires the user to give an alternative selection. If an application allows the user to create new files, it should do so by providing a separate **New** menu command.  The **tk\_getSaveFile** command is usually associated with the **Save as** command in the **File** menu. If the user enters a file that already exists, the dialog box prompts the user for confirmation whether the existing file should be overwritten or not. 


 The following *option-value* pairs are possible as command line arguments to these two commands: 


 
**-confirmoverwrite** *boolean*

 Configures how the Save dialog reacts when the selected file already exists, and saving would overwrite it. A true value requests a confirmation dialog be presented to the user. A false value requests that the overwrite take place without confirmation. Default value is true. 


**-defaultextension** *extension*

 Specifies a string that will be appended to the filename if the user enters a filename without an extension. The default value is the empty string, which means no extension will be appended to the filename in any case. This option is ignored on Mac OS X, which does not require extensions to filenames, and the UNIX implementation guesses reasonable values for this from the **-filetypes** option when this is not supplied. 


**-filetypes** *filePatternList*

 If a **[File types](../tclcmd/file.htm)** listbox exists in the file dialog on the particular platform, this option gives the *filetype*s in this listbox. When the user choose a filetype in the listbox, only the files of that type are listed. If this option is unspecified, or if it is set to the empty list, or if the **[File types](../tclcmd/file.htm)** listbox is not supported by the particular platform then all files are listed regardless of their types. See the section **[SPECIFYING FILE PATTERNS](#M15)** below for a discussion on the contents of *filePatternList*. 


**-initialdir** *directory*

 Specifies that the files in *directory* should be displayed when the dialog pops up. If this parameter is not specified, the initial directory defaults to the current working directory on non-Windows systems and on Windows systems prior to Vista. On Vista and later systems, the initial directory defaults to the last user-selected directory for the application. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. 


**-initialfile** *filename*

 Specifies a filename to be displayed in the dialog when it pops up. 


**-message** *string*

 Specifies a message to include in the client area of the dialog. This is only available on Mac OS X. 


**-multiple** *boolean*

 Allows the user to choose multiple files from the Open dialog. 


**-parent** *window*

 Makes *window* the logical parent of the file dialog. The file dialog is displayed on top of its parent window. On Mac OS X, this turns the file dialog into a sheet attached to the parent window. 


**-title** *titleString*

 Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title is displayed. 


**-typevariable** *variableName*

 The global variable *variableName* is used to preselect which filter is used from *filterList* when the dialog box is opened and is updated when the dialog box is closed, to the last selected filter. The variable is read once at the beginning to select the appropriate filter. If the variable does not exist, or its value does not match any filter typename, or is empty (**{}**), the dialog box will revert to the default behavior of selecting the first filter in the list. If the dialog is canceled, the variable is not modified. 

  If the user selects a file, both **tk\_getOpenFile** and **tk\_getSaveFile** return the full pathname of this file. If the user cancels the operation, both commands return the empty string. 


Specifying file patterns
------------------------

 The *filePatternList* value given by the **-filetypes** option is a list of file patterns. Each file pattern is a list of the form 
```
*typeName* {*extension* ?*extension ...*?} ?{*macType* ?*macType ...*?}?
```
 *typeName* is the name of the file type described by this file pattern and is the text string that appears in the **[File types](../tclcmd/file.htm)** listbox. *extension* is a file extension for this file pattern. *macType* is a four-character Macintosh file type. The list of *macType*s is optional and may be omitted for applications that do not need to execute on the Macintosh platform.  Several file patterns may have the same *typeName,* in which case they refer to the same file type and share the same entry in the listbox. When the user selects an entry in the listbox, all the files that match at least one of the file patterns corresponding to that entry are listed. Usually, each file pattern corresponds to a distinct type of file. The use of more than one file pattern for one type of file is only necessary on the Macintosh platform. 


 On the Macintosh platform, a file matches a file pattern if its name matches at least one of the *extension*(s) AND it belongs to at least one of the *macType*(s) of the file pattern. For example, the **C Source Files** file pattern in the sample code matches with files that have a **.c** extension AND belong to the *macType* **TEXT**. To use the OR rule instead, you can use two file patterns, one with the *extensions* only and the other with the *macType* only. The **GIF Files** file type in the sample code matches files that *either* have a **.gif** extension OR belong to the *macType* **GIFF**. 


 On the Unix and Windows platforms, a file matches a file pattern if its name matches at least one of the *extension*(s) of the file pattern. The *macType*s are ignored. 


Specifying extensions
---------------------

 On the Unix and Macintosh platforms, extensions are matched using glob-style pattern matching. On the Windows platform, extensions are matched by the underlying operating system. The types of possible extensions are: 
1. the special extension “\*” matches any file;
2. the special extension “” matches any files that do not have an extension (i.e., the filename contains no full stop character);
3. any character string that does not contain any wild card characters (\* and ?).

  Due to the different pattern matching rules on the various platforms, to ensure portability, wild card characters are not allowed in the extensions, except as in the special extension “\*”. Extensions without a full stop character (e.g. “~”) are allowed but may not work on all platforms. 


Example
-------

 
```
set types {
    {{Text Files}       {.txt}        }
    {{TCL Scripts}      {.tcl}        }
    {{C Source Files}   {.c}      TEXT}
    {{GIF Files}        {.gif}        }
    {{GIF Files}        {}        GIFF}
    {{All Files}        *             }
}
set filename [**tk\_getOpenFile** -filetypes $types]

if {$filename ne ""} {
    # Open the file ...
}
```
 See also
--------

 **tk\_chooseDirectory** Copyright © 1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/getOpenFile.htm>

ttk\_treeview
=============

  
[NAME](ttk_treeview.htm#M2) ttk::treeview — hierarchical multicolumn data display widget 
[SYNOPSIS](ttk_treeview.htm#M3) 
[DESCRIPTION](ttk_treeview.htm#M4) 
[STANDARD OPTIONS](ttk_treeview.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 
[-xscrollcommand, xScrollCommand, ScrollCommand](ttk_widget.htm#M-xscrollcommand) 
[-yscrollcommand, yScrollCommand, ScrollCommand](ttk_widget.htm#M-yscrollcommand) 





 
[WIDGET-SPECIFIC OPTIONS](ttk_treeview.htm#M6)  
[-columns, columns, Columns](ttk_treeview.htm#M7) 
[-displaycolumns, displayColumns, DisplayColumns](ttk_treeview.htm#M8) 
[-height, height, Height](ttk_treeview.htm#M9) 
[-padding, padding, Padding](ttk_treeview.htm#M10) 
[-selectmode, selectMode, SelectMode](ttk_treeview.htm#M11) 
[-show, show, Show](ttk_treeview.htm#M12)  
[**tree**](ttk_treeview.htm#M13) 
[**headings**](ttk_treeview.htm#M14) 

 





 
[WIDGET COMMAND](ttk_treeview.htm#M15)  
[*pathname* **bbox** *item* ?*column*?](ttk_treeview.htm#M16) 
[*pathname* **cget** *option*](ttk_treeview.htm#M17) 
[*pathname* **children** *item* ?*newchildren*?](ttk_treeview.htm#M18) 
[*pathname* **column** *column* ?*-option* ?*value -option value...*?](ttk_treeview.htm#M19)  
[**-id** *name*](ttk_treeview.htm#M20) 
[**-anchor**](ttk_treeview.htm#M21) 
[**-minwidth**](ttk_treeview.htm#M22) 
[**-stretch**](ttk_treeview.htm#M23) 
[**-width** *w*](ttk_treeview.htm#M24) 




 
[*pathname* **configure** ?*option*? ?*value option value ...*?](ttk_treeview.htm#M25) 
[*pathname* **delete** *itemList*](ttk_treeview.htm#M26) 
[*pathname* **detach** *itemList*](ttk_treeview.htm#M27) 
[*pathname* **exists** *item*](ttk_treeview.htm#M28) 
[*pathname* **focus** ?*item*?](ttk_treeview.htm#M29) 
[*pathname* **heading** *column* ?*-option* ?*value -option value...*?](ttk_treeview.htm#M30)  
[**-text** *text*](ttk_treeview.htm#M31) 
[**-image** *imageName*](ttk_treeview.htm#M32) 
[**-anchor** *anchor*](ttk_treeview.htm#M33) 
[**-command** *script*](ttk_treeview.htm#M34) 



 
[*pathname* **identify** *component x y*](ttk_treeview.htm#M35)  
[*pathname* **identify region** *x y*](ttk_treeview.htm#M36)  
[heading](ttk_treeview.htm#M37) 
[separator](ttk_treeview.htm#M38) 
[tree](ttk_treeview.htm#M39) 
[cell](ttk_treeview.htm#M40) 



 
[*pathname* **identify column** *x y*](ttk_treeview.htm#M41) 
[*pathname* **identify element** *x y*](ttk_treeview.htm#M42) 
[*pathname* **identify row** *x y*](ttk_treeview.htm#M43) 



 
[*pathname* **index** *item*](ttk_treeview.htm#M44) 
[*pathname* **insert** *parent index* ?**-id** *id*? *options...*](ttk_treeview.htm#M45) 
[*pathname* **instate** *statespec* ?*script*?](ttk_treeview.htm#M46) 
[*pathname* **item** *item* ?*-option* ?*value -option value...*?](ttk_treeview.htm#M47) 
[*pathname* **move** *item parent index*](ttk_treeview.htm#M48) 
[*pathname* **next** *item*](ttk_treeview.htm#M49) 
[*pathname* **parent** *item*](ttk_treeview.htm#M50) 
[*pathname* **prev** *item*](ttk_treeview.htm#M51) 
[*pathname* **see** *item*](ttk_treeview.htm#M52) 
[*pathname* **selection** ?*selop itemList*?](ttk_treeview.htm#M53)  
[*pathname* **selection set** *itemList*](ttk_treeview.htm#M54) 
[*pathname* **selection add** *itemList*](ttk_treeview.htm#M55) 
[*pathname* **selection remove** *itemList*](ttk_treeview.htm#M56) 
[*pathname* **selection toggle** *itemList*](ttk_treeview.htm#M57) 



 
[*pathname* **set** *item* ?*column*? ?*value*?](ttk_treeview.htm#M58) 
[*pathname* **state** ?*stateSpec*?](ttk_treeview.htm#M59) 
[*pathName* **tag** *args...*](ttk_treeview.htm#M60)  
[*pathName* **tag bind** *tagName* ?*sequence*? ?*script*?](ttk_treeview.htm#M61) 
[*pathName* **tag configure** *tagName* ?*option*? ?*value option value...*?](ttk_treeview.htm#M62) 
[*pathName* **tag has** *tagName* ?*item*?](ttk_treeview.htm#M63) 
[*pathName* **tag names**](ttk_treeview.htm#M64) 
[*pathName* **tag add** *tag items*](ttk_treeview.htm#M65) 
[*pathName* **tag remove** *tag* ?*items*?](ttk_treeview.htm#M66) 





 
[*pathName* **xview** *args*](ttk_treeview.htm#M67) 
[*pathName* **yview** *args*](ttk_treeview.htm#M68) 

























 
[ITEM OPTIONS](ttk_treeview.htm#M69)  
[-text, text, Text](ttk_treeview.htm#M70) 
[-image, image, Image](ttk_treeview.htm#M71) 
[-values, values, Values](ttk_treeview.htm#M72) 
[-open, open, Open](ttk_treeview.htm#M73) 
[-tags, tags, Tags](ttk_treeview.htm#M74) 




 
[TAG OPTIONS](ttk_treeview.htm#M75)  
[**-foreground**](ttk_treeview.htm#M76) 
[**-background**](ttk_treeview.htm#M77) 
[**-font**](ttk_treeview.htm#M78) 
[**-image**](ttk_treeview.htm#M79) 



 
[COLUMN IDENTIFIERS](ttk_treeview.htm#M80) 
[VIRTUAL EVENTS](ttk_treeview.htm#M81)  
[<<TreeviewSelect>>](ttk_treeview.htm#M82) 
[<<TreeviewOpen>>](ttk_treeview.htm#M83) 
[<<TreeviewClose>>](ttk_treeview.htm#M84) 


 
[SEE ALSO](ttk_treeview.htm#M85) 










 Name
----

 ttk::treeview — hierarchical multicolumn data display widget Synopsis
--------

 **ttk::treeview** *pathname* ?*options*?  
 Description
-----------

 The **ttk::treeview** widget displays a hierarchical collection of items. Each item has a textual label, an optional image, and an optional list of data values. The data values are displayed in successive columns after the tree label.  The order in which data values are displayed may be controlled by setting the **-displaycolumns** widget option. The tree widget can also display column headings. Columns may be accessed by number or by symbolic names listed in the **-columns** widget option; see **[COLUMN IDENTIFIERS](#M80)**. 


 Each item is identified by a unique name. The widget will generate item IDs if they are not supplied by the caller. There is a distinguished root item, named **{}**. The root item itself is not displayed; its children appear at the top level of the hierarchy. 


 Each item also has a list of *tags*, which can be used to associate event bindings with individual items and control the appearance of the item. 


 Treeview widgets support horizontal and vertical scrolling with the standard **-**[**xy**]**scrollcommand** options and [**xy**]**view** widget commands. 


Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 
**[-xscrollcommand, xScrollCommand, ScrollCommand](ttk_widget.htm#M-xscrollcommand)** 
**[-yscrollcommand, yScrollCommand, ScrollCommand](ttk_widget.htm#M-yscrollcommand)** 





 Widget-specific options
-----------------------

  Command-Line Name: **-columns** Database Name: **columns** Database Class: **Columns** 


A list of column identifiers, specifying the number of columns and their names. 

Command-Line Name: **-displaycolumns** Database Name: **displayColumns** Database Class: **DisplayColumns** 


A list of column identifiers (either symbolic names or integer indices) specifying which data columns are displayed and the order in which they appear, or the string **#all**. If set to **#all** (the default), all columns are shown in the order given. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies the number of rows which should be visible. Note: the requested width is determined from the sum of the column widths. 

Command-Line Name: **-padding** Database Name: **padding** Database Class: **Padding** 


Specifies the internal padding for the widget. The padding is a list of up to four length specifications; see **[Ttk\_GetPaddingFromObj()](https://www.tcl.tk/man/tcl/TkLib/ttk_Geometry.htm)** for details. 

Command-Line Name: **-selectmode** Database Name: **selectMode** Database Class: **SelectMode** 


Controls how the built-in class bindings manage the selection. One of **extended**, **browse**, or **none**.  If set to **extended** (the default), multiple items may be selected. If **browse**, only a single item will be selected at a time. If **none**, the selection will not be changed. 


 Note that application code and tag bindings can set the selection however they wish, regardless of the value of **-selectmode**. 



Command-Line Name: **-show** Database Name: **show** Database Class: **Show** 


A list containing zero or more of the following values, specifying which elements of the tree to display. 
 **tree**
 Display tree labels in column #0. 

**headings**
 Display the heading row. 

  The default is **tree headings**, i.e., show all elements. 


 **NOTE:** Column #0 always refers to the tree column, even if **-show tree** is not specified. 



 Widget command
--------------


 
*pathname* **bbox** *item* ?*column*?
 Returns the bounding box (relative to the treeview widget's window) of the specified *item* in the form *x y width height*. If *column* is specified, returns the bounding box of that cell. If the *item* is not visible (i.e., if it is a descendant of a closed item or is scrolled offscreen), returns the empty list. 


*pathname* **cget** *option*

 Returns the current value of the specified *option*; see *ttk::widget(n)*. 


*pathname* **children** *item* ?*newchildren*?
 If *newchildren* is not specified, returns the list of children belonging to *item*.  If *newchildren* is specified, replaces *item*'s child list with *newchildren*. Items in the old child list not present in the new child list are detached from the tree. None of the items in *newchildren* may be an ancestor of *item*. 




*pathname* **column** *column* ?*-option* ?*value -option value...*?
 Query or modify the options for the specified *column*. If no *-option* is specified, returns a dictionary of option/value pairs. If a single *-option* is specified, returns the value of that option. Otherwise, the options are updated with the specified values. The following options may be set on each column: 
 
**-id** *name*

 The column name. This is a read-only option. For example, [*$pathname* **column #***n* **-id**] returns the data column associated with display column #*n*. 

**-anchor**
 Specifies how the text in this column should be aligned with respect to the cell. One of **n**, **ne**, **e**, **se**, **s**, **sw**, **w**, **nw**, or **center**. 

**-minwidth**
 The minimum width of the column in pixels. The treeview widget will not make the column any smaller than **-minwidth** when the widget is resized or the user drags a column separator. 

**-stretch**
 Specifies whether or not the column's width should be adjusted when the widget is resized. 


**-width** *w*

 The width of the column in pixels. Default is something reasonable, probably 200 or so. 

Use *pathname column #0* to configure the tree column.




*pathname* **configure** ?*option*? ?*value option value ...*?
 Modify or query widget options; see *ttk::widget(n)*. 


*pathname* **delete** *itemList*

 Deletes each of the items in *itemList* and all of their descendants. The root item may not be deleted. See also: **detach**. 


*pathname* **detach** *itemList*

 Unlinks all of the specified items in *itemList* from the tree. The items and all of their descendants are still present and may be reinserted at another point in the tree with the **move** operation, but will not be displayed until that is done. The root item may not be detached. See also: **delete**. 


*pathname* **exists** *item*

 Returns 1 if the specified *item* is present in the tree, 0 otherwise. 


*pathname* **focus** ?*item*?
 If *item* is specified, sets the focus item to *item*. Otherwise, returns the current focus item, or **{}** if there is none. 


*pathname* **heading** *column* ?*-option* ?*value -option value...*?
 Query or modify the heading options for the specified *column*. Valid options are: 
 
**-text** *text*

 The text to display in the column heading. 


**-image** *imageName*

 Specifies an image to display to the right of the column heading. 


**-anchor** *anchor*

 Specifies how the heading text should be aligned. One of the standard Tk anchor values. 


**-command** *script*

 A script to evaluate when the heading label is pressed. 

Use *pathname heading #0* to configure the tree column heading.




*pathname* **identify** *component x y*

 Returns a description of the specified *component* under the point given by *x* and *y*, or the empty string if no such *component* is present at that position. The following subcommands are supported: 
 
*pathname* **identify region** *x y*

  Returns one of: 
 heading
 Tree heading area; use [**pathname identify column** *x y*] to determine the heading number. 

separator
 Space between two column headings; [**pathname identify column** *x y*] will return the display column identifier of the heading to left of the separator. 

tree
 The tree area. 

cell
 A data cell. 

  *pathname* **identify item** *x y* Returns the item ID of the item at position *y*. 


*pathname* **identify column** *x y*

 Returns the data column identifier of the cell at position *x*. The tree column has ID **#0**. 


*pathname* **identify element** *x y*

 The element at position *x,y*. 


*pathname* **identify row** *x y*

 Obsolescent synonym for *pathname* **identify item**. 

See **[COLUMN IDENTIFIERS](#M80)** for a discussion of display columns and data columns.




*pathname* **index** *item*

 Returns the integer index of *item* within its parent's list of children. 


*pathname* **insert** *parent index* ?**-id** *id*? *options...*

 Creates a new item. *parent* is the item ID of the parent item, or the empty string **{}** to create a new top-level item. *index* is an integer, or the value **end**, specifying where in the list of *parent*'s children to insert the new item. If *index* is less than or equal to zero, the new node is inserted at the beginning; if *index* is greater than or equal to the current number of children, it is inserted at the end. If **-id** is specified, it is used as the item identifier; *id* must not already exist in the tree. Otherwise, a new unique identifier is generated.  *pathname* **insert** returns the item identifier of the newly created item. See **[ITEM OPTIONS](#M69)** for the list of available options. 




*pathname* **instate** *statespec* ?*script*?
 Test the widget state; see *ttk::widget(n)*. 


*pathname* **item** *item* ?*-option* ?*value -option value...*?
 Query or modify the options for the specified *item*. If no *-option* is specified, returns a dictionary of option/value pairs. If a single *-option* is specified, returns the value of that option. Otherwise, the item's options are updated with the specified values. See **[ITEM OPTIONS](#M69)** for the list of available options. 


*pathname* **move** *item parent index*

 Moves *item* to position *index* in *parent*'s list of children. It is illegal to move an item under one of its descendants.  If *index* is less than or equal to zero, *item* is moved to the beginning; if greater than or equal to the number of children, it is moved to the end. 




*pathname* **next** *item*

 Returns the identifier of *item*'s next sibling, or **{}** if *item* is the last child of its parent. 


*pathname* **parent** *item*

 Returns the ID of the parent of *item*, or **{}** if *item* is at the top level of the hierarchy. 


*pathname* **prev** *item*

 Returns the identifier of *item*'s previous sibling, or **{}** if *item* is the first child of its parent. 


*pathname* **see** *item*

 Ensure that *item* is visible: sets all of *item*'s ancestors to **-open true**, and scrolls the widget if necessary so that *item* is within the visible portion of the tree. 


*pathname* **selection** ?*selop itemList*?
 If *selop* is not specified, returns the list of selected items. Otherwise, *selop* is one of the following: 
 
*pathname* **selection set** *itemList*

 *itemList* becomes the new selection. 


*pathname* **selection add** *itemList*

 Add *itemList* to the selection 


*pathname* **selection remove** *itemList*

 Remove *itemList* from the selection 


*pathname* **selection toggle** *itemList*

 Toggle the selection state of each item in *itemList*. 




*pathname* **set** *item* ?*column*? ?*value*?
 With one argument, returns a dictionary of column/value pairs for the specified *item*. With two arguments, returns the current value of the specified *column*. With three arguments, sets the value of column *column* in item *item* to the specified *value*. See also **[COLUMN IDENTIFIERS](#M80)**. 


*pathname* **state** ?*stateSpec*?
 Modify or query the widget state; see *ttk::widget(n)*. 


*pathName* **tag** *args...*


 
*pathName* **tag bind** *tagName* ?*sequence*? ?*script*?
 Add a Tk binding script for the event sequence *sequence* to the tag *tagName*. When an X event is delivered to an item, binding scripts for each of the item's **-tags** are evaluated in order as per *bindtags(n)*.  **<KeyPress>**, **<KeyRelease>**, and virtual events are sent to the focus item. **<ButtonPress>**, **<ButtonRelease>**, and **<Motion>** events are sent to the item under the mouse pointer. No other event types are supported. 


The binding *script* undergoes **%**-substitutions before evaluation; see **bind(n)** for details. 




*pathName* **tag configure** *tagName* ?*option*? ?*value option value...*?
 Query or modify the options for the specified *tagName*. If one or more *option/value* pairs are specified, sets the value of those options for the specified tag. If a single *option* is specified, returns the value of that option (or the empty string if the option has not been specified for *tagName*). With no additional arguments, returns a dictionary of the option settings for *tagName*. See **[TAG OPTIONS](#M75)** for the list of available options. 


*pathName* **tag has** *tagName* ?*item*?
 If *item* is specified, returns 1 or 0 depending on whether the specified item has the named tag. Otherwise, returns a list of all items which have the specified tag. 


*pathName* **tag names**

 Returns a list of all tags used by the widget. 


*pathName* **tag add** *tag items*

 Adds the specified *tag* to each of the listed *items*. If *tag* is already present for a particular item, then the **-tags** for that item are unchanged. 


*pathName* **tag remove** *tag* ?*items*?
 Removes the specified *tag* from each of the listed *items*. If *items* is omitted, removes *tag* from each item in the tree. If *tag* is not present for a particular item, then the **-tags** for that item are unchanged. 




*pathName* **xview** *args*

 Standard command for horizontal scrolling; see *widget(n)*. 


*pathName* **yview** *args*

 Standard command for vertical scrolling; see *ttk::widget(n)*. 

 Item options
------------

 The following item options may be specified for items in the **insert** and **item** widget commands.  Command-Line Name: **-text** Database Name: **text** Database Class: **Text** 


The textual label to display for the item. 

Command-Line Name: **-image** Database Name: **[image](image.htm)** Database Class: **[Image](image.htm)** 


A Tk image, displayed to the left of the label. 

Command-Line Name: **-values** Database Name: **values** Database Class: **Values** 


The list of values associated with the item.  Each item should have the same number of values as the **-columns** widget option. If there are fewer values than columns, the remaining values are assumed empty. If there are more values than columns, the extra values are ignored. 



Command-Line Name: **-open** Database Name: **open** Database Class: **Open** 


A boolean value indicating whether the item's children should be displayed (**-open true**) or hidden (**-open false**). 

Command-Line Name: **-tags** Database Name: **tags** Database Class: **Tags** 


A list of tags associated with this item. 
 Tag options
-----------

 The following options may be specified on tags: 
 **-foreground**
 Specifies the text foreground color. 

**-background**
 Specifies the cell or item background color. 

**-font**
 Specifies the font to use when drawing text. 

**-image**
 Specifies the item image, in case the item's **-image** option is empty. 

 Column identifiers
------------------

 Column identifiers take any of the following forms: 
* A symbolic name from the list of **-columns**.
* An integer *n*, specifying the *n*th data column.
* A string of the form **#***n*, where *n* is an integer, specifying the *n*th display column.

  **NOTE:** Item **-values** may be displayed in a different order than the order in which they are stored. 


 **NOTE:** Column #0 always refers to the tree column, even if **-show tree** is not specified. 


 A *data column number* is an index into an item's **-values** list; a *display column number* is the column number in the tree where the values are displayed. Tree labels are displayed in column #0. If **-displaycolumns** is not set, then data column *n* is displayed in display column **#***n+1*. Again, **column #0 always refers to the tree column**. 


Virtual events
--------------

 The treeview widget generates the following virtual events. 
 <<TreeviewSelect>>
 Generated whenever the selection changes. 

<<TreeviewOpen>>
 Generated just before setting the focus item to **-open true**. 

<<TreeviewClose>>
 Generated just after setting the focus item to **-open false**. 

  The **[focus](focus.htm)** and **[selection](selection.htm)** widget commands can be used to determine the affected item or items. 


See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[listbox](listbox.htm)**, **[image](image.htm)**, **[bind](bind.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_treeview.htm>

options
=======

  
[NAME](options.htm#M2) options — Standard options supported by widgets 
[DESCRIPTION](options.htm#M3)  
[-activebackground, activeBackground, Foreground](options.htm#M-activebackground) 
[-activeborderwidth, activeBorderWidth, BorderWidth](options.htm#M-activeborderwidth) 
[-activeforeground, activeForeground, Background](options.htm#M-activeforeground) 
[-anchor, anchor, Anchor](options.htm#M-anchor) 
[-background or -bg, background, Background](options.htm#M-background) 
[-bitmap, bitmap, Bitmap](options.htm#M-bitmap) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-compound, compound, Compound](options.htm#M-compound) 
[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground) 
[-exportselection, exportSelection, ExportSelection](options.htm#M-exportselection) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-image, image, Image](options.htm#M-image) 
[-insertbackground, insertBackground, Foreground](options.htm#M-insertbackground) 
[-insertborderwidth, insertBorderWidth, BorderWidth](options.htm#M-insertborderwidth) 
[-insertofftime, insertOffTime, OffTime](options.htm#M-insertofftime) 
[-insertontime, insertOnTime, OnTime](options.htm#M-insertontime) 
[-insertwidth, insertWidth, InsertWidth](options.htm#M-insertwidth) 
[-jump, jump, Jump](options.htm#M-jump) 
[-justify, justify, Justify](options.htm#M-justify) 
[-orient, orient, Orient](options.htm#M-orient) 
[-padx, padX, Pad](options.htm#M-padx) 
[-pady, padY, Pad](options.htm#M-pady) 
[-relief, relief, Relief](options.htm#M-relief) 
[-repeatdelay, repeatDelay, RepeatDelay](options.htm#M-repeatdelay) 
[-repeatinterval, repeatInterval, RepeatInterval](options.htm#M-repeatinterval) 
[-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground) 
[-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth) 
[-selectforeground, selectForeground, Background](options.htm#M-selectforeground) 
[-setgrid, setGrid, SetGrid](options.htm#M-setgrid) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-text, text, Text](options.htm#M-text) 
[-textvariable, textVariable, Variable](options.htm#M-textvariable) 
[-troughcolor, troughColor, Background](options.htm#M-troughcolor) 
[-underline, underline, Underline](options.htm#M-underline) 
[-wraplength, wrapLength, WrapLength](options.htm#M-wraplength) 
[-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand) 
[-yscrollcommand, yScrollCommand, ScrollCommand](options.htm#M-yscrollcommand) 









































 
[SEE ALSO](options.htm#M4) 
[KEYWORDS](options.htm#M5) 



 Name
----

 options — Standard options supported by widgets Description
-----------

 This manual entry describes the common configuration options supported by widgets in the Tk toolkit. Every widget does not necessarily support every option (see the manual entries for individual widgets for a list of the standard options supported by that widget), but if a widget does support an option with one of the names listed below, then the option has exactly the effect described below.  In the descriptions below, “Command-Line Name” refers to the switch used in class commands and **configure** widget commands to set this value. For example, if an option's command-line switch is **-foreground** and there exists a widget **.a.b.c**, then the command 



```
**.a.b.c configure -foreground black**
```
 may be used to specify the value **black** for the option in the widget **.a.b.c**. Command-line switches may be abbreviated, as long as the abbreviation is unambiguous. “Database Name” refers to the option's name in the option database (e.g. in .Xdefaults files). “Database Class” refers to the option's class value in the option database.  Command-Line Name: **-activebackground** Database Name: **activeBackground** Database Class: **Foreground** 


Specifies background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. If strict Motif compliance has been requested by setting the **tk\_strictMotif** variable, this option will normally be ignored; the normal background color will be used instead. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. 

Command-Line Name: **-activeborderwidth** Database Name: **activeBorderWidth** Database Class: **BorderWidth** 


Specifies a non-negative value indicating the width of the 3-D border drawn around active elements. See above for definition of active elements. The value may have any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. This option is typically only available in widgets displaying more than one element at a time (e.g. menus but not buttons). 

Command-Line Name: **-activeforeground** Database Name: **activeForeground** Database Class: **Background** 


Specifies foreground color to use when drawing active elements. See above for definition of active elements. 

Command-Line Name: **-anchor** Database Name: **anchor** Database Class: **Anchor** 


Specifies how the information in a widget (e.g. text or a bitmap) is to be displayed in the widget. Must be one of the values **n**, **ne**, **e**, **se**, **s**, **sw**, **w**, **nw**, or **center**. For example, **nw** means display the information such that its top-left corner is at the top-left corner of the widget. 

Command-Line Name: **-background or -bg** Database Name: **background** Database Class: **Background** 


Specifies the normal background color to use when displaying the widget. 

Command-Line Name: **-bitmap** Database Name: **bitmap** Database Class: **Bitmap** 


Specifies a bitmap to display in the widget, in any of the forms acceptable to **[Tk\_GetBitmap](https://www.tcl.tk/man/tcl/TkLib/GetBitmap.htm)**. The exact way in which the bitmap is displayed may be affected by other options such as **-anchor** or **-justify**. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget but this is controlled by the **-compound** option; the **-bitmap** option may be reset to an empty string to re-enable a text display. In widgets that support both **-bitmap** and **-image** options, **-image** will usually override **-bitmap**. 

Command-Line Name: **-borderwidth or -bd** Database Name: **borderWidth** Database Class: **BorderWidth** 


Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a border is being drawn; the **-relief** option typically determines this). The value may also be used when drawing 3-D effects in the interior of the widget. The value may have any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 

Command-Line Name: **-cursor** Database Name: **cursor** Database Class: **Cursor** 


Specifies the mouse cursor to be used for the widget. The value may have any of the forms acceptable to **[Tk\_GetCursor](https://www.tcl.tk/man/tcl/TkLib/GetCursor.htm)**. In addition, if an empty string is specified, it indicates that the widget should defer to its parent for cursor specification. 

Command-Line Name: **-compound** Database Name: **compound** Database Class: **Compound** 


Specifies if the widget should display text and bitmaps/images at the same time, and if so, where the bitmap/image should be placed relative to the text. Must be one of the values **none**, **bottom**, **top**, **left**, **right**, or **center**. For example, the (default) value **none** specifies that the bitmap or image should (if defined) be displayed instead of the text, the value **left** specifies that the bitmap or image should be displayed to the left of the text, and the value **center** specifies that the bitmap or image should be displayed on top of the text. 

Command-Line Name: **-disabledforeground** Database Name: **disabledForeground** Database Class: **DisabledForeground** 


Specifies foreground color to use when drawing a disabled element. If the option is specified as an empty string (which is typically the case on monochrome displays), disabled elements are drawn with the normal foreground color but they are dimmed by drawing them with a stippled fill pattern. 

Command-Line Name: **-exportselection** Database Name: **exportSelection** Database Class: **ExportSelection** 


Specifies whether or not a selection in the widget should also be the X selection. The value may have any of the forms accepted by **[Tcl\_GetBoolean](https://www.tcl.tk/man/tcl/TclLib/GetInt.htm)**, such as **true**, **false**, **0**, **1**, **yes**, or **no**. If the selection is exported, then selecting in the widget deselects the current X selection, selecting outside the widget deselects any widget selection, and the widget will respond to selection retrieval requests when it has a selection. The default is usually for widgets to export selections. 

Command-Line Name: **-font** Database Name: **[font](font.htm)** Database Class: **[Font](font.htm)** 


Specifies the font to use when drawing text inside the widget. The value may have any of the forms described in the **[font](font.htm)** manual page under **[FONT DESCRIPTION](font.htm)**. 

Command-Line Name: **-foreground or -fg** Database Name: **foreground** Database Class: **Foreground** 


Specifies the normal foreground color to use when displaying the widget. 

Command-Line Name: **-highlightbackground** Database Name: **highlightBackground** Database Class: **HighlightBackground** 


Specifies the color to display in the traversal highlight region when the widget does not have the input focus. 

Command-Line Name: **-highlightcolor** Database Name: **highlightColor** Database Class: **HighlightColor** 


Specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus. 

Command-Line Name: **-highlightthickness** Database Name: **highlightThickness** Database Class: **HighlightThickness** 


Specifies a non-negative value indicating the width of the highlight rectangle to draw around the outside of the widget when it has the input focus. The value may have any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. If the value is zero, no focus highlight is drawn around the widget. 

Command-Line Name: **-image** Database Name: **image** Database Class: **Image** 


Specifies an image to display in the widget, which must have been created with the **[image create](image.htm)** command. Typically, if the **-image** option is specified then it overrides other options that specify a bitmap or textual value to display in the widget, though this is controlled by the **-compound** option; the **-image** option may be reset to an empty string to re-enable a bitmap or text display. 

Command-Line Name: **-insertbackground** Database Name: **insertBackground** Database Class: **Foreground** 


Specifies the color to use as background in the area covered by the insertion cursor. This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the selection). 

Command-Line Name: **-insertborderwidth** Database Name: **insertBorderWidth** Database Class: **BorderWidth** 


Specifies a non-negative value indicating the width of the 3-D border to draw around the insertion cursor. The value may have any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 

Command-Line Name: **-insertofftime** Database Name: **insertOffTime** Database Class: **OffTime** 


Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain “off” in each blink cycle. If this option is zero then the cursor does not blink: it is on all the time. 

Command-Line Name: **-insertontime** Database Name: **insertOnTime** Database Class: **OnTime** 


Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain “on” in each blink cycle. 

Command-Line Name: **-insertwidth** Database Name: **insertWidth** Database Class: **InsertWidth** 


Specifies a value indicating the total width of the insertion cursor. The value may have any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. If a border has been specified for the insertion cursor (using the **-insertborderwidth** option), the border will be drawn inside the width specified by the **-insertwidth** option. 

Command-Line Name: **-jump** Database Name: **jump** Database Class: **Jump** 


For widgets with a slider that can be dragged to adjust a value, such as scrollbars, this option determines when notifications are made about changes in the value. The option's value must be a boolean of the form accepted by **[Tcl\_GetBoolean](https://www.tcl.tk/man/tcl/TclLib/GetInt.htm)**. If the value is false, updates are made continuously as the slider is dragged. If the value is true, updates are delayed until the mouse button is released to end the drag; at that point a single notification is made (the value “jumps” rather than changing smoothly). 

Command-Line Name: **-justify** Database Name: **justify** Database Class: **Justify** 


When there are multiple lines of text displayed in a widget, this option determines how the lines line up with each other. Must be one of **left**, **center**, or **right**. **Left** means that the lines' left edges all line up, **center** means that the lines' centers are aligned, and **right** means that the lines' right edges line up. 

Command-Line Name: **-orient** Database Name: **orient** Database Class: **Orient** 


For widgets that can lay themselves out with either a horizontal or vertical orientation, such as scrollbars, this option specifies which orientation should be used. Must be either **horizontal** or **vertical** or an abbreviation of one of these. 

Command-Line Name: **-padx** Database Name: **padX** Database Class: **Pad** 


Specifies a non-negative value indicating how much extra space to request for the widget in the X-direction. The value may have any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. When computing how large a window it needs, the widget will add this amount to the width it would normally need (as determined by the width of the things displayed in the widget); if the geometry manager can satisfy this request, the widget will end up with extra internal space to the left and/or right of what it displays inside. Most widgets only use this option for padding text: if they are displaying a bitmap or image, then they usually ignore padding options. 

Command-Line Name: **-pady** Database Name: **padY** Database Class: **Pad** 


Specifies a non-negative value indicating how much extra space to request for the widget in the Y-direction. The value may have any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. When computing how large a window it needs, the widget will add this amount to the height it would normally need (as determined by the height of the things displayed in the widget); if the geometry manager can satisfy this request, the widget will end up with extra internal space above and/or below what it displays inside. Most widgets only use this option for padding text: if they are displaying a bitmap or image, then they usually ignore padding options. 

Command-Line Name: **-relief** Database Name: **relief** Database Class: **Relief** 


Specifies the 3-D effect desired for the widget. Acceptable values are **raised**, **sunken**, **flat**, **ridge**, **solid**, and **groove**. The value indicates how the interior of the widget should appear relative to its exterior; for example, **raised** means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget. 

Command-Line Name: **-repeatdelay** Database Name: **repeatDelay** Database Class: **RepeatDelay** 


Specifies the number of milliseconds a button or key must be held down before it begins to auto-repeat. Used, for example, on the up- and down-arrows in scrollbars. 

Command-Line Name: **-repeatinterval** Database Name: **repeatInterval** Database Class: **RepeatInterval** 


Used in conjunction with **-repeatdelay**: once auto-repeat begins, this option determines the number of milliseconds between auto-repeats. 

Command-Line Name: **-selectbackground** Database Name: **selectBackground** Database Class: **Foreground** 


Specifies the background color to use when displaying selected items. 

Command-Line Name: **-selectborderwidth** Database Name: **selectBorderWidth** Database Class: **BorderWidth** 


Specifies a non-negative value indicating the width of the 3-D border to draw around selected items. The value may have any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 

Command-Line Name: **-selectforeground** Database Name: **selectForeground** Database Class: **Background** 


Specifies the foreground color to use when displaying selected items. 

Command-Line Name: **-setgrid** Database Name: **setGrid** Database Class: **SetGrid** 


Specifies a boolean value that determines whether this widget controls the resizing grid for its top-level window. This option is typically used in text widgets, where the information in the widget has a natural size (the size of a character) and it makes sense for the window's dimensions to be integral numbers of these units. These natural window sizes form a grid. If the **-setgrid** option is set to true then the widget will communicate with the window manager so that when the user interactively resizes the top-level window that contains the widget, the dimensions of the window will be displayed to the user in grid units and the window size will be constrained to integral numbers of grid units. See the section **GRIDDED GEOMETRY MANAGEMENT** in the **[wm](wm.htm)** manual entry for more details. 

Command-Line Name: **-takefocus** Database Name: **takeFocus** Database Class: **TakeFocus** 


Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal scripts consult the value of the **-takefocus** option. A value of **0** means that the window should be skipped entirely during keyboard traversal. **1** means that the window should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). An empty value for the option means that the traversal scripts make the decision about whether or not to focus on the window: the current algorithm is to skip the window if it is disabled, if it has no key bindings, or if it is not viewable. If the value has any other form, then the traversal scripts take the value, append the name of the window to it (with a separator space), and evaluate the resulting string as a Tcl script. The script must return **0**, **1**, or an empty string: a **0** or **1** value specifies whether the window will receive the input focus, and an empty string results in the default decision described above. Note: this interpretation of the option is defined entirely by the Tcl scripts that implement traversal: the widget implementations ignore the option entirely, so you can change its meaning if you redefine the keyboard traversal scripts. 

Command-Line Name: **-text** Database Name: **[text](text.htm)** Database Class: **[Text](text.htm)** 


Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as **-anchor** or **-justify**. 

Command-Line Name: **-textvariable** Database Name: **textVariable** Database Class: **[Variable](../tclcmd/variable.htm)** 


Specifies the name of a global variable. The value of the variable is a text string to be displayed inside the widget; if the variable value changes then the widget will automatically update itself to reflect the new value. The way in which the string is displayed in the widget depends on the particular widget and may be determined by other options, such as **-anchor** or **-justify**. 

Command-Line Name: **-troughcolor** Database Name: **troughColor** Database Class: **Background** 


Specifies the color to use for the rectangular trough areas in widgets such as scrollbars and scales. This option is ignored for scrollbars on Windows (native widget does not recognize this option). 

Command-Line Name: **-underline** Database Name: **underline** Database Class: **Underline** 


Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on. 

Command-Line Name: **-wraplength** Database Name: **wrapLength** Database Class: **WrapLength** 


For widgets that can perform word-wrapping, this option specifies the maximum line length. Lines that would exceed this length are wrapped onto the next line, so that no line is longer than the specified length. The value may be specified in any of the standard forms for screen distances. If this value is less than or equal to 0 then no wrapping is done: lines will break only at newline characters in the text. 

Command-Line Name: **-xscrollcommand** Database Name: **xScrollCommand** Database Class: **ScrollCommand** 


Specifies the prefix for a command used to communicate with horizontal scrollbars. When the view in the widget's window changes (or whenever anything else occurs that could change the display in a scrollbar, such as a change in the total size of the widget's contents), the widget will generate a Tcl command by concatenating the scroll command and two numbers. Each of the numbers is a fraction between 0 and 1, which indicates a position in the document. 0 indicates the beginning of the document, 1 indicates the end, .333 indicates a position one third the way through the document, and so on. The first fraction indicates the first information in the document that is visible in the window, and the second fraction indicates the information just after the last portion that is visible. The command is then passed to the Tcl interpreter for execution. Typically the **-xscrollcommand** option consists of the path name of a scrollbar widget followed by “set”, e.g. “.x.scrollbar set”: this will cause the scrollbar to be updated whenever the view in the window changes. If this option is not specified, then no command will be executed. 

Command-Line Name: **-yscrollcommand** Database Name: **yScrollCommand** Database Class: **ScrollCommand** 


Specifies the prefix for a command used to communicate with vertical scrollbars. This option is treated in the same way as the **-xscrollcommand** option, except that it is used for vertical scrollbars and is provided by widgets that support vertical scrolling. See the description of **-xscrollcommand** for details on how this option is used. 
 See also
--------

 **[colors](colors.htm)**, **[cursors](cursors.htm)**, **[font](font.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/options.htm>

ttk\_frame
==========

  
[NAME](ttk_frame.htm#M2) ttk::frame — Simple container widget 
[SYNOPSIS](ttk_frame.htm#M3) 
[DESCRIPTION](ttk_frame.htm#M4) 
[STANDARD OPTIONS](ttk_frame.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 



 
[WIDGET-SPECIFIC OPTIONS](ttk_frame.htm#M6)  
[-borderwidth, borderWidth, BorderWidth](ttk_frame.htm#M7) 
[-relief, relief, Relief](ttk_frame.htm#M8) 
[-padding, padding, Padding](ttk_frame.htm#M9) 
[-width, width, Width](ttk_frame.htm#M10) 
[-height, height, Height](ttk_frame.htm#M11) 




 
[WIDGET COMMAND](ttk_frame.htm#M12) 
[NOTES](ttk_frame.htm#M13) 
[SEE ALSO](ttk_frame.htm#M14) 
[KEYWORDS](ttk_frame.htm#M15) 








 Name
----

 ttk::frame — Simple container widget Synopsis
--------

 **ttk::frame** *pathName* ?*options*?  
 Description
-----------

 A **ttk::frame** widget is a container, used to group other widgets together. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 



 Widget-specific options
-----------------------

  Command-Line Name: **-borderwidth** Database Name: **borderWidth** Database Class: **BorderWidth** 


The desired width of the widget border. Defaults to 0. 

Command-Line Name: **-relief** Database Name: **relief** Database Class: **Relief** 


One of the standard Tk border styles: **flat**, **groove**, **raised**, **ridge**, **solid**, or **sunken**. Defaults to **flat**. 

Command-Line Name: **-padding** Database Name: **padding** Database Class: **Padding** 


Additional padding to include inside the border. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


If specified, the widget's requested width in pixels. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


If specified, the widget's requested height in pixels. 
 Widget command
--------------

 Supports the standard widget commands **configure**, **cget**, **identify**, **instate**, and **state**; see *ttk::widget(n)*. Notes
-----

 Note that if the **[pack](pack.htm)**, **[grid](grid.htm)**, or other geometry managers are used to manage the children of the **[frame](frame.htm)**, by the GM's requested size will normally take precedence over the **[frame](frame.htm)** widget's **-width** and **-height** options. **[pack propagate](pack.htm)** and **[grid propagate](grid.htm)** can be used to change this. See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[ttk::labelframe](ttk_labelframe.htm)**, **[frame](frame.htm)** Copyright © 2005 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_frame.htm>

panedwindow
===========

  
[NAME](panedwindow.htm#M2) panedwindow — Create and manipulate 'panedwindow' split container widgets 
[SYNOPSIS](panedwindow.htm#M3) 
[STANDARD OPTIONS](panedwindow.htm#M4)  
[-background or -bg, background, Background](options.htm#M-background) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-orient, orient, Orient](options.htm#M-orient) 
[-relief, relief, Relief](options.htm#M-relief) 




 
[WIDGET-SPECIFIC OPTIONS](panedwindow.htm#M5)  
[-handlepad, handlePad, HandlePad](panedwindow.htm#M6) 
[-handlesize, handleSize, HandleSize](panedwindow.htm#M7) 
[-height, height, Height](panedwindow.htm#M8) 
[-proxybackground, proxyBackground, ProxyBackground](panedwindow.htm#M9) 
[-proxyborderwidth, proxyBorderWidth, ProxyBorderWidth](panedwindow.htm#M10) 
[-proxyrelief, proxyRelief, ProxyRelief](panedwindow.htm#M11) 
[-opaqueresize, opaqueResize, OpaqueResize](panedwindow.htm#M12) 
[-sashcursor, sashCursor, SashCursor](panedwindow.htm#M13) 
[-sashpad, sashPad, SashPad](panedwindow.htm#M14) 
[-sashrelief, sashRelief, SashRelief](panedwindow.htm#M15) 
[-sashwidth, sashWidth, SashWidth](panedwindow.htm#M16) 
[-showhandle, showHandle, ShowHandle](panedwindow.htm#M17) 
[-width, width, Width](panedwindow.htm#M18) 












 
[DESCRIPTION](panedwindow.htm#M19) 
[WIDGET COMMAND](panedwindow.htm#M20)  
[*pathName* **add** *window* ?*window ...*? ?*option value ...*?](panedwindow.htm#M21) 
[*pathName* **cget** *option*](panedwindow.htm#M22) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](panedwindow.htm#M23) 
[*pathName* **forget** *window* ?*window ...*?](panedwindow.htm#M24) 
[*pathName* **identify** *x y*](panedwindow.htm#M25) 
[*pathName* **proxy** ?*args*?](panedwindow.htm#M26)  
[*pathName* **proxy coord**](panedwindow.htm#M27) 
[*pathName* **proxy forget**](panedwindow.htm#M28) 
[*pathName* **proxy place** *x y*](panedwindow.htm#M29) 


 
[*pathName* **sash** ?*args*?](panedwindow.htm#M30)  
[*pathName* **sash coord** *index*](panedwindow.htm#M31) 
[*pathName* **sash dragto** *index x y*](panedwindow.htm#M32) 
[*pathName* **sash mark** *index x y*](panedwindow.htm#M33) 
[*pathName* **sash place** *index x y*](panedwindow.htm#M34) 



 
[*pathName* **panecget** *window option*](panedwindow.htm#M35) 
[*pathName* **paneconfigure** *window* ?*option*? ?*value option value ...*?](panedwindow.htm#M36)  
[**-after** *window*](panedwindow.htm#M37) 
[**-before** *window*](panedwindow.htm#M38) 
[**-height** *size*](panedwindow.htm#M39) 
[**-hide** *boolean*](panedwindow.htm#M40) 
[**-minsize** *n*](panedwindow.htm#M41) 
[**-padx** *n*](panedwindow.htm#M42) 
[**-pady** *n*](panedwindow.htm#M43) 
[**-sticky** *style*](panedwindow.htm#M44) 
[**-stretch** *when*](panedwindow.htm#M45)  
[**always**](panedwindow.htm#M46) 
[**first**](panedwindow.htm#M47) 
[**last**](panedwindow.htm#M48) 
[**middle**](panedwindow.htm#M49) 
[**never**](panedwindow.htm#M50) 




 
[**-width** *size*](panedwindow.htm#M51) 









 
[*pathName* **panes**](panedwindow.htm#M52) 









 
[RESIZING PANES](panedwindow.htm#M53) 
[SEE ALSO](panedwindow.htm#M54) 
[KEYWORDS](panedwindow.htm#M55) 








 Name
----

 panedwindow — Create and manipulate 'panedwindow' split container widgets Synopsis
--------

 **panedwindow** *pathName* ?*options*?  
 Standard options
----------------

  
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-orient, orient, Orient](options.htm#M-orient)** 
**[-relief, relief, Relief](options.htm#M-relief)** 




 Widget-specific options
-----------------------

  Command-Line Name: **-handlepad** Database Name: **handlePad** Database Class: **HandlePad** 


When sash handles are drawn, specifies the distance from the top or left end of the sash (depending on the orientation of the widget) at which to draw the handle. May be any value accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 

Command-Line Name: **-handlesize** Database Name: **handleSize** Database Class: **HandleSize** 


Specifies the side length of a sash handle. Handles are always drawn as squares. May be any value accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies a desired height for the overall panedwindow widget. May be any value accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. If an empty string, the widget will be made high enough to allow all contained widgets to have their natural height. 

Command-Line Name: **-proxybackground** Database Name: **proxyBackground** Database Class: **ProxyBackground** 


Background color to use when drawing the proxy. If an empty string, the value of the **-background** option will be used. 

Command-Line Name: **-proxyborderwidth** Database Name: **proxyBorderWidth** Database Class: **ProxyBorderWidth** 


Specifies the borderwidth of the proxy. May be any value accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 

Command-Line Name: **-proxyrelief** Database Name: **proxyRelief** Database Class: **ProxyRelief** 


Relief to use when drawing the proxy. May be any of the standard Tk relief values. If an empty string, the value of the **-sashrelief** option will be used. 

Command-Line Name: **-opaqueresize** Database Name: **opaqueResize** Database Class: **OpaqueResize** 


Specifies whether panes should be resized as a sash is moved (true), or if resizing should be deferred until the sash is placed (false). 

Command-Line Name: **-sashcursor** Database Name: **sashCursor** Database Class: **SashCursor** 


Mouse cursor to use when over a sash. If null, **sb\_h\_double\_arrow** will be used for horizontal panedwindows, and **sb\_v\_double\_arrow** will be used for vertical panedwindows. 

Command-Line Name: **-sashpad** Database Name: **sashPad** Database Class: **SashPad** 


Specifies the amount of padding to leave of each side of a sash. May be any value accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 

Command-Line Name: **-sashrelief** Database Name: **sashRelief** Database Class: **SashRelief** 


Relief to use when drawing a sash. May be any of the standard Tk relief values. 

Command-Line Name: **-sashwidth** Database Name: **sashWidth** Database Class: **SashWidth** 


Specifies the width of each sash. May be any value accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 

Command-Line Name: **-showhandle** Database Name: **showHandle** Database Class: **ShowHandle** 


Specifies whether sash handles should be shown. May be any valid Tcl boolean value. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies a desired width for the overall panedwindow widget. May be any value accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. If an empty string, the widget will be made wide enough to allow all contained widgets to have their natural width. 
 Description
-----------

 The **panedwindow** command creates a new window (given by the *pathName* argument) and makes it into a panedwindow widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the panedwindow such as its default background color and relief. The **panedwindow** command returns the path name of the new window.  A panedwindow widget contains any number of panes, arranged horizontally or vertically, according to the value of the **-orient** option. Each pane contains one widget, and each pair of panes is separated by a moveable (via mouse movements) sash. Moving a sash causes the widgets on either side of the sash to be resized. 


Widget command
--------------

 The **panedwindow** command creates a new Tcl command whose name is the same as the path name of the panedwindow's window. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *PathName* is the name of the command, which is the same as the panedwindow widget's path name. *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for panedwindow widgets: 
 
*pathName* **add** *window* ?*window ...*? ?*option value ...*?
 Add one or more windows to the panedwindow, each in a separate pane. The arguments consist of the names of one or more windows followed by pairs of arguments that specify how to manage the windows. *Option* may have any of the values accepted by the **configure** subcommand. 


*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **panedwindow** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **panedwindow** command. 


*pathName* **forget** *window* ?*window ...*?
 Remove the pane containing *window* from the panedwindow. All geometry management options for *window* will be forgotten. 


*pathName* **identify** *x y*

 Identify the panedwindow component underneath the point given by *x* and *y*, in window coordinates. If the point is over a sash or a sash handle, the result is a two element list containing the index of the sash or handle, and a word indicating whether it is over a sash or a handle, such as {0 sash} or {2 handle}. If the point is over any other part of the panedwindow, the result is an empty list. 


*pathName* **proxy** ?*args*?
 This command is used to query and change the position of the sash proxy, used for rubberband-style pane resizing. It can take any of the following forms: 
 
*pathName* **proxy coord**

 Return a list containing the x and y coordinates of the most recent proxy location. 


*pathName* **proxy forget**

 Remove the proxy from the display. 


*pathName* **proxy place** *x y*

 Place the proxy at the given *x* and *y* coordinates. 




*pathName* **sash** ?*args*?
 This command is used to query and change the position of sashes in the panedwindow. It can take any of the following forms: 
 
*pathName* **sash coord** *index*

 Return the current x and y coordinate pair for the sash given by *index*. *Index* must be an integer between 0 and 1 less than the number of panes in the panedwindow. The coordinates given are those of the top left corner of the region containing the sash. 


*pathName* **sash dragto** *index x y*

 This command computes the difference between the given coordinates and the coordinates given to the last **sash mark** command for the given sash. It then moves that sash the computed difference. The return value is the empty string. 


*pathName* **sash mark** *index x y*

 Records *x* and *y* for the sash given by *index*; used in conjunction with later **sash dragto** commands to move the sash. 


*pathName* **sash place** *index x y*

 Place the sash given by *index* at the given coordinates. 




*pathName* **panecget** *window option*

 Query a management option for *window*. *Option* may be any value allowed by the **paneconfigure** subcommand. 


*pathName* **paneconfigure** *window* ?*option*? ?*value option value ...*?
 Query or modify the management options for *window*. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. The following options are supported: 
 
**-after** *window*

 Insert the window after the window specified. *window* should be the name of a window already managed by *pathName*. 


**-before** *window*

 Insert the window before the window specified. *window* should be the name of a window already managed by *pathName*. 


**-height** *size*

 Specify a height for the window. The height will be the outer dimension of the window including its border, if any. If *size* is an empty string, or if **-height** is not specified, then the height requested internally by the window will be used initially; the height may later be adjusted by the movement of sashes in the panedwindow. *Size* may be any value accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 


**-hide** *boolean*

 Controls the visibility of a pane. When the *boolean* is true (according to **[Tcl\_GetBoolean](https://www.tcl.tk/man/tcl/TclLib/GetInt.htm)**) the pane will not be visible, but it will still be maintained in the list of panes. 


**-minsize** *n*

 Specifies that the size of the window cannot be made less than *n*. This constraint only affects the size of the widget in the paned dimension — the x dimension for horizontal panedwindows, the y dimension for vertical panedwindows. May be any value accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 


**-padx** *n*

 Specifies a non-negative value indicating how much extra space to leave on each side of the window in the X-direction. The value may have any of the forms accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 


**-pady** *n*

 Specifies a non-negative value indicating how much extra space to leave on each side of the window in the Y-direction. The value may have any of the forms accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 


**-sticky** *style*

 If a window's pane is larger than the requested dimensions of the window, this option may be used to position (or stretch) the window within its pane. *Style* is a string that contains zero or more of the characters **n**, **s**, **e** or **w**. The string can optionally contains spaces or commas, but they are ignored. Each letter refers to a side (north, south, east, or west) that the window will “stick” to. If both **n** and **s** (or **e** and **w**) are specified, the window will be stretched to fill the entire height (or width) of its cavity. 


**-stretch** *when*

 Controls how extra space is allocated to each of the panes. *When* is one of **always**, **first**, **last**, **middle**, and **never**. The panedwindow will calculate the required size of all its panes. Any remaining (or deficit) space will be distributed to those panes marked for stretching. The space will be distributed based on each panes current ratio of the whole. The *when* values have the following definition: 
 **always**
 This pane will always stretch. 

**first**
 Only if this pane is the first pane (left-most or top-most) will it stretch. 

**last**
 Only if this pane is the last pane (right-most or bottom-most) will it stretch. This is the default value. 

**middle**
 Only if this pane is not the first or last pane will it stretch. 

**never**
 This pane will never stretch. 




**-width** *size*

 Specify a width for the window. The width will be the outer dimension of the window including its border, if any. If *size* is an empty string, or if **-width** is not specified, then the width requested internally by the window will be used initially; the width may later be adjusted by the movement of sashes in the panedwindow. *Size* may be any value accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. 




*pathName* **panes**

 Returns an ordered list of the widgets managed by *pathName*. 

 Resizing panes
--------------

 A pane is resized by grabbing the sash (or sash handle if present) and dragging with the mouse. This is accomplished via mouse motion bindings on the widget. When a sash is moved, the sizes of the panes on each side of the sash, and thus the widgets in those panes, are adjusted.  When a pane is resized from outside (e.g. it is packed to expand and fill, and the containing toplevel is resized), space is added to the final (rightmost or bottommost) pane in the window. 


 Unlike slave windows managed by e.g. pack or grid, the panes managed by a panedwindow do not change width or height to accomodate changes in the requested widths or heights of the panes, once these have become mapped. Therefore it may be advisable, particularly when creating layouts interactively, to not add a pane to the panedwindow widget until after the geometry requests of that pane has been finalized (i.e., all components of the pane inserted, all options affecting geometry set to their proper values, etc.). 


See also
--------

 **[ttk::panedwindow](ttk_panedwindow.htm)** Copyright © 1992 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/panedwindow.htm>

raise
=====

 Name
----

 raise — Change a window's position in the stacking order Synopsis
--------

 **raise** *window* ?*aboveThis*?  
 Description
-----------

 If the *aboveThis* argument is omitted then the command raises *window* so that it is above all of its siblings in the stacking order (it will not be obscured by any siblings and will obscure any siblings that overlap it). If *aboveThis* is specified then it must be the path name of a window that is either a sibling of *window* or the descendant of a sibling of *window*. In this case the **raise** command will insert *window* into the stacking order just above *aboveThis* (or the ancestor of *aboveThis* that is a sibling of *window*); this could end up either raising or lowering *window*.  All **[toplevel](toplevel.htm)** windows may be restacked with respect to each other, whatever their relative path names, but the window manager is not obligated to strictly honor requests to restack. 


Example
-------

 Make a button appear to be in a sibling frame that was created after it. This is is often necessary when building GUIs in the style where you create your activity widgets first before laying them out on the display: 
```
button .b -text "Hi there!"
pack [frame .f -background blue]
pack [label .f.l1 -text "This is above"]
pack .b -in .f
pack [label .f.l2 -text "This is below"]
**raise** .b
```
 See also
--------

 **[lower](lower.htm)** Copyright © 1990 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/raise.htm>

place
=====

  
[NAME](place.htm#M2) place — Geometry manager for fixed or rubber-sheet placement 
[SYNOPSIS](place.htm#M3) 
[DESCRIPTION](place.htm#M4)  
[**place** *window option value* ?*option value ...*?](place.htm#M5) 
[**place configure** *window* ?*option*? ?*value option value ...*?](place.htm#M6)  
[**-anchor** *where*](place.htm#M7) 
[**-bordermode** *mode*](place.htm#M8) 
[**-height** *size*](place.htm#M9) 
[**-in** *master*](place.htm#M10) 
[**-relheight** *size*](place.htm#M11) 
[**-relwidth** *size*](place.htm#M12) 
[**-relx** *location*](place.htm#M13) 
[**-rely** *location*](place.htm#M14) 
[**-width** *size*](place.htm#M15) 
[**-x** *location*](place.htm#M16) 
[**-y** *location*](place.htm#M17) 










 
[**place forget** *window*](place.htm#M18) 
[**place info** *window*](place.htm#M19) 
[**place slaves** *window*](place.htm#M20) 




 
[FINE POINTS](place.htm#M21) 
[EXAMPLE](place.htm#M22) 
[SEE ALSO](place.htm#M23) 
[KEYWORDS](place.htm#M24) 






 Name
----

 place — Geometry manager for fixed or rubber-sheet placement Synopsis
--------

 **place** *option arg* ?*arg ...*?  
 Description
-----------

 The placer is a geometry manager for Tk. It provides simple fixed placement of windows, where you specify the exact size and location of one window, called the *slave*, within another window, called the *master*. The placer also provides rubber-sheet placement, where you specify the size and location of the slave in terms of the dimensions of the master, so that the slave changes size and location in response to changes in the size of the master. Lastly, the placer allows you to mix these styles of placement so that, for example, the slave has a fixed width and height but is centered inside the master. 

 
**place** *window option value* ?*option value ...*?
 Arrange for the placer to manage the geometry of a slave whose pathName is *window*. The remaining arguments consist of one or more *option-value* pairs that specify the way in which *window*'s geometry is managed. *Option* may have any of the values accepted by the **place configure** command. 


**place configure** *window* ?*option*? ?*value option value ...*?
 Query or modify the geometry options of the slave given by *window*. If no *option* is specified, this command returns a list describing the available options (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string.  The following *option-value* pairs are supported: 


 
**-anchor** *where*

 *Where* specifies which point of *window* is to be positioned at the (x,y) location selected by the **-x**, **-y**, **-relx**, and **-rely** options. The anchor point is in terms of the outer area of *window* including its border, if any. Thus if *where* is **se** then the lower-right corner of *window*'s border will appear at the given (x,y) location in the master. The anchor position defaults to **nw**. 


**-bordermode** *mode*

 *Mode* determines the degree to which borders within the master are used in determining the placement of the slave. The default and most common value is **inside**. In this case the placer considers the area of the master to be the innermost area of the master, inside any border: an option of **-x 0** corresponds to an x-coordinate just inside the border and an option of **-relwidth 1.0** means *window* will fill the area inside the master's border.  If *mode* is **outside** then the placer considers the area of the master to include its border; this mode is typically used when placing *window* outside its master, as with the options **-x 0 -y 0 -anchor ne**. Lastly, *mode* may be specified as **ignore**, in which case borders are ignored: the area of the master is considered to be its official X area, which includes any internal border but no external border. A bordermode of **ignore** is probably not very useful. 




**-height** *size*

 *Size* specifies the height for *window* in screen units (i.e. any of the forms accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**). The height will be the outer dimension of *window* including its border, if any. If *size* is an empty string, or if no **-height** or **-relheight** option is specified, then the height requested internally by the window will be used. 


**-in** *master*

 *Master* specifies the path name of the window relative to which *window* is to be placed. *Master* must either be *window*'s parent or a descendant of *window*'s parent. In addition, *master* and *window* must both be descendants of the same top-level window. These restrictions are necessary to guarantee that *window* is visible whenever *master* is visible. If this option is not specified then the master defaults to *window*'s parent. 


**-relheight** *size*

 *Size* specifies the height for *window*. In this case the height is specified as a floating-point number relative to the height of the master: 0.5 means *window* will be half as high as the master, 1.0 means *window* will have the same height as the master, and so on. If both **-height** and **-relheight** are specified for a slave, their values are summed. For example, **-relheight 1.0 -height -2** makes the slave 2 pixels shorter than the master. 


**-relwidth** *size*

 *Size* specifies the width for *window*. In this case the width is specified as a floating-point number relative to the width of the master: 0.5 means *window* will be half as wide as the master, 1.0 means *window* will have the same width as the master, and so on. If both **-width** and **-relwidth** are specified for a slave, their values are summed. For example, **-relwidth 1.0 -width 5** makes the slave 5 pixels wider than the master. 


**-relx** *location*

 *Location* specifies the x-coordinate within the master window of the anchor point for *window*. In this case the location is specified in a relative fashion as a floating-point number: 0.0 corresponds to the left edge of the master and 1.0 corresponds to the right edge of the master. *Location* need not be in the range 0.0-1.0. If both **-x** and **-relx** are specified for a slave then their values are summed. For example, **-relx 0.5 -x -2** positions the left edge of the slave 2 pixels to the left of the center of its master. 


**-rely** *location*

 *Location* specifies the y-coordinate within the master window of the anchor point for *window*. In this case the value is specified in a relative fashion as a floating-point number: 0.0 corresponds to the top edge of the master and 1.0 corresponds to the bottom edge of the master. *Location* need not be in the range 0.0-1.0. If both **-y** and **-rely** are specified for a slave then their values are summed. For example, **-rely 0.5 -x 3** positions the top edge of the slave 3 pixels below the center of its master. 


**-width** *size*

 *Size* specifies the width for *window* in screen units (i.e. any of the forms accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**). The width will be the outer width of *window* including its border, if any. If *size* is an empty string, or if no **-width** or **-relwidth** option is specified, then the width requested internally by the window will be used. 


**-x** *location*

 *Location* specifies the x-coordinate within the master window of the anchor point for *window*. The location is specified in screen units (i.e. any of the forms accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**) and need not lie within the bounds of the master window. 


**-y** *location*

 *Location* specifies the y-coordinate within the master window of the anchor point for *window*. The location is specified in screen units (i.e. any of the forms accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**) and need not lie within the bounds of the master window. 

If the same value is specified separately with two different options, such as **-x** and **-relx**, then the most recent option is used and the older one is ignored.




**place forget** *window*

 Causes the placer to stop managing the geometry of *window*. As a side effect of this command *window* will be unmapped so that it does not appear on the screen. If *window* is not currently managed by the placer then the command has no effect. This command returns an empty string. 


**place info** *window*

 Returns a list giving the current configuration of *window*. The list consists of *option-value* pairs in exactly the same form as might be specified to the **place configure** command. 


**place slaves** *window*

 Returns a list of all the slave windows for which *window* is the master. If there are no slaves for *window* then an empty string is returned. 

  If the configuration of a window has been retrieved with **place info**, that configuration can be restored later by first using **place forget** to erase any existing information for the window and then invoking **place configure** with the saved information. 


Fine points
-----------

 It is not necessary for the master window to be the parent of the slave window. This feature is useful in at least two situations. First, for complex window layouts it means you can create a hierarchy of subwindows whose only purpose is to assist in the layout of the parent. The “real children” of the parent (i.e. the windows that are significant for the application's user interface) can be children of the parent yet be placed inside the windows of the geometry-management hierarchy. This means that the path names of the “real children” do not reflect the geometry-management hierarchy and users can specify options for the real children without being aware of the structure of the geometry-management hierarchy.  A second reason for having a master different than the slave's parent is to tie two siblings together. For example, the placer can be used to force a window always to be positioned centered just below one of its siblings by specifying the configuration 



```
**-in** *sibling* **-relx 0.5 -rely 1.0 -anchor n -bordermode outside**
```
 Whenever the sibling is repositioned in the future, the slave will be repositioned as well.  Unlike many other geometry managers (such as the packer) the placer does not make any attempt to manipulate the geometry of the master windows or the parents of slave windows (i.e. it does not set their requested sizes). To control the sizes of these windows, make them windows like frames and canvases that provide configuration options for this purpose. 


Example
-------

 Make the label occupy the middle bit of the toplevel, no matter how it is resized: 
```
label .l -text "In the\nMiddle!" -bg black -fg white
**place** .l -relwidth .3 -relx .35 -relheight .3 -rely .35
```
 See also
--------

 **[grid](grid.htm)**, **[pack](pack.htm)** Copyright © 1992 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/place.htm>

entry
=====

  
[NAME](entry.htm#M2) entry — Create and manipulate 'entry' one-line text entry widgets 
[SYNOPSIS](entry.htm#M3) 
[STANDARD OPTIONS](entry.htm#M4)  
[-background or -bg, background, Background](options.htm#M-background) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-exportselection, exportSelection, ExportSelection](options.htm#M-exportselection) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-insertbackground, insertBackground, Foreground](options.htm#M-insertbackground) 
[-insertborderwidth, insertBorderWidth, BorderWidth](options.htm#M-insertborderwidth) 
[-insertofftime, insertOffTime, OffTime](options.htm#M-insertofftime) 
[-insertontime, insertOnTime, OnTime](options.htm#M-insertontime) 
[-insertwidth, insertWidth, InsertWidth](options.htm#M-insertwidth) 
[-justify, justify, Justify](options.htm#M-justify) 
[-relief, relief, Relief](options.htm#M-relief) 
[-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground) 
[-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth) 
[-selectforeground, selectForeground, Background](options.htm#M-selectforeground) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-textvariable, textVariable, Variable](options.htm#M-textvariable) 
[-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand) 





















 
[WIDGET-SPECIFIC OPTIONS](entry.htm#M5)  
[-disabledbackground, disabledBackground, DisabledBackground](entry.htm#M6) 
[-disabledforeground, disabledForeground, DisabledForeground](entry.htm#M7) 
[-invalidcommand or -invcmd, invalidCommand, InvalidCommand](entry.htm#M8) 
[-readonlybackground, readonlyBackground, ReadonlyBackground](entry.htm#M9) 
[-show, show, Show](entry.htm#M10) 
[-state, state, State](entry.htm#M11) 
[-validate, validate, Validate](entry.htm#M12) 
[-validatecommand or -vcmd, validateCommand, ValidateCommand](entry.htm#M13) 
[-width, width, Width](entry.htm#M14) 








 
[DESCRIPTION](entry.htm#M15) 
[VALIDATION](entry.htm#M16)  
[**none**](entry.htm#M17) 
[**focus**](entry.htm#M18) 
[**focusin**](entry.htm#M19) 
[**focusout**](entry.htm#M20) 
[**key**](entry.htm#M21) 
[**all**](entry.htm#M22) 





  
[**%d**](entry.htm#M23) 
[**%i**](entry.htm#M24) 
[**%P**](entry.htm#M25) 
[**%s**](entry.htm#M26) 
[**%S**](entry.htm#M27) 
[**%v**](entry.htm#M28) 
[**%V**](entry.htm#M29) 
[**%W**](entry.htm#M30) 







 
[WIDGET COMMAND](entry.htm#M31) 
[INDICES](entry.htm#M32)  
[*number*](entry.htm#M33) 
[**anchor**](entry.htm#M34) 
[**end**](entry.htm#M35) 
[**insert**](entry.htm#M36) 
[**sel.first**](entry.htm#M37) 
[**sel.last**](entry.htm#M38) 
[**@***number*](entry.htm#M39) 






 
[SUBCOMMANDS](entry.htm#M40)  
[*pathName* **bbox** *index*](entry.htm#M41) 
[*pathName* **cget** *option*](entry.htm#M42) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](entry.htm#M43) 
[*pathName* **delete** *first* ?*last*?](entry.htm#M44) 
[*pathName* **get**](entry.htm#M45) 
[*pathName* **icursor** *index*](entry.htm#M46) 
[*pathName* **index** *index*](entry.htm#M47) 
[*pathName* **insert** *index string*](entry.htm#M48) 
[*pathName* **scan** *option args*](entry.htm#M49)  
[*pathName* **scan mark** *x*](entry.htm#M50) 
[*pathName* **scan dragto** *x*](entry.htm#M51) 

 
[*pathName* **selection** *option arg*](entry.htm#M52)  
[*pathName* **selection adjust** *index*](entry.htm#M53) 
[*pathName* **selection clear**](entry.htm#M54) 
[*pathName* **selection from** *index*](entry.htm#M55) 
[*pathName* **selection present**](entry.htm#M56) 
[*pathName* **selection range** *start* *end*](entry.htm#M57) 
[*pathName* **selection to** *index*](entry.htm#M58) 





 
[*pathName* **validate**](entry.htm#M59) 
[*pathName* **xview** *args*](entry.htm#M60)  
[*pathName* **xview**](entry.htm#M61) 
[*pathName* **xview** *index*](entry.htm#M62) 
[*pathName* **xview moveto** *fraction*](entry.htm#M63) 
[*pathName* **xview scroll** *number what*](entry.htm#M64) 



 











 
[DEFAULT BINDINGS](entry.htm#M65) 
[SEE ALSO](entry.htm#M66) 
[KEYWORDS](entry.htm#M67) 











 Name
----

 entry — Create and manipulate 'entry' one-line text entry widgets Synopsis
--------

 **entry** *pathName* ?*options*?  
 Standard options
----------------

  
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-exportselection, exportSelection, ExportSelection](options.htm#M-exportselection)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-insertbackground, insertBackground, Foreground](options.htm#M-insertbackground)** 
**[-insertborderwidth, insertBorderWidth, BorderWidth](options.htm#M-insertborderwidth)** 
**[-insertofftime, insertOffTime, OffTime](options.htm#M-insertofftime)** 
**[-insertontime, insertOnTime, OnTime](options.htm#M-insertontime)** 
**[-insertwidth, insertWidth, InsertWidth](options.htm#M-insertwidth)** 
**[-justify, justify, Justify](options.htm#M-justify)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground)** 
**[-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth)** 
**[-selectforeground, selectForeground, Background](options.htm#M-selectforeground)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-textvariable, textVariable, Variable](options.htm#M-textvariable)** 
**[-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand)** 





















 Widget-specific options
-----------------------

  Command-Line Name: **-disabledbackground** Database Name: **disabledBackground** Database Class: **DisabledBackground** 


Specifies the background color to use when the entry is disabled. If this option is the empty string, the normal background color is used. 

Command-Line Name: **-disabledforeground** Database Name: **disabledForeground** Database Class: **DisabledForeground** 


Specifies the foreground color to use when the entry is disabled. If this option is the empty string, the normal foreground color is used. 

Command-Line Name: **-invalidcommand or -invcmd** Database Name: **invalidCommand** Database Class: **InvalidCommand** 


Specifies a script to eval when **-validatecommand** returns 0. Setting it to {} disables this feature (the default). The best use of this option is to set it to *bell*. See **[VALIDATION](#M16)** below for more information. 

Command-Line Name: **-readonlybackground** Database Name: **readonlyBackground** Database Class: **ReadonlyBackground** 


Specifies the background color to use when the entry is readonly. If this option is the empty string, the normal background color is used. 

Command-Line Name: **-show** Database Name: **show** Database Class: **Show** 


If this option is specified, then the true contents of the entry are not displayed in the window. Instead, each character in the entry's value will be displayed as the first character in the value of this option, such as “\*”. This is useful, for example, if the entry is to be used to enter a password. If characters in the entry are selected and copied elsewhere, the information copied will be what is displayed, not the true contents of the entry. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Specifies one of three states for the entry: **normal**, **disabled**, or **readonly**. If the entry is readonly, then the value may not be changed using widget commands and no insertion cursor will be displayed, even if the input focus is in the widget; the contents of the widget may still be selected. If the entry is disabled, the value may not be changed, no insertion cursor will be displayed, the contents will not be selectable, and the entry may be displayed in a different color, depending on the values of the **-disabledforeground** and **-disabledbackground** options. 

Command-Line Name: **-validate** Database Name: **validate** Database Class: **Validate** 


Specifies the mode in which validation should operate: **none**, **[focus](focus.htm)**, **focusin**, **focusout**, **key**, or **all**. It defaults to **none**. When you want validation, you must explicitly state which mode you wish to use. See **[VALIDATION](#M16)** below for more. 

Command-Line Name: **-validatecommand or -vcmd** Database Name: **validateCommand** Database Class: **ValidateCommand** 


Specifies a script to eval when you want to validate the input into the entry widget. Setting it to {} disables this feature (the default). This command must return a valid Tcl boolean value. If it returns 0 (or the valid Tcl boolean equivalent) then it means you reject the new edition and it will not occur and the **-invalidcommand** will be evaluated if it is set. If it returns 1, then the new edition occurs. See **[VALIDATION](#M16)** below for more information. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies an integer value indicating the desired width of the entry window, in average-size characters of the widget's font. If the value is less than or equal to zero, the widget picks a size just large enough to hold its current text. 
 Description
-----------

 The **entry** command creates a new window (given by the *pathName* argument) and makes it into an entry widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the entry such as its colors, font, and relief. The **entry** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  An entry is a widget that displays a one-line text string and allows that string to be edited using widget commands described below, which are typically bound to keystrokes and mouse actions. When first created, an entry's string is empty. A portion of the entry may be selected as described below. If an entry is exporting its selection (see the **-exportselection** option), then it will observe the standard X11 protocols for handling the selection; entry selections are available as type **STRING**. Entries also observe the standard Tk rules for dealing with the input focus. When an entry has the input focus it displays an *insertion cursor* to indicate where new characters will be inserted. 


 Entries are capable of displaying strings that are too long to fit entirely within the widget's window. In this case, only a portion of the string will be displayed; commands described below may be used to change the view in the window. Entries use the standard **-xscrollcommand** mechanism for interacting with scrollbars (see the description of the **-xscrollcommand** option for details). They also support scanning, as described below. 


Validation
----------

 Validation works by setting the **-validatecommand** option to a script (*validateCommand*) which will be evaluated according to the **-validate** option as follows: 

 **none**
 Default. This means no validation will occur. 

**focus**
 *validateCommand* will be called when the entry receives or loses focus. 

**focusin**
 *validateCommand* will be called when the entry receives focus. 

**focusout**
 *validateCommand* will be called when the entry loses focus. 

**key**
 *validateCommand* will be called when the entry is edited. 

**all**
 *validateCommand* will be called for all above conditions. 

  It is possible to perform percent substitutions on the value of the **-validatecommand** and **-invalidcommand** options, just as you would in a **[bind](bind.htm)** script. The following substitutions are recognized: 


 **%d**
 Type of action: 1 for **insert**, 0 for **delete**, or -1 for focus, forced or textvariable validation. 

**%i**
 Index of char string to be inserted/deleted, if any, otherwise -1. 

**%P**
 The value of the entry if the edit is allowed. If you are configuring the entry widget to have a new textvariable, this will be the value of that textvariable. 

**%s**
 The current value of entry prior to editing. 

**%S**
 The text string being inserted/deleted, if any, {} otherwise. 

**%v**
 The type of validation currently set. 

**%V**
 The type of validation that triggered the callback (key, focusin, focusout, forced). 

**%W**
 The name of the entry widget. 

  In general, the **-textvariable** and **-validatecommand** options can be dangerous to mix. Any problems have been overcome so that using the **-validatecommand** will not interfere with the traditional behavior of the entry widget. Using the **-textvariable** for read-only purposes will never cause problems. The danger comes when you try set the **-textvariable** to something that the **-validatecommand** would not accept, which causes **-validate** to become *none* (the **-invalidcommand** will not be triggered). The same happens when an error occurs evaluating the **-validatecommand**. 


 Primarily, an error will occur when the **-validatecommand** or **-invalidcommand** encounters an error in its script while evaluating or **-validatecommand** does not return a valid Tcl boolean value. The **-validate** option will also set itself to **none** when you edit the entry widget from within either the **-validatecommand** or the **-invalidcommand**. Such editions will override the one that was being validated. If you wish to edit the entry widget (for example set it to {}) during validation and still have the **-validate** option set, you should include the command 



```
after idle {%W config -validate %v}
```
 in the **-validatecommand** or **-invalidcommand** (whichever one you were editing the entry widget from). It is also recommended to not set an associated **-textvariable** during validation, as that can cause the entry widget to become out of sync with the **-textvariable**. Widget command
--------------

 The **entry** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName subcommand* ?*arg arg ...*?
```
 *Subcommand* and the *arg*s determine the exact behavior of the command. ### Indices

 Many of the widget commands for entries take one or more indices as arguments. An index specifies a particular character in the entry's string, in any of the following ways: 
 *number*
 Specifies the character as a numerical index, where 0 corresponds to the first character in the string. 

**anchor**
 Indicates the anchor point for the selection, which is set with the **select from** and **select adjust** widget commands. 

**end**
 Indicates the character just after the last one in the entry's string. This is equivalent to specifying a numerical index equal to the length of the entry's string. 

**insert**
 Indicates the character adjacent to and immediately following the insertion cursor. 

**sel.first**
 Indicates the first character in the selection. It is an error to use this form if the selection is not in the entry window. 

**sel.last**
 Indicates the character just after the last one in the selection. It is an error to use this form if the selection is not in the entry window. 


**@***number*

 In this form, *number* is treated as an x-coordinate in the entry's window; the character spanning that x-coordinate is used. For example, “**@0**” indicates the left-most character in the window. 

  Abbreviations may be used for any of the forms above, e.g. “**e**” or “**sel.f**”. In general, out-of-range indices are automatically rounded to the nearest legal value. 


### Subcommands

 The following commands are possible for entry widgets: 
 
*pathName* **bbox** *index*

 Returns a list of four numbers describing the bounding box of the character given by *index*. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window. 


*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **entry** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **entry** command. 


*pathName* **delete** *first* ?*last*?
 Delete one or more elements of the entry. *First* is the index of the first character to delete, and *last* is the index of the character just after the last one to delete. If *last* is not specified it defaults to *first*+1, i.e. a single character is deleted. This command returns an empty string. 


*pathName* **get**

 Returns the entry's string. 


*pathName* **icursor** *index*

 Arrange for the insertion cursor to be displayed just before the character given by *index*. Returns an empty string. 


*pathName* **index** *index*

 Returns the numerical index corresponding to *index*. 


*pathName* **insert** *index string*

 Insert the characters of *string* just before the character indicated by *index*. Returns an empty string. 


*pathName* **scan** *option args*

 This command is used to implement scanning on entries. It has two forms, depending on *option*: 
 
*pathName* **scan mark** *x*

 Records *x* and the current view in the entry window; used in conjunction with later **scan dragto** commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. 


*pathName* **scan dragto** *x*

 This command computes the difference between its *x* argument and the *x* argument to the last **scan mark** command for the widget. It then adjusts the view left or right by 10 times the difference in x-coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the entry at high speed through the window. The return value is an empty string. 




*pathName* **selection** *option arg*

 This command is used to adjust the selection within an entry. It has several forms, depending on *option*: 
 
*pathName* **selection adjust** *index*

 Locate the end of the selection nearest to the character given by *index*, and adjust that end of the selection to be at *index* (i.e. including but not going beyond *index*). The other end of the selection is made the anchor point for future **select to** commands. If the selection is not currently in the entry, then a new selection is created to include the characters between *index* and the most recent selection anchor point, inclusive. Returns an empty string. 


*pathName* **selection clear**

 Clear the selection if it is currently in this widget. If the selection is not in this widget then the command has no effect. Returns an empty string. 


*pathName* **selection from** *index*

 Set the selection anchor point to just before the character given by *index*. Does not change the selection. Returns an empty string. 


*pathName* **selection present**

 Returns 1 if there is are characters selected in the entry, 0 if nothing is selected. 


*pathName* **selection range** *start* *end*

 Sets the selection to include the characters starting with the one indexed by *start* and ending with the one just before *end*. If *end* refers to the same character as *start* or an earlier one, then the entry's selection is cleared. 


*pathName* **selection to** *index*

 If *index* is before the anchor point, set the selection to the characters from *index* up to but not including the anchor point. If *index* is the same as the anchor point, do nothing. If *index* is after the anchor point, set the selection to the characters from the anchor point up to but not including *index*. The anchor point is determined by the most recent **select from** or **select adjust** command in this widget. If the selection is not in this widget then a new selection is created using the most recent anchor point specified for the widget. Returns an empty string. 




*pathName* **validate**

 This command is used to force an evaluation of the **-validatecommand** independent of the conditions specified by the **-validate** option. This is done by temporarily setting the **-validate** option to **all**. It returns 0 or 1. 


*pathName* **xview** *args*

 This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: 
 
*pathName* **xview**

 Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the entry's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the **-xscrollcommand** option. 


*pathName* **xview** *index*

 Adjusts the view in the window so that the character given by *index* is displayed at the left edge of the window. 


*pathName* **xview moveto** *fraction*

 Adjusts the view in the window so that the character *fraction* of the way through the text appears at the left edge of the window. *Fraction* must be a fraction between 0 and 1. 


*pathName* **xview scroll** *number what*

 This command shifts the view in the window left or right according to *number* and *what*. *Number* must be an integer. *What* must be either **units** or **pages** or an abbreviation of one of these. If *what* is **units**, the view adjusts left or right by *number* average-width characters on the display; if it is **pages** then the view adjusts by *number* screenfuls. If *number* is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. 



 Default bindings
----------------

 Tk automatically creates class bindings for entries that give them the following default behavior. In the descriptions below, “word” refers to a contiguous group of letters, digits, or “\_” characters, or any single character other than these. 
1. Clicking mouse button 1 positions the insertion cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse.
2. Double-clicking with mouse button 1 selects the word under the mouse and positions the insertion cursor at the end of the word. Dragging after a double click will stroke out a selection consisting of whole words.
3. Triple-clicking with mouse button 1 selects all of the text in the entry and positions the insertion cursor at the end of the line.
4. The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down; this will adjust the end of the selection that was nearest to the mouse cursor when button 1 was pressed. If the button is double-clicked before dragging then the selection will be adjusted in units of whole words.
5. Clicking mouse button 1 with the Control key down will position the insertion cursor in the entry without affecting the selection.
6. If any normal printing characters are typed in an entry, they are inserted at the point of the insertion cursor.
7. The view in the entry can be adjusted by dragging with mouse button 2. If mouse button 2 is clicked without moving the mouse, the selection is copied into the entry at the position of the mouse cursor.
8. If the mouse is dragged out of the entry on the left or right sides while button 1 is pressed, the entry will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window).
9. The Left and Right keys move the insertion cursor one character to the left or right; they also clear any selection in the entry and set the selection anchor. If Left or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Left and Control-Right move the insertion cursor by words, and Control-Shift-Left and Control-Shift-Right move the insertion cursor by words and also extend the selection. Control-b and Control-f behave the same as Left and Right, respectively. Meta-b and Meta-f behave the same as Control-Left and Control-Right, respectively.
10. The Home key, or Control-a, will move the insertion cursor to the beginning of the entry and clear any selection in the entry. Shift-Home moves the insertion cursor to the beginning of the entry and also extends the selection to that point.
11. The End key, or Control-e, will move the insertion cursor to the end of the entry and clear any selection in the entry. Shift-End moves the cursor to the end and extends the selection to that point.
12. The Select key and Control-Space set the selection anchor to the position of the insertion cursor. They do not affect the current selection. Shift-Select and Control-Shift-Space adjust the selection to the current position of the insertion cursor, selecting from the anchor to the insertion cursor if there was not any selection previously.
13. Control-/ selects all the text in the entry.
14. Control-\ clears any selection in the entry.
15. The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection.
16. The F20 key (labelled Cut on many Sun workstations) or Control-w copies the selection in the widget to the clipboard and deletes the selection. If there is no selection in the widget then these keys have no effect.
17. The F18 key (labelled Paste on many Sun workstations) or Control-y inserts the contents of the clipboard at the position of the insertion cursor.
18. The Delete key deletes the selection, if there is one in the entry. If there is no selection, it deletes the character to the right of the insertion cursor.
19. The BackSpace key and Control-h delete the selection, if there is one in the entry. If there is no selection, it deletes the character to the left of the insertion cursor.
20. Control-d deletes the character to the right of the insertion cursor.
21. Meta-d deletes the word to the right of the insertion cursor.
22. Control-k deletes all the characters to the right of the insertion cursor.
23. Control-t reverses the order of the two characters to the right of the insertion cursor.

  If the entry is disabled using the **-state** option, then the entry's view can still be adjusted and text in the entry can still be selected, but no insertion cursor will be displayed and no text modifications will take place except if the entry is linked to a variable using the **-textvariable** option, in which case any changes to the variable are reflected by the entry whatever the value of its **-state** option. 


 The behavior of entries can be changed by defining new bindings for individual widgets or by redefining the class bindings. 


See also
--------

 **[ttk::entry](ttk_entry.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 1998-2000 Scriptics Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/entry.htm>

fontchooser
===========

  
[NAME](fontchooser.htm#M2) fontchooser — control font selection dialog 
[SYNOPSIS](fontchooser.htm#M3) 
[DESCRIPTION](fontchooser.htm#M4)  
[**tk fontchooser** **configure** ?*-option value -option value ...*?](fontchooser.htm#M5) 
[**tk fontchooser** **show**](fontchooser.htm#M6) 
[**tk fontchooser** **hide**](fontchooser.htm#M7) 


 
[CONFIGURATION OPTIONS](fontchooser.htm#M8)  
[**-parent**](fontchooser.htm#M9) 
[**-title**](fontchooser.htm#M10) 
[**-font**](fontchooser.htm#M11) 
[**-command**](fontchooser.htm#M12) 
[**-visible**](fontchooser.htm#M13) 




 
[VIRTUAL EVENTS](fontchooser.htm#M14)  
[**<<TkFontchooserVisibility>>**](fontchooser.htm#M15) 
[**<<TkFontchooserFontChanged>>**](fontchooser.htm#M16) 

 
[NOTES](fontchooser.htm#M17) 
[EXAMPLE](fontchooser.htm#M18) 
[SEE ALSO](fontchooser.htm#M19) 
[KEYWORDS](fontchooser.htm#M20) 








 Name
----

 fontchooser — control font selection dialog Synopsis
--------

 **[tk fontchooser](tk.htm)** **configure** ?*-option value -option value ...*?  
 **[tk fontchooser](tk.htm)** **show**  
 **[tk fontchooser](tk.htm)** **hide**  
 Description
-----------

 The **[tk fontchooser](tk.htm)** command controls the Tk font selection dialog. It uses the native platform font selection dialog where available, or a dialog implemented in Tcl otherwise.  Unlike most of the other Tk dialog commands, **[tk fontchooser](tk.htm)** does not return an immediate result, as on some platforms (Mac OS X) the standard font dialog is modeless while on others (Windows) it is modal. To accommodate this difference, all user interaction with the dialog will be communicated to the caller via callbacks or virtual events. 


 The **[tk fontchooser](tk.htm)** command can have one of the following forms: 


 
**tk fontchooser** **configure** ?*-option value -option value ...*?
 Set or query one or more of the configurations options below (analogous to Tk widget configuration). 


**tk fontchooser** **show**

 Show the font selection dialog. Depending on the platform, may return immediately or only once the dialog has been withdrawn. 


**tk fontchooser** **hide**

 Hide the font selection dialog if it is visible and cause any pending **[tk fontchooser](tk.htm)** **show** command to return. 


Configuration options
---------------------

  **-parent**
 Specifies/returns the logical parent window of the font selection dialog (similar to the **-parent** option to other dialogs). The font selection dialog is hidden if it is visible when the parent window is destroyed. 

**-title**
 Specifies/returns the title of the dialog. Has no effect on platforms where the font selection dialog does not support titles. 

**-font**
 Specifies/returns the font that is currently selected in the dialog if it is visible, or that will be initially selected when the dialog is shown (if supported by the platform). Can be set to the empty string to indicate that no font should be selected. Fonts can be specified in any form given by the "FONT DESCRIPTION" section in the **[font](font.htm)** manual page. 

**-command**
 Specifies/returns the command prefix to be called when a font selection has been made by the user. The command prefix is evaluated at the global level after having the specification of the selected font appended. On platforms where the font selection dialog offers the user control of further font attributes (such as color), additional key/value pairs may be appended before evaluation. Can be set to the empty string to indicate that no callback should be invoked. Fonts are specified by a list of form [3] of the "FONT DESCRIPTION" section in the **[font](font.htm)** manual page (i.e. a list of the form *{family size style ?style ...?}*). 

**-visible**
 Read-only option that returns a boolean indicating whether the font selection dialog is currently visible. Attempting to set this option results in an error. 


Virtual events
--------------

  **<<TkFontchooserVisibility>>**
 Sent to the dialog parent whenever the visibility of the font selection dialog changes, both as a result of user action (e.g. disposing of the dialog via OK/Cancel button or close box) and of the **[tk fontchooser](tk.htm)** **show**/**hide** commands being called. Binding scripts can determine the current visibility of the dialog by querying the **-visible** configuration option. 

**<<TkFontchooserFontChanged>>**
 Sent to the dialog parent whenever the font selection dialog is visible and the selected font changes, both as a result of user action and of the **-font** configuration option being set. Binding scripts can determine the currently selected font by querying the **-font** configuration option. 


Notes
-----

 Callers should not expect a result from **[tk fontchooser](tk.htm)** **show** and may not assume that the dialog has been withdrawn or closed when the command returns. All user interaction with the dialog is communicated to the caller via the **-command** callback and the **<<TkFontchooser\*>>** virtual events. It is implementation dependent which exact user actions result in the callback being called resp. the virtual events being sent. Where an Apply or OK button is present in the dialog, that button will trigger the **-command** callback and **<<TkFontchooserFontChanged>>** virtual event. On some implementations other user actions may also have that effect; on Mac OS X for instance, the standard font selection dialog immediately reflects all user choices to the caller.  In the presence of multiple widgets intended to be influenced by the font selection dialog, care needs to be taken to correctly handle focus changes: the font selected in the dialog should always match the current font of the widget with the focus, and the **-command** callback should only act on the widget with the focus. The recommended practice is to set font dialog **-font** and **-command** configuration options in per-widget **<FocusIn>** handlers (and if necessary to unset them - i.e. set to the empty string - in corresponding **<FocusOut>** handlers). This is particularly important for implementers of library code using the font selection dialog, to avoid conflicting with application code that may also want to use the dialog. 


 Because the font selection dialog is application-global, in the presence of multiple interpreters calling **[tk fontchooser](tk.htm)**, only the **-command** callback set by the interpreter that most recently called **[tk fontchooser](tk.htm)** **configure** or **[tk fontchooser](tk.htm)** **show** will be invoked in response to user action and only the **-parent** set by that interpreter will receive **<<TkFontchooser\*>>** virtual events. 


 The font dialog implementation may only store (and return) **[font](font.htm)** **actual** data as the value of the **-font** configuration option. This can be an issue when **-font** is set to a named font, if that font is subsequently changed, the font dialog **-font** option needs to be set again to ensure its selected font matches the new value of the named font. 


Example
-------

 
```
proc fontchooserDemo {} {
    wm title . "Font Chooser Demo"
    **[tk fontchooser](tk.htm)** **configure** -parent .
    button .b -command fontchooserToggle -takefocus 0
    fontchooserVisibility .b
    bind . **<<TkFontchooserVisibility>>** \
            [list fontchooserVisibility .b]
    foreach w {.t1 .t2} {
        text $w -width 20 -height 4 -borderwidth 1 -relief solid
        bind $w <FocusIn> [list fontchooserFocus $w]
        $w insert end "Text Widget $w"
    }
    .t1 configure -font {Courier 14}
    .t2 configure -font {Times 16}
    pack .b .t1 .t2; focus .t1
}
proc fontchooserToggle {} {
    **[tk fontchooser](tk.htm)** [expr {
            [**[tk fontchooser](tk.htm)** **configure** -visible] ?
            "**hide**" : "**show**"}]
}
proc fontchooserVisibility {w} {
    $w configure -text [expr {
            [**[tk fontchooser](tk.htm)** **configure** -visible] ?
            "Hide Font Dialog" : "Show Font Dialog"}]
}
proc fontchooserFocus {w} {
    **[tk fontchooser](tk.htm)** **configure** -font [$w cget -font] \
            -command [list fontchooserFontSelection $w]
}
proc fontchooserFontSelection {w font args} {
    $w configure -font [font actual $font]
}
fontchooserDemo
```
 See also
--------

 **[font](font.htm)**, **[tk](tk.htm)** Copyright © 2008 Daniel A. Steffen <das(at)users.sourceforge.net> 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/fontchooser.htm>

ttk\_intro
==========

 Name
----

 ttk::intro — Introduction to the Tk theme engine Overview
--------

 The Tk themed widget set is based on a revised and enhanced version of TIP #48 (<http://tip.tcl.tk/48>) specified style engine. The main concepts are described below. The basic idea is to separate, to the extent possible, the code implementing a widget's behavior from the code implementing its appearance. Widget class bindings are primarily responsible for maintaining the widget state and invoking callbacks; all aspects of the widget's appearance are controlled by the style of the widget (i.e. the style of the elements of the widget). Themes
------

 A *theme* is a collection of elements and styles that determine the look and feel of the widget set. Themes can be used to: 
* isolate platform differences (X11 vs. classic Windows vs. XP vs. Aqua ...)
* adapt to display limitations (low-color, grayscale, monochrome, tiny screens)
* accessibility (high contrast, large type)
* application suite branding
* blend in with the rest of the desktop (Gnome, KDE, Java)
* and, of course: eye candy.

 Elements
--------

 An *element* displays an individual part of a widget. For example, a vertical scrollbar widget contains **uparrow**, **downarrow**, **trough** and **slider** elements.  Element names use a recursive dotted notation. For example, **uparrow** identifies a generic arrow element, and **Scrollbar.uparrow** and **Combobox.uparrow** identify widget-specific elements. When looking for an element, the style engine looks for the specific name first, and if an element of that name is not found it looks for generic elements by stripping off successive leading components of the element name. 


 Like widgets, elements have *options* which specify what to display and how to display it. For example, the **text** element (which displays a text string) has **-text**, **-font**, **-foreground**, **-background**, **-underline**, and **-width** options. The value of an element option is taken from: 


* an option of the same name and type in the widget containing the element;
* a dynamic setting specified by **[style map](ttk_style.htm)** and the current state;
* the default setting specified by **style configure**; or
* the element's built-in default value for the option.

 Layouts
-------

 A *layout* specifies which elements make up a widget and how they are arranged. The layout engine uses a simplified version of the **[pack](pack.htm)** algorithm: starting with an initial cavity equal to the size of the widget, elements are allocated a parcel within the cavity along the side specified by the **-side** option, and placed within the parcel according to the **-sticky** option. For example, the layout for a horizontal scrollbar is: 

```
ttk::**style layout** Horizontal.TScrollbar {
    Scrollbar.trough -children {
	Scrollbar.leftarrow -side left -sticky w
	Scrollbar.rightarrow -side right -sticky e
	Scrollbar.thumb -side left -expand true -sticky ew
    }
}
```
  By default, the layout for a widget is the same as its class name. Some widgets may override this (for example, the **[ttk::scrollbar](ttk_scrollbar.htm)** widget chooses different layouts based on the **-orient** option). 


States
------

 In standard Tk, many widgets have a **-state** option which (in most cases) is either **normal** or **disabled**. Some widgets support additional states, such as the **[entry](entry.htm)** widget which has a **readonly** state and the various flavors of buttons which have **active** state.  The themed Tk widgets generalizes this idea: every widget has a bitmap of independent state flags. Widget state flags include **active**, **disabled**, **pressed**, **focus**, etc., (see *ttk::widget(n)* for the full list of state flags). 


 Instead of a **-state** option, every widget now has a **state** widget command which is used to set or query the state. A *state specification* is a list of symbolic state names indicating which bits are set, each optionally prefixed with an exclamation point indicating that the bit is cleared instead. 


 For example, the class bindings for the **[ttk::button](ttk_button.htm)** widget are: 



```
bind TButton <Enter>		{ %W state active }
bind TButton <Leave>		{ %W state !active }
bind TButton <ButtonPress-1>	{ %W state pressed }
bind TButton <Button1-Leave>	{ %W state !pressed }
bind TButton <Button1-Enter>	{ %W state pressed }
bind TButton <ButtonRelease-1>	\
    { %W instate {pressed} { %W state !pressed ; %W invoke } }
```
  This specifies that the widget becomes **active** when the pointer enters the widget, and inactive when it leaves. Similarly it becomes **pressed** when the mouse button is pressed, and **!pressed** on the ButtonRelease event. In addition, the button unpresses if pointer is dragged outside the widget while Button-1 is held down, and represses if it's dragged back in. Finally, when the mouse button is released, the widget's **-command** is invoked, but only if the button is currently in the **pressed** state. (The actual bindings are a little more complicated than the above, but not by much). 


Styles
------

 Each widget is associated with a *style*, which specifies values for element options. Style names use a recursive dotted notation like layouts and elements; by default, widgets use the class name to look up a style in the current theme. For example: 

```
ttk::**style configure** TButton \
	-background #d9d9d9 \
	-foreground black \
	-relief raised \
	;
```
  Many elements are displayed differently depending on the widget state. For example, buttons have a different background when they are active, a different foreground when disabled, and a different relief when pressed. The **[style map](ttk_style.htm)** command specifies dynamic option settings for a particular style: 



```
ttk::**[style map](ttk_style.htm)** TButton \
	-background [list disabled #d9d9d9  active #ececec] \
	-foreground [list disabled #a3a3a3] \
	-relief [list {pressed !disabled} sunken] \
	;
```
 See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[ttk::style](ttk_style.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_intro.htm>

frame
=====

  
[NAME](frame.htm#M2) frame — Create and manipulate 'frame' simple container widgets 
[SYNOPSIS](frame.htm#M3) 
[STANDARD OPTIONS](frame.htm#M4)  
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-padx, padX, Pad](options.htm#M-padx) 
[-pady, padY, Pad](options.htm#M-pady) 
[-relief, relief, Relief](options.htm#M-relief) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 








 
[WIDGET-SPECIFIC OPTIONS](frame.htm#M5)  
[-background, background, Background](frame.htm#M6) 
[-class, class, Class](frame.htm#M7) 
[-colormap, colormap, Colormap](frame.htm#M8) 
[-container, container, Container](frame.htm#M9) 
[-height, height, Height](frame.htm#M10) 
[-visual, visual, Visual](frame.htm#M11) 
[-width, width, Width](frame.htm#M12) 






 
[DESCRIPTION](frame.htm#M13) 
[WIDGET COMMAND](frame.htm#M14)  
[*pathName* **cget** *option*](frame.htm#M15) 
[*pathName* **configure** ?*option*? *?value option value ...*?](frame.htm#M16) 

 
[BINDINGS](frame.htm#M17) 
[SEE ALSO](frame.htm#M18) 
[KEYWORDS](frame.htm#M19) 








 Name
----

 frame — Create and manipulate 'frame' simple container widgets Synopsis
--------

 **frame** *pathName* ?*options*?  
 Standard options
----------------

  
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-padx, padX, Pad](options.htm#M-padx)** 
**[-pady, padY, Pad](options.htm#M-pady)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 








 Widget-specific options
-----------------------

  Command-Line Name: **-background** Database Name: **background** Database Class: **Background** 


This option is the same as the standard **-background** option except that its value may also be specified as an empty string. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border. 

Command-Line Name: **-class** Database Name: **class** Database Class: **Class** 


Specifies a class for the window. This class will be used when querying the option database for the window's other options, and it will also be used later for other purposes such as bindings. The **-class** option may not be changed with the **configure** widget command. 

Command-Line Name: **-colormap** Database Name: **colormap** Database Class: **Colormap** 


Specifies a colormap to use for the window. The value may be either **new**, in which case a new colormap is created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as *pathName*), in which case the new window will use the colormap from the specified window. If the **-colormap** option is not specified, the new window uses the same colormap as its parent. This option may not be changed with the **configure** widget command. 

Command-Line Name: **-container** Database Name: **container** Database Class: **Container** 


The value must be a boolean. If true, it means that this window will be used as a container in which some other application will be embedded (for example, a Tk toplevel can be embedded using the **-use** option). The window will support the appropriate window manager protocols for things like geometry requests. The window should not have any children of its own in this application. This option may not be changed with the **configure** widget command. Note that **-borderwidth**, **-padx** and **-pady** are ignored when configured as a container since a container has no border. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies the desired height for the window in any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. If this option is less than or equal to zero then the window will not request any size at all. Note that this sets the total height of the frame, any **-borderwidth** or similar is not added. Normally **-height** should not be used if a propagating geometry manager, such as **[grid](grid.htm)** or **[pack](pack.htm)**, is used within the frame since the geometry manager will override the height of the frame. 

Command-Line Name: **-visual** Database Name: **visual** Database Class: **Visual** 


Specifies visual information for the new window in any of the forms accepted by **[Tk\_GetVisual](https://www.tcl.tk/man/tcl/TkLib/GetVisual.htm)**. If this option is not specified, the new window will use the same visual as its parent. The **-visual** option may not be modified with the **configure** widget command. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies the desired width for the window in any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. If this option is less than or equal to zero then the window will not request any size at all. Note that this sets the total width of the frame, any **-borderwidth** or similar is not added. Normally **-width** should not be used if a propagating geometry manager, such as **[grid](grid.htm)** or **[pack](pack.htm)**, is used within the frame since the geometry manager will override the width of the frame. 
 Description
-----------

 The **frame** command creates a new window (given by the *pathName* argument) and makes it into a frame widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the frame such as its background color and relief. The **frame** command returns the path name of the new window.  A frame is a simple widget. Its primary purpose is to act as a spacer or container for complex window layouts. The only features of a frame are its background color and an optional 3-D border to make the frame appear raised or sunken. 


Widget command
--------------

 The **frame** command creates a new Tcl command whose name is the same as the path name of the frame's window. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *PathName* is the name of the command, which is the same as the frame widget's path name. *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for frame widgets: 
 
*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **frame** command. 


*pathName* **configure** ?*option*? *?value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **frame** command. 

 Bindings
--------

 When a new frame is created, it has no default event bindings: frames are not intended to be interactive. See also
--------

 **[labelframe](labelframe.htm)**, **[toplevel](toplevel.htm)**, **[ttk::frame](ttk_frame.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/frame.htm>

event
=====

  
[NAME](event.htm#M2) event — Miscellaneous event facilities: define virtual events and generate events 
[SYNOPSIS](event.htm#M3) 
[DESCRIPTION](event.htm#M4)  
[**event add <<***virtual***>>** *sequence* ?*sequence ...*?](event.htm#M5) 
[**event delete <<***virtual***>>** ?*sequence* *sequence ...*?](event.htm#M6) 
[**event generate** *window event* ?*option value option value ...*?](event.htm#M7) 
[**event info** ?**<<***virtual***>>**?](event.htm#M8) 



 
[EVENT FIELDS](event.htm#M9)  
[**-above** *window*](event.htm#M10) 
[**-borderwidth** *size*](event.htm#M11) 
[**-button** *number*](event.htm#M12) 
[**-count** *number*](event.htm#M13) 
[**-data** *string*](event.htm#M14) 
[**-delta** *number*](event.htm#M15) 
[**-detail** *detail*](event.htm#M16) 
[**-focus** *boolean*](event.htm#M17) 
[**-height** *size*](event.htm#M18) 
[**-keycode** *number*](event.htm#M19) 
[**-keysym** *name*](event.htm#M20) 
[**-mode** *notify*](event.htm#M21) 
[**-override** *boolean*](event.htm#M22) 
[**-place** *where*](event.htm#M23) 
[**-root** *window*](event.htm#M24) 
[**-rootx** *coord*](event.htm#M25) 
[**-rooty** *coord*](event.htm#M26) 
[**-sendevent** *boolean*](event.htm#M27) 
[**-serial** *number*](event.htm#M28) 
[**-state** *state*](event.htm#M29) 
[**-subwindow** *window*](event.htm#M30) 
[**-time** *integer*](event.htm#M31) 
[**-warp** *boolean*](event.htm#M32) 
[**-width** *size*](event.htm#M33) 
[**-when** *when*](event.htm#M34)  
[**now**](event.htm#M35) 
[**tail**](event.htm#M36) 
[**head**](event.htm#M37) 
[**mark**](event.htm#M38) 



 
[**-x** *coord*](event.htm#M39) 
[**-y** *coord*](event.htm#M40) 


























 
[PREDEFINED VIRTUAL EVENTS](event.htm#M41)  
[**<<AltUnderlined>>**](event.htm#M42) 
[**<<Invoke>>**](event.htm#M43) 
[**<<ListboxSelect>>**](event.htm#M44) 
[**<<MenuSelect>>**](event.htm#M45) 
[**<<Modified>>**](event.htm#M46) 
[**<<Selection>>**](event.htm#M47) 
[**<<ThemeChanged>>**](event.htm#M48) 
[**<<TraverseIn>>**](event.htm#M49) 
[**<<TraverseOut>>**](event.htm#M50) 
[**<<UndoStack>>**](event.htm#M51) 
[**<<WidgetViewSync>>**](event.htm#M52) 










  
[**<<Clear>>**](event.htm#M53) 
[**<<Copy>>**](event.htm#M54) 
[**<<Cut>>**](event.htm#M55) 
[**<<LineEnd>>**](event.htm#M56) 
[**<<LineStart>>**](event.htm#M57) 
[**<<NextChar>>**](event.htm#M58) 
[**<<NextLine>>**](event.htm#M59) 
[**<<NextPara>>**](event.htm#M60) 
[**<<NextWord>>**](event.htm#M61) 
[**<<Paste>>**](event.htm#M62) 
[**<<PasteSelection>>**](event.htm#M63) 
[**<<PrevChar>>**](event.htm#M64) 
[**<<PrevLine>>**](event.htm#M65) 
[**<<PrevPara>>**](event.htm#M66) 
[**<<PrevWindow>>**](event.htm#M67) 
[**<<PrevWord>>**](event.htm#M68) 
[**<<Redo>>**](event.htm#M69) 
[**<<SelectAll>>**](event.htm#M70) 
[**<<SelectLineEnd>>**](event.htm#M71) 
[**<<SelectLineStart>>**](event.htm#M72) 
[**<<SelectNextChar>>**](event.htm#M73) 
[**<<SelectNextLine>>**](event.htm#M74) 
[**<<SelectNextPara>>**](event.htm#M75) 
[**<<SelectNextWord>>**](event.htm#M76) 
[**<<SelectNone>>**](event.htm#M77) 
[**<<SelectPrevChar>>**](event.htm#M78) 
[**<<SelectPrevLine>>**](event.htm#M79) 
[**<<SelectPrevPara>>**](event.htm#M80) 
[**<<SelectPrevWord>>**](event.htm#M81) 
[**<<ToggleSelection>>**](event.htm#M82) 
[**<<Undo>>**](event.htm#M83) 






























 
[EXAMPLES](event.htm#M84) 
[MAPPING KEYS TO VIRTUAL EVENTS](event.htm#M85) 
[MOVING THE MOUSE POINTER](event.htm#M86) 
[SEE ALSO](event.htm#M87) 
[KEYWORDS](event.htm#M88) 









 Name
----

 event — Miscellaneous event facilities: define virtual events and generate events Synopsis
--------

 **event** *option* ?*arg arg ...*?  
 Description
-----------

 The **event** command provides several facilities for dealing with window system events, such as defining virtual events and synthesizing events. The command has several different forms, determined by the first argument. The following forms are currently supported: 
 
**event add <<***virtual***>>** *sequence* ?*sequence ...*?
 Associates the virtual event *virtual* with the physical event sequence(s) given by the *sequence* arguments, so that the virtual event will trigger whenever any one of the *sequence*s occurs. *Virtual* may be any string value and *sequence* may have any of the values allowed for the *sequence* argument to the **[bind](bind.htm)** command. If *virtual* is already defined, the new physical event sequences add to the existing sequences for the event. 


**event delete <<***virtual***>>** ?*sequence* *sequence ...*?
 Deletes each of the *sequence*s from those associated with the virtual event given by *virtual*. *Virtual* may be any string value and *sequence* may have any of the values allowed for the *sequence* argument to the **[bind](bind.htm)** command. Any *sequence*s not currently associated with *virtual* are ignored. If no *sequence* argument is provided, all physical event sequences are removed for *virtual*, so that the virtual event will not trigger anymore. 


**event generate** *window event* ?*option value option value ...*?
 Generates a window event and arranges for it to be processed just as if it had come from the window system. *Window* gives the path name of the window for which the event will be generated; it may also be an identifier (such as returned by **[winfo id](winfo.htm)**) as long as it is for a window in the current application. *Event* provides a basic description of the event, such as **<Shift-Button-2>** or **<<Paste>>**. If *Window* is empty the whole screen is meant, and coordinates are relative to the screen. *Event* may have any of the forms allowed for the *sequence* argument of the **[bind](bind.htm)** command except that it must consist of a single event pattern, not a sequence. *Option-value* pairs may be used to specify additional attributes of the event, such as the x and y mouse position; see **[EVENT FIELDS](#M9)** below. If the **-when** option is not specified, the event is processed immediately: all of the handlers for the event will complete before the **event generate** command returns. If the **-when** option is specified then it determines when the event is processed. Certain events, such as key events, require that the window has focus to receive the event properly. 


**event info** ?**<<***virtual***>>**?
 Returns information about virtual events. If the **<<***virtual***>>** argument is omitted, the return value is a list of all the virtual events that are currently defined. If **<<***virtual***>>** is specified then the return value is a list whose elements are the physical event sequences currently defined for the given virtual event; if the virtual event is not defined then an empty string is returned.  Note that virtual events that are not bound to physical event sequences are *not* returned by **event info**. 



 Event fields
------------

 The following options are supported for the **event generate** command. These correspond to the “%” expansions allowed in binding scripts for the **[bind](bind.htm)** command. 
 
**-above** *window*

 *Window* specifies the *above* field for the event, either as a window path name or as an integer window id. Valid for **Configure** events. Corresponds to the **%a** substitution for binding scripts. 


**-borderwidth** *size*

 *Size* must be a screen distance; it specifies the *border\_width* field for the event. Valid for **Configure** events. Corresponds to the **%B** substitution for binding scripts. 


**-button** *number*

 *Number* must be an integer; it specifies the *detail* field for a **ButtonPress** or **ButtonRelease** event, overriding any button number provided in the base *event* argument. Corresponds to the **%b** substitution for binding scripts. 


**-count** *number*

 *Number* must be an integer; it specifies the *count* field for the event. Valid for **Expose** events. Corresponds to the **%c** substitution for binding scripts. 


**-data** *string*

 *String* may be any value; it specifies the *user\_data* field for the event. Only valid for virtual events. Corresponds to the **%d** substitution for virtual events in binding scripts. 


**-delta** *number*

 *Number* must be an integer; it specifies the *delta* field for the **MouseWheel** event. The *delta* refers to the direction and magnitude the mouse wheel was rotated. Note the value is not a screen distance but are units of motion in the mouse wheel. Typically these values are multiples of 120. For example, 120 should scroll the text widget up 4 lines and -240 would scroll the text widget down 8 lines. Of course, other widgets may define different behaviors for mouse wheel motion. This field corresponds to the **%D** substitution for binding scripts. 


**-detail** *detail*

 *Detail* specifies the *detail* field for the event and must be one of the following: 

|  |  |
| --- | --- |
| **NotifyAncestor** | **NotifyNonlinearVirtual** |
| **NotifyDetailNone** | **NotifyPointer** |
| **NotifyInferior** | **NotifyPointerRoot** |
| **NotifyNonlinear** | **NotifyVirtual** |

 Valid for **Enter**, **Leave**, **FocusIn** and **FocusOut** events. Corresponds to the **%d** substitution for binding scripts. 


**-focus** *boolean*

 *Boolean* must be a boolean value; it specifies the *focus* field for the event. Valid for **Enter** and **Leave** events. Corresponds to the **%f** substitution for binding scripts. 


**-height** *size*

 *Size* must be a screen distance; it specifies the *height* field for the event. Valid for **Configure** events. Corresponds to the **%h** substitution for binding scripts. 


**-keycode** *number*

 *Number* must be an integer; it specifies the *keycode* field for the event. Valid for **KeyPress** and **KeyRelease** events. Corresponds to the **%k** substitution for binding scripts. 


**-keysym** *name*

 *Name* must be the name of a valid keysym, such as **g**, **space**, or **Return**; its corresponding keycode value is used as the *keycode* field for event, overriding any detail specified in the base *event* argument. Valid for **KeyPress** and **KeyRelease** events. Corresponds to the **%K** substitution for binding scripts. 


**-mode** *notify*

 *Notify* specifies the *mode* field for the event and must be one of **NotifyNormal**, **NotifyGrab**, **NotifyUngrab**, or **NotifyWhileGrabbed**. Valid for **Enter**, **Leave**, **FocusIn**, and **FocusOut** events. Corresponds to the **%m** substitution for binding scripts. 


**-override** *boolean*

 *Boolean* must be a boolean value; it specifies the *override\_redirect* field for the event. Valid for **Map**, **Reparent**, and **Configure** events. Corresponds to the **%o** substitution for binding scripts. 


**-place** *where*

 *Where* specifies the *place* field for the event; it must be either **PlaceOnTop** or **PlaceOnBottom**. Valid for **Circulate** events. Corresponds to the **%p** substitution for binding scripts. 


**-root** *window*

 *Window* must be either a window path name or an integer window identifier; it specifies the *root* field for the event. Valid for **KeyPress**, **KeyRelease**, **ButtonPress**, **ButtonRelease**, **Enter**, **Leave**, and **Motion** events. Corresponds to the **%R** substitution for binding scripts. 


**-rootx** *coord*

 *Coord* must be a screen distance; it specifies the *x\_root* field for the event. Valid for **KeyPress**, **KeyRelease**, **ButtonPress**, **ButtonRelease**, **Enter**, **Leave**, and **Motion** events. Corresponds to the **%X** substitution for binding scripts. 


**-rooty** *coord*

 *Coord* must be a screen distance; it specifies the *y\_root* field for the event. Valid for **KeyPress**, **KeyRelease**, **ButtonPress**, **ButtonRelease**, **Enter**, **Leave**, and **Motion** events. Corresponds to the **%Y** substitution for binding scripts. 


**-sendevent** *boolean*

 *Boolean* must be a boolean value; it specifies the *send\_event* field for the event. Valid for all events. Corresponds to the **%E** substitution for binding scripts. 


**-serial** *number*

 *Number* must be an integer; it specifies the *serial* field for the event. Valid for all events. Corresponds to the **%#** substitution for binding scripts. 


**-state** *state*

 *State* specifies the *state* field for the event. For **KeyPress**, **KeyRelease**, **ButtonPress**, **ButtonRelease**, **Enter**, **Leave**, and **Motion** events it must be an integer value. For **Visibility** events it must be one of **VisibilityUnobscured**, **VisibilityPartiallyObscured**, or **VisibilityFullyObscured**. This option overrides any modifiers such as **Meta** or **Control** specified in the base *event*. Corresponds to the **%s** substitution for binding scripts. 


**-subwindow** *window*

 *Window* specifies the *subwindow* field for the event, either as a path name for a Tk widget or as an integer window identifier. Valid for **KeyPress**, **KeyRelease**, **ButtonPress**, **ButtonRelease**, **Enter**, **Leave**, and **Motion** events. Similar to **%S** substitution for binding scripts. 


**-time** *integer*

 *Integer* must be an integer value; it specifies the *time* field for the event. Valid for **KeyPress**, **KeyRelease**, **ButtonPress**, **ButtonRelease**, **Enter**, **Leave**, **Motion**, and **Property** events. Corresponds to the **%t** substitution for binding scripts. 


**-warp** *boolean*

 *boolean* must be a boolean value; it specifies whether the screen pointer should be warped as well. Valid for **KeyPress**, **KeyRelease**, **ButtonPress**, **ButtonRelease**, and **Motion** events. The pointer will only warp to a window if it is mapped. 


**-width** *size*

 *Size* must be a screen distance; it specifies the *width* field for the event. Valid for **Configure** events. Corresponds to the **%w** substitution for binding scripts. 


**-when** *when*

 *When* determines when the event will be processed; it must have one of the following values: 
 **now**
 Process the event immediately, before the command returns. This also happens if the **-when** option is omitted. 

**tail**
 Place the event on Tcl's event queue behind any events already queued for this application. 

**head**
 Place the event at the front of Tcl's event queue, so that it will be handled before any other events already queued. 

**mark**
 Place the event at the front of Tcl's event queue but behind any other events already queued with **-when mark**. This option is useful when generating a series of events that should be processed in order but at the front of the queue. 




**-x** *coord*

 *Coord* must be a screen distance; it specifies the *x* field for the event. Valid for **KeyPress**, **KeyRelease**, **ButtonPress**, **ButtonRelease**, **Motion**, **Enter**, **Leave**, **Expose**, **Configure**, **Gravity**, and **Reparent** events. Corresponds to the **%x** substitution for binding scripts. If *Window* is empty the coordinate is relative to the screen, and this option corresponds to the **%X** substitution for binding scripts. 


**-y** *coord*

 *Coord* must be a screen distance; it specifies the *y* field for the event. Valid for **KeyPress**, **KeyRelease**, **ButtonPress**, **ButtonRelease**, **Motion**, **Enter**, **Leave**, **Expose**, **Configure**, **Gravity**, and **Reparent** events. Corresponds to the **%y** substitution for binding scripts. If *Window* is empty the coordinate is relative to the screen, and this option corresponds to the **%Y** substitution for binding scripts. 

  Any options that are not specified when generating an event are filled with the value 0, except for *serial*, which is filled with the next X event serial number. 


Predefined virtual events
-------------------------

 Tk defines the following virtual events for the purposes of notification: 
 **<<AltUnderlined>>**
 This is sent to widget to notify it that the letter it has underlined (as an accelerator indicator) with the **-underline** option has been pressed in combination with the Alt key. The usual response to this is to either focus into the widget (or some related widget) or to invoke the widget. 

**<<Invoke>>**
 This can be sent to some widgets (e.g. button, listbox, menu) as an alternative to <space>. 

**<<ListboxSelect>>**
 This is sent to a listbox when the set of selected item(s) in the listbox is updated. 

**<<MenuSelect>>**
 This is sent to a menu when the currently selected item in the menu changes. It is intended for use with context-sensitive help systems. 

**<<Modified>>**
 This is sent to a text widget when the contents of the widget are changed. 

**<<Selection>>**
 This is sent to a text widget when the selection in the widget is changed. 

**<<ThemeChanged>>**
 This is sent to a text widget when the ttk (Tile) theme changed. 

**<<TraverseIn>>**
 This is sent to a widget when the focus enters the widget because of a user-driven “tab to widget” action. 

**<<TraverseOut>>**
 This is sent to a widget when the focus leaves the widget because of a user-driven “tab to widget” action. 

**<<UndoStack>>**
 This is sent to a text widget when its undo stack or redo stack becomes empty or unempty. 

**<<WidgetViewSync>>**
 This is sent to a text widget when its internal data become obsolete, and again when these internal data are back in sync with the widget view. The detail field (%d substitution) is either true (when the widget is in sync) or false (when it is not). 

  Tk defines the following virtual events for the purposes of unifying bindings across multiple platforms. Users expect them to behave in the following way: 


 **<<Clear>>**
 Delete the currently selected widget contents. 

**<<Copy>>**
 Copy the currently selected widget contents to the clipboard. 

**<<Cut>>**
 Move the currently selected widget contents to the clipboard. 

**<<LineEnd>>**
 Move to the end of the line in the current widget while deselecting any selected contents. 

**<<LineStart>>**
 Move to the start of the line in the current widget while deselecting any selected contents. 

**<<NextChar>>**
 Move to the next item (i.e., visible character) in the current widget while deselecting any selected contents. 

**<<NextLine>>**
 Move to the next line in the current widget while deselecting any selected contents. 

**<<NextPara>>**
 Move to the next paragraph in the current widget while deselecting any selected contents. 

**<<NextWord>>**
 Move to the next group of items (i.e., visible word) in the current widget while deselecting any selected contents. 

**<<Paste>>**
 Replace the currently selected widget contents with the contents of the clipboard. 

**<<PasteSelection>>**
 Insert the contents of the selection at the mouse location. (This event has meaningful **%x** and **%y** substitutions). 

**<<PrevChar>>**
 Move to the previous item (i.e., visible character) in the current widget while deselecting any selected contents. 

**<<PrevLine>>**
 Move to the previous line in the current widget while deselecting any selected contents. 

**<<PrevPara>>**
 Move to the previous paragraph in the current widget while deselecting any selected contents. 

**<<PrevWindow>>**
 Traverse to the previous window. 

**<<PrevWord>>**
 Move to the previous group of items (i.e., visible word) in the current widget while deselecting any selected contents. 

**<<Redo>>**
 Redo one undone action. 

**<<SelectAll>>**
 Set the range of selected contents to the complete widget. 

**<<SelectLineEnd>>**
 Move to the end of the line in the current widget while extending the range of selected contents. 

**<<SelectLineStart>>**
 Move to the start of the line in the current widget while extending the range of selected contents. 

**<<SelectNextChar>>**
 Move to the next item (i.e., visible character) in the current widget while extending the range of selected contents. 

**<<SelectNextLine>>**
 Move to the next line in the current widget while extending the range of selected contents. 

**<<SelectNextPara>>**
 Move to the next paragraph in the current widget while extending the range of selected contents. 

**<<SelectNextWord>>**
 Move to the next group of items (i.e., visible word) in the current widget while extending the range of selected contents. 

**<<SelectNone>>**
 Reset the range of selected contents to be empty. 

**<<SelectPrevChar>>**
 Move to the previous item (i.e., visible character) in the current widget while extending the range of selected contents. 

**<<SelectPrevLine>>**
 Move to the previous line in the current widget while extending the range of selected contents. 

**<<SelectPrevPara>>**
 Move to the previous paragraph in the current widget while extending the range of selected contents. 

**<<SelectPrevWord>>**
 Move to the previous group of items (i.e., visible word) in the current widget while extending the range of selected contents. 

**<<ToggleSelection>>**
 Toggle the selection. 

**<<Undo>>**
 Undo the last action. 

 Examples
--------

 ### Mapping keys to virtual events

 In order for a virtual event binding to trigger, two things must happen. First, the virtual event must be defined with the **event add** command. Second, a binding must be created for the virtual event with the **[bind](bind.htm)** command. Consider the following virtual event definitions: 

```
**event add** <<Paste>> <Control-y>
**event add** <<Paste>> <Button-2>
**event add** <<Save>> <Control-X><Control-S>
**event add** <<Save>> <Shift-F12>
if {[tk windowingsystem] eq "aqua"} {
    **event add** <<Save>> <Command-s>
}
```
  In the **[bind](bind.htm)** command, a virtual event can be bound like any other builtin event type as follows: 



```
bind Entry <<Paste>> {%W insert [selection get]}
```
  The double angle brackets are used to specify that a virtual event is being bound. If the user types Control-y or presses button 2, or if a **<<Paste>>** virtual event is synthesized with **event generate**, then the **<<Paste>>** binding will be invoked. 


 If a virtual binding has the exact same sequence as a separate physical binding, then the physical binding will take precedence. Consider the following example: 



```
**event add** <<Paste>> <Control-y> <Meta-Control-y>
bind Entry <Control-y> {puts Control-y}
bind Entry <<Paste>> {puts Paste}
```
  When the user types Control-y the **<Control-y>** binding will be invoked, because a physical event is considered more specific than a virtual event, all other things being equal. However, when the user types Meta-Control-y the **<<Paste>>** binding will be invoked, because the **Meta** modifier in the physical pattern associated with the virtual binding is more specific than the **<Control-y**> sequence for the physical event. 


 Bindings on a virtual event may be created before the virtual event exists. Indeed, the virtual event never actually needs to be defined, for instance, on platforms where the specific virtual event would be meaningless or ungeneratable. 


 When a definition of a virtual event changes at run time, all windows will respond immediately to the new definition. Starting from the preceding example, if the following code is executed: 



```
bind Entry <Control-y> {}
**event add** <<Paste>> <Key-F6>
```
  the behavior will change such in two ways. First, the shadowed **<<Paste>>** binding will emerge. Typing Control-y will no longer invoke the **<Control-y>** binding, but instead invoke the virtual event **<<Paste>>**. Second, pressing the F6 key will now also invoke the **<<Paste>>** binding. 


### Moving the mouse pointer

 Sometimes it is useful to be able to really move the mouse pointer. For example, if you have some software that is capable of demonstrating directly to the user how to use the program. To do this, you need to “warp” the mouse around by using **event generate**, like this: 

```
for {set xy 0} {$xy < 200} {incr xy} {
    **event generate** . <Motion> -x $xy -y $xy -warp 1
    update
    after 50
}
```
  Note that it is usually considered bad style to move the mouse pointer for the user because it removes control from them. Therefore this technique should be used with caution. Also note that it is not guaranteed to function on all platforms. 


See also
--------

 **[bind](bind.htm)** Copyright © 1996 Sun Microsystems, Inc.  
 Copyright © 1998-2000 Ajuba Solutions. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/event.htm>

photo
=====

  
[NAME](photo.htm#M2) photo — Full-color images 
[SYNOPSIS](photo.htm#M3) 
[DESCRIPTION](photo.htm#M4) 
[CREATING PHOTOS](photo.htm#M5)  
[**-data** *string*](photo.htm#M6) 
[**-format** *format-name*](photo.htm#M7) 
[**-file** *name*](photo.htm#M8) 
[**-gamma** *value*](photo.htm#M9) 
[**-height** *number*](photo.htm#M10) 
[**-palette** *palette-spec*](photo.htm#M11) 
[**-width** *number*](photo.htm#M12) 






 
[IMAGE COMMAND](photo.htm#M13)  
[*imageName* **blank**](photo.htm#M14) 
[*imageName* **cget** *option*](photo.htm#M15) 
[*imageName* **configure** ?*option*? ?*value option value ...*?](photo.htm#M16) 
[*imageName* **copy** *sourceImage* ?*option value(s) ...*?](photo.htm#M17)  
[**-from** *x1 y1 x2 y2*](photo.htm#M18) 
[**-to** *x1 y1 x2 y2*](photo.htm#M19) 
[**-shrink**](photo.htm#M20) 
[**-zoom** *x y*](photo.htm#M21) 
[**-subsample** *x y*](photo.htm#M22) 
[**-compositingrule** *rule*](photo.htm#M23) 





 
[*imageName* **data** ?*option value(s) ...*?](photo.htm#M24)  
[**-background** *color*](photo.htm#M25) 
[**-format** *format-name*](photo.htm#M26) 
[**-from** *x1 y1 x2 y2*](photo.htm#M27) 
[**-grayscale**](photo.htm#M28) 



 
[*imageName* **get** *x y*](photo.htm#M29) 
[*imageName* **put** *data* ?*option value(s) ...*?](photo.htm#M30)  
[**-format** *format-name*](photo.htm#M31) 
[**-to** *x1 y1* ?*x2 y2*?](photo.htm#M32) 

 
[*imageName* **read** *filename* ?*option value(s) ...*?](photo.htm#M33)  
[**-format** *format-name*](photo.htm#M34) 
[**-from** *x1 y1 x2 y2*](photo.htm#M35) 
[**-shrink**](photo.htm#M36) 
[**-to** *x y*](photo.htm#M37) 



 
[*imageName* **redither**](photo.htm#M38) 
[*imageName* **transparency** *subcommand* ?*arg arg ...*?](photo.htm#M39)  
[*imageName* **transparency get** *x y*](photo.htm#M40) 
[*imageName* **transparency set** *x y boolean*](photo.htm#M41) 

 
[*imageName* **write** *filename* ?*option value(s) ...*?](photo.htm#M42)  
[**-background** *color*](photo.htm#M43) 
[**-format** *format-name*](photo.htm#M44) 
[**-from** *x1 y1 x2 y2*](photo.htm#M45) 
[**-grayscale**](photo.htm#M46) 



 










 
[IMAGE FORMATS](photo.htm#M47) 
[FORMAT SUBOPTIONS](photo.htm#M48)  
[**gif -index** *indexValue*](photo.htm#M49) 
[**png -alpha** *alphaValue*](photo.htm#M50) 

 
[COLOR ALLOCATION](photo.htm#M51) 
[CREDITS](photo.htm#M52) 
[EXAMPLE](photo.htm#M53) 
[SEE ALSO](photo.htm#M54) 
[KEYWORDS](photo.htm#M55) 











 Name
----

 photo — Full-color images Synopsis
--------

 **image create photo** ?*name*? ?*options*?  
   
 *imageName* **blank**  
 *imageName* **cget** *option*  
 *imageName* **configure** ?*option*? ?*value option value ...*?  
 *imageName* **copy** *sourceImage* ?*option value(s) ...*?  
 *imageName* **data** ?*option value(s) ...*?  
 *imageName* **get** *x y*  
 *imageName* **put** *data* ?*option value(s) ...*?  
 *imageName* **read** *filename* ?*option value(s) ...*?  
 *imageName* **redither**  
 *imageName* **transparency** *subcommand* ?*arg arg ...*?  
 *imageName* **write** *filename* ?*option value(s) ...*?  
 Description
-----------

 A photo is an image whose pixels can display any color or be transparent. A photo image is stored internally in full color (32 bits per pixel), and is displayed using dithering if necessary. Image data for a photo image can be obtained from a file or a string, or it can be supplied from C code through a procedural interface. At present, only PNG, GIF and PPM/PGM formats are supported, but an interface exists to allow additional image file formats to be added easily. A photo image is transparent in regions where no image data has been supplied or where it has been set transparent by the **transparency set** subcommand. Creating photos
---------------

 Like all images, photos are created using the **[image create](image.htm)** command. Photos support the following *options*: 
 
**-data** *string*

 Specifies the contents of the image as a string. The string should contain binary data or, for some formats, base64-encoded data (this is currently guaranteed to be supported for PNG and GIF images). The format of the string must be one of those for which there is an image file format handler that will accept string data. If both the **-data** and **-file** options are specified, the **-file** option takes precedence. 


**-format** *format-name*

 Specifies the name of the file format for the data specified with the **-data** or **-file** option. 


**-file** *name*

 *name* gives the name of a file that is to be read to supply data for the photo image. The file format must be one of those for which there is an image file format handler that can read data. 


**-gamma** *value*

 Specifies that the colors allocated for displaying this image in a window should be corrected for a non-linear display with the specified gamma exponent value. (The intensity produced by most CRT displays is a power function of the input value, to a good approximation; gamma is the exponent and is typically around 2). The value specified must be greater than zero. The default value is one (no correction). In general, values greater than one will make the image lighter, and values less than one will make it darker. 


**-height** *number*

 Specifies the height of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink vertically to fit the data stored in it. 


**-palette** *palette-spec*

 Specifies the resolution of the color cube to be allocated for displaying this image, and thus the number of colors used from the colormaps of the windows where it is displayed. The *palette-spec* string may be either a single decimal number, specifying the number of shades of gray to use, or three decimal numbers separated by slashes (/), specifying the number of shades of red, green and blue to use, respectively. If the first form (a single number) is used, the image will be displayed in monochrome (i.e., grayscale). 


**-width** *number*

 Specifies the width of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink horizontally to fit the data stored in it. 

 Image command
-------------

 When a photo image is created, Tk also creates a new command whose name is the same as the image. This command may be used to invoke various operations on the image. It has the following general form: 
```
*imageName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command.  Those options that write data to the image generally expand the size of the image, if necessary, to accommodate the data written to the image, unless the user has specified non-zero values for the **-width** and/or **-height** configuration options, in which case the width and/or height, respectively, of the image will not be changed. 


 The following commands are possible for photo images: 


 
*imageName* **blank**

 Blank the image; that is, set the entire image to have no data, so it will be displayed as transparent, and the background of whatever window it is displayed in will show through. 


*imageName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **[image create](image.htm)** **photo** command. 


*imageName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options for the image. If no *option* is specified, returns a list describing all of the available options for *imageName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **[image create](image.htm)** **photo** command. 


*imageName* **copy** *sourceImage* ?*option value(s) ...*?
 Copies a region from the image called *sourceImage* (which must be a photo image) to the image called *imageName*, possibly with pixel zooming and/or subsampling. If no options are specified, this command copies the whole of *sourceImage* into *imageName*, starting at coordinates (0,0) in *imageName*. The following options may be specified: 
 
**-from** *x1 y1 x2 y2*

 Specifies a rectangular sub-region of the source image to be copied. (*x1,y1*) and (*x2,y2*) specify diagonally opposite corners of the rectangle. If *x2* and *y2* are not specified, the default value is the bottom-right corner of the source image. The pixels copied will include the left and top edges of the specified rectangle but not the bottom or right edges. If the **-from** option is not given, the default is the whole source image. 


**-to** *x1 y1 x2 y2*

 Specifies a rectangular sub-region of the destination image to be affected. (*x1,y1*) and (*x2,y2*) specify diagonally opposite corners of the rectangle. If *x2* and *y2* are not specified, the default value is (*x1,y1*) plus the size of the source region (after subsampling and zooming, if specified). If *x2* and *y2* are specified, the source region will be replicated if necessary to fill the destination region in a tiled fashion. 

**-shrink**
 Specifies that the size of the destination image should be reduced, if necessary, so that the region being copied into is at the bottom-right corner of the image. This option will not affect the width or height of the image if the user has specified a non-zero value for the **-width** or **-height** configuration option, respectively. 


**-zoom** *x y*

 Specifies that the source region should be magnified by a factor of *x* in the X direction and *y* in the Y direction. If *y* is not given, the default value is the same as *x*. With this option, each pixel in the source image will be expanded into a block of *x* x *y* pixels in the destination image, all the same color. *x* and *y* must be greater than 0. 


**-subsample** *x y*

 Specifies that the source image should be reduced in size by using only every *x*th pixel in the X direction and *y*th pixel in the Y direction. Negative values will cause the image to be flipped about the Y or X axes, respectively. If *y* is not given, the default value is the same as *x*. 


**-compositingrule** *rule*

 Specifies how transparent pixels in the source image are combined with the destination image. When a compositing rule of *overlay* is set, the old contents of the destination image are visible, as if the source image were printed on a piece of transparent film and placed over the top of the destination. When a compositing rule of *set* is set, the old contents of the destination image are discarded and the source image is used as-is. The default compositing rule is *overlay*. 




*imageName* **data** ?*option value(s) ...*?
 Returns image data in the form of a string. The following options may be specified: 
 
**-background** *color*

 If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color. 


**-format** *format-name*

 Specifies the name of the image file format handler to be used. Specifically, this subcommand searches for the first handler whose name matches an initial substring of *format-name* and which has the capability to write a string containing this image data. If this option is not given, this subcommand uses a format that consists of a list (one element per row) of lists (one element per pixel/column) of colors in “**#***rrggbb*” format (where *rr* is a pair of hexadecimal digits for the red channel, *gg* for green, and *bb* for blue). 


**-from** *x1 y1 x2 y2*

 Specifies a rectangular region of *imageName* to be returned. If only *x1* and *y1* are specified, the region extends from *(x1,y1)* to the bottom-right corner of *imageName*. If all four coordinates are given, they specify diagonally opposite corners of the rectangular region, including x1,y1 and excluding x2,y2. The default, if this option is not given, is the whole image. 

**-grayscale**
 If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale. 




*imageName* **get** *x y*

 Returns the color of the pixel at coordinates (*x*,*y*) in the image as a list of three integers between 0 and 255, representing the red, green and blue components respectively. 


*imageName* **put** *data* ?*option value(s) ...*?
 Sets pixels in  *imageName* to the data specified in *data*. This command first searches the list of image file format handlers for a handler that can interpret the data in *data*, and then reads the image encoded within into *imageName* (the destination image). If *data* does not match any known format, an attempt to interpret it as a (top-to-bottom) list of scan-lines is made, with each scan-line being a (left-to-right) list of pixel colors (see **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)** for a description of valid colors.) Every scan-line must be of the same length. Note that when *data* is a single color name, you are instructing Tk to fill a rectangular region with that color. The following options may be specified: 
 
**-format** *format-name*

 Specifies the format of the image data in *data*. Specifically, only image file format handlers whose names begin with *format-name* will be used while searching for an image data format handler to read the data. 


**-to** *x1 y1* ?*x2 y2*?
 Specifies the coordinates of the top-left corner (*x1*,*y1*) of the region of *imageName* into which the image data will be copied. The default position is (0,0). If *x2*,*y2* is given and *data* is not large enough to cover the rectangle specified by this option, the image data extracted will be tiled so it covers the entire destination rectangle. Note that if *data* specifies a single color value, then a region extending to the bottom-right corner represented by (*x2*,*y2*) will be filled with that color. 




*imageName* **read** *filename* ?*option value(s) ...*?
 Reads image data from the file named *filename* into the image. This command first searches the list of image file format handlers for a handler that can interpret the data in *filename*, and then reads the image in *filename* into *imageName* (the destination image). The following options may be specified: 
 
**-format** *format-name*

 Specifies the format of the image data in *filename*. Specifically, only image file format handlers whose names begin with *format-name* will be used while searching for an image data format handler to read the data. 


**-from** *x1 y1 x2 y2*

 Specifies a rectangular sub-region of the image file data to be copied to the destination image. If only *x1* and *y1* are specified, the region extends from (*x1,y1*) to the bottom-right corner of the image in the image file. If all four coordinates are specified, they specify diagonally opposite corners or the region. The default, if this option is not specified, is the whole of the image in the image file. 

**-shrink**
 If this option, the size of *imageName* will be reduced, if necessary, so that the region into which the image file data are read is at the bottom-right corner of the *imageName*. This option will not affect the width or height of the image if the user has specified a non-zero value for the **-width** or **-height** configuration option, respectively. 


**-to** *x y*

 Specifies the coordinates of the top-left corner of the region of *imageName* into which data from *filename* are to be read. The default is (0,0). 




*imageName* **redither**

 The dithering algorithm used in displaying photo images propagates quantization errors from one pixel to its neighbors. If the image data for *imageName* is supplied in pieces, the dithered image may not be exactly correct. Normally the difference is not noticeable, but if it is a problem, this command can be used to recalculate the dithered image in each window where the image is displayed. 


*imageName* **transparency** *subcommand* ?*arg arg ...*?
 Allows examination and manipulation of the transparency information in the photo image. Several subcommands are available: 
 
*imageName* **transparency get** *x y*

 Returns a boolean indicating if the pixel at (*x*,*y*) is transparent. 


*imageName* **transparency set** *x y boolean*

 Makes the pixel at (*x*,*y*) transparent if *boolean* is true, and makes that pixel opaque otherwise. 




*imageName* **write** *filename* ?*option value(s) ...*?
 Writes image data from *imageName* to a file named *filename*. The following options may be specified: 
 
**-background** *color*

 If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color. 


**-format** *format-name*

 Specifies the name of the image file format handler to be used to write the data to the file. Specifically, this subcommand searches for the first handler whose name matches an initial substring of *format-name* and which has the capability to write an image file. If this option is not given, the format is guessed from the file extension. If that cannot be determined, this subcommand uses the first handler that has the capability to write an image file. 


**-from** *x1 y1 x2 y2*

 Specifies a rectangular region of *imageName* to be written to the image file. If only *x1* and *y1* are specified, the region extends from *(x1,y1)* to the bottom-right corner of *imageName*. If all four coordinates are given, they specify diagonally opposite corners of the rectangular region. The default, if this option is not given, is the whole image. 

**-grayscale**
 If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale. 



 Image formats
-------------

 The photo image code is structured to allow handlers for additional image file formats to be added easily. The photo image code maintains a list of these handlers. Handlers are added to the list by registering them with a call to **[Tk\_CreatePhotoImageFormat](https://www.tcl.tk/man/tcl/TkLib/CrtPhImgFmt.htm)**. The standard Tk distribution comes with handlers for PPM/PGM, PNG and GIF formats, which are automatically registered on initialization.  When reading an image file or processing string data specified with the **-data** configuration option, the photo image code invokes each handler in turn until one is found that claims to be able to read the data in the file or string. Usually this will find the correct handler, but if it does not, the user may give a format name with the **-format** option to specify which handler to use. In fact the photo image code will try those handlers whose names begin with the string specified for the **-format** option (the comparison is case-insensitive). For example, if the user specifies **-format gif**, then a handler named GIF87 or GIF89 may be invoked, but a handler named JPEG may not (assuming that such handlers had been registered). 


 When writing image data to a file, the processing of the **-format** option is slightly different: the string value given for the **-format** option must begin with the complete name of the requested handler, and may contain additional information following that, which the handler can use, for example, to specify which variant to use of the formats supported by the handler. Note that not all image handlers may support writing transparency data to a file, even where the target image format does. 


### Format suboptions

 Some image formats support sub-options, which are specified at the time that the image is loaded using additional words in the **-format** option. At the time of writing, the following are supported: 
 
**gif -index** *indexValue*

 When parsing a multi-part GIF image, Tk normally only accesses the first image. By giving the **-index** sub-option, the *indexValue*'th value may be used instead. The *indexValue* must be an integer from 0 up to the number of image parts in the GIF data. 


**png -alpha** *alphaValue*

 An additional alpha filtering for the overall image, which allows the background on which the image is displayed to show through. This usually also has the effect of desaturating the image. The *alphaValue* must be between 0.0 and 1.0. 

 Color allocation
----------------

 When a photo image is displayed in a window, the photo image code allocates colors to use to display the image and dithers the image, if necessary, to display a reasonable approximation to the image using the colors that are available. The colors are allocated as a color cube, that is, the number of colors allocated is the product of the number of shades of red, green and blue.  Normally, the number of colors allocated is chosen based on the depth of the window. For example, in an 8-bit PseudoColor window, the photo image code will attempt to allocate seven shades of red, seven shades of green and four shades of blue, for a total of 198 colors. In a 1-bit StaticGray (monochrome) window, it will allocate two colors, black and white. In a 24-bit DirectColor or TrueColor window, it will allocate 256 shades each of red, green and blue. Fortunately, because of the way that pixel values can be combined in DirectColor and TrueColor windows, this only requires 256 colors to be allocated. If not all of the colors can be allocated, the photo image code reduces the number of shades of each primary color and tries again. 


 The user can exercise some control over the number of colors that a photo image uses with the **-palette** configuration option. If this option is used, it specifies the maximum number of shades of each primary color to try to allocate. It can also be used to force the image to be displayed in shades of gray, even on a color display, by giving a single number rather than three numbers separated by slashes. 


Credits
-------

 The photo image type was designed and implemented by Paul Mackerras, based on his earlier photo widget and some suggestions from John Ousterhout. Example
-------

 Load an image from a file and tile it to the size of a window, which is useful for producing a tiled background: 

```
# These lines should be called once
**image create photo** untiled -file "theFile.ppm"
**image create photo** tiled

# These lines should be called whenever .someWidget changes
# size; a <Configure> binding is useful here
set width  [winfo width .someWidget]
set height [winfo height .someWidget]
tiled **copy** untiled -to 0 0 $width $height -shrink
```
  The PNG image loader allows the application of an additional alpha factor during loading, which is useful for generating images suitable for disabled buttons: 



```
**image create photo** icon -file "icon.png"
**image create photo** iconDisabled -file "icon.png" \
        -format "png -alpha 0.5"
button .b -image icon -disabledimage iconDisabled
```
 See also
--------

 **[image](image.htm)** Copyright © 1994 The Australian National University  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/photo.htm>

winfo
=====

  
[NAME](winfo.htm#M2) winfo — Return window-related information 
[SYNOPSIS](winfo.htm#M3) 
[DESCRIPTION](winfo.htm#M4)  
[**winfo atom** ?**-displayof** *window*? *name*](winfo.htm#M5) 
[**winfo atomname** ?**-displayof** *window*? *id*](winfo.htm#M6) 
[**winfo cells** *window*](winfo.htm#M7) 
[**winfo children** *window*](winfo.htm#M8) 
[**winfo class** *window*](winfo.htm#M9) 
[**winfo colormapfull** *window*](winfo.htm#M10) 
[**winfo containing** ?**-displayof** *window*? *rootX rootY*](winfo.htm#M11) 
[**winfo depth** *window*](winfo.htm#M12) 
[**winfo exists** *window*](winfo.htm#M13) 
[**winfo fpixels** *window* *number*](winfo.htm#M14) 
[**winfo geometry** *window*](winfo.htm#M15) 
[**winfo height** *window*](winfo.htm#M16) 
[**winfo id** *window*](winfo.htm#M17) 
[**winfo interps** ?**-displayof** *window*?](winfo.htm#M18) 
[**winfo ismapped** *window*](winfo.htm#M19) 
[**winfo manager** *window*](winfo.htm#M20) 
[**winfo name** *window*](winfo.htm#M21) 
[**winfo parent** *window*](winfo.htm#M22) 
[**winfo pathname** ?**-displayof** *window*? *id*](winfo.htm#M23) 
[**winfo pixels** *window* *number*](winfo.htm#M24) 
[**winfo pointerx** *window*](winfo.htm#M25) 
[**winfo pointerxy** *window*](winfo.htm#M26) 
[**winfo pointery** *window*](winfo.htm#M27) 
[**winfo reqheight** *window*](winfo.htm#M28) 
[**winfo reqwidth** *window*](winfo.htm#M29) 
[**winfo rgb** *window color*](winfo.htm#M30) 
[**winfo rootx** *window*](winfo.htm#M31) 
[**winfo rooty** *window*](winfo.htm#M32) 
[**winfo screen** *window*](winfo.htm#M33) 
[**winfo screencells** *window*](winfo.htm#M34) 
[**winfo screendepth** *window*](winfo.htm#M35) 
[**winfo screenheight** *window*](winfo.htm#M36) 
[**winfo screenmmheight** *window*](winfo.htm#M37) 
[**winfo screenmmwidth** *window*](winfo.htm#M38) 
[**winfo screenvisual** *window*](winfo.htm#M39) 
[**winfo screenwidth** *window*](winfo.htm#M40) 
[**winfo server** *window*](winfo.htm#M41) 
[**winfo toplevel** *window*](winfo.htm#M42) 
[**winfo viewable** *window*](winfo.htm#M43) 
[**winfo visual** *window*](winfo.htm#M44) 
[**winfo visualid** *window*](winfo.htm#M45) 
[**winfo visualsavailable** *window* ?**includeids**?](winfo.htm#M46) 
[**winfo vrootheight** *window*](winfo.htm#M47) 
[**winfo vrootwidth** *window*](winfo.htm#M48) 
[**winfo vrootx** *window*](winfo.htm#M49) 
[**winfo vrooty** *window*](winfo.htm#M50) 
[**winfo width** *window*](winfo.htm#M51) 
[**winfo x** *window*](winfo.htm#M52) 
[**winfo y** *window*](winfo.htm#M53) 
















































 
[EXAMPLE](winfo.htm#M54) 
[KEYWORDS](winfo.htm#M55) 




 Name
----

 winfo — Return window-related information Synopsis
--------

 **winfo** *option* ?*arg arg ...*?  
 Description
-----------

 The **winfo** command is used to retrieve information about windows managed by Tk. It can take any of a number of different forms, depending on the *option* argument. The legal forms are: 
 
**winfo atom** ?**-displayof** *window*? *name*

 Returns a decimal string giving the integer identifier for the atom whose name is *name*. If no atom exists with the name *name* then a new one is created. If the **-displayof** option is given then the atom is looked up on the display of *window*; otherwise it is looked up on the display of the application's main window. 


**winfo atomname** ?**-displayof** *window*? *id*

 Returns the textual name for the atom whose integer identifier is *id*. If the **-displayof** option is given then the identifier is looked up on the display of *window*; otherwise it is looked up on the display of the application's main window. This command is the inverse of the **winfo atom** command. It generates an error if no such atom exists. 


**winfo cells** *window*

 Returns a decimal string giving the number of cells in the color map for *window*. 


**winfo children** *window*

 Returns a list containing the path names of all the children of *window*. Top-level windows are returned as children of their logical parents. The list is in stacking order, with the lowest window first, except for Top-level windows which are not returned in stacking order. Use the **[wm stackorder](wm.htm)** command to query the stacking order of Top-level windows. 


**winfo class** *window*

 Returns the class name for *window*. 


**winfo colormapfull** *window*

 Returns 1 if the colormap for *window* is known to be full, 0 otherwise. The colormap for a window is “known” to be full if the last attempt to allocate a new color on that window failed and this application has not freed any colors in the colormap since the failed allocation. 


**winfo containing** ?**-displayof** *window*? *rootX rootY*

 Returns the path name for the window containing the point given by *rootX* and *rootY*. *RootX* and *rootY* are specified in screen units (i.e. any form acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**) in the coordinate system of the root window (if a virtual-root window manager is in use then the coordinate system of the virtual root window is used). If the **-displayof** option is given then the coordinates refer to the screen containing *window*; otherwise they refer to the screen of the application's main window. If no window in this application contains the point then an empty string is returned. In selecting the containing window, children are given higher priority than parents and among siblings the highest one in the stacking order is chosen. 


**winfo depth** *window*

 Returns a decimal string giving the depth of *window* (number of bits per pixel). 


**winfo exists** *window*

 Returns 1 if there exists a window named *window*, 0 if no such window exists. 


**winfo fpixels** *window* *number*

 Returns a floating-point value giving the number of pixels in *window* corresponding to the distance given by *number*. *Number* may be specified in any of the forms acceptable to **[Tk\_GetScreenMM](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**, such as “2.0c” or “1i”. The return value may be fractional; for an integer value, use **winfo pixels**. 


**winfo geometry** *window*

 Returns the geometry for *window*, in the form *width***x***height***+***x***+***y*. All dimensions are in pixels. 


**winfo height** *window*

 Returns a decimal string giving *window*'s height in pixels. When a window is first created its height will be 1 pixel; the height will eventually be changed by a geometry manager to fulfil the window's needs. If you need the true height immediately after creating a widget, invoke **[update](../tclcmd/update.htm)** to force the geometry manager to arrange it, or use **winfo reqheight** to get the window's requested height instead of its actual height. 


**winfo id** *window*

 Returns a hexadecimal string giving a low-level platform-specific identifier for *window*. On Unix platforms, this is the X window identifier. Under Windows, this is the Windows HWND. On the Macintosh the value has no meaning outside Tk. 


**winfo interps** ?**-displayof** *window*?
 Returns a list whose members are the names of all Tcl interpreters (e.g. all Tk-based applications) currently registered for a particular display. If the **-displayof** option is given then the return value refers to the display of *window*; otherwise it refers to the display of the application's main window. 


**winfo ismapped** *window*

 Returns **1** if *window* is currently mapped, **0** otherwise. 


**winfo manager** *window*

 Returns the name of the geometry manager currently responsible for *window*, or an empty string if *window* is not managed by any geometry manager. The name is usually the name of the Tcl command for the geometry manager, such as **[pack](pack.htm)** or **[place](place.htm)**. If the geometry manager is a widget, such as canvases or text, the name is the widget's class command, such as **[canvas](canvas.htm)**. 


**winfo name** *window*

 Returns *window*'s name (i.e. its name within its parent, as opposed to its full path name). The command **winfo name .** will return the name of the application. 


**winfo parent** *window*

 Returns the path name of *window*'s parent, or an empty string if *window* is the main window of the application. 


**winfo pathname** ?**-displayof** *window*? *id*

 Returns the path name of the window whose X identifier is *id*. *Id* must be a decimal, hexadecimal, or octal integer and must correspond to a window in the invoking application. If the **-displayof** option is given then the identifier is looked up on the display of *window*; otherwise it is looked up on the display of the application's main window. 


**winfo pixels** *window* *number*

 Returns the number of pixels in *window* corresponding to the distance given by *number*. *Number* may be specified in any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**, such as “2.0c” or “1i”. The result is rounded to the nearest integer value; for a fractional result, use **winfo fpixels**. 


**winfo pointerx** *window*

 If the mouse pointer is on the same screen as *window*, returns the pointer's x coordinate, measured in pixels in the screen's root window. If a virtual root window is in use on the screen, the position is measured in the virtual root. If the mouse pointer is not on the same screen as *window* then -1 is returned. 


**winfo pointerxy** *window*

 If the mouse pointer is on the same screen as *window*, returns a list with two elements, which are the pointer's x and y coordinates measured in pixels in the screen's root window. If a virtual root window is in use on the screen, the position is computed in the virtual root. If the mouse pointer is not on the same screen as *window* then both of the returned coordinates are -1. 


**winfo pointery** *window*

 If the mouse pointer is on the same screen as *window*, returns the pointer's y coordinate, measured in pixels in the screen's root window. If a virtual root window is in use on the screen, the position is computed in the virtual root. If the mouse pointer is not on the same screen as *window* then -1 is returned. 


**winfo reqheight** *window*

 Returns a decimal string giving *window*'s requested height, in pixels. This is the value used by *window*'s geometry manager to compute its geometry. 


**winfo reqwidth** *window*

 Returns a decimal string giving *window*'s requested width, in pixels. This is the value used by *window*'s geometry manager to compute its geometry. 


**winfo rgb** *window color*

 Returns a list containing three decimal values in the range 0 to 65535, which are the red, green, and blue intensities that correspond to *color* in the window given by *window*. *Color* may be specified in any of the forms acceptable for a color option. 


**winfo rootx** *window*

 Returns a decimal string giving the x-coordinate, in the root window of the screen, of the upper-left corner of *window*'s border (or *window* if it has no border). 


**winfo rooty** *window*

 Returns a decimal string giving the y-coordinate, in the root window of the screen, of the upper-left corner of *window*'s border (or *window* if it has no border). 


**winfo screen** *window*

 Returns the name of the screen associated with *window*, in the form *displayName*.*screenIndex*. 


**winfo screencells** *window*

 Returns a decimal string giving the number of cells in the default color map for *window*'s screen. 


**winfo screendepth** *window*

 Returns a decimal string giving the depth of the root window of *window*'s screen (number of bits per pixel). 


**winfo screenheight** *window*

 Returns a decimal string giving the height of *window*'s screen, in pixels. 


**winfo screenmmheight** *window*

 Returns a decimal string giving the height of *window*'s screen, in millimeters. 


**winfo screenmmwidth** *window*

 Returns a decimal string giving the width of *window*'s screen, in millimeters. 


**winfo screenvisual** *window*

 Returns one of the following strings to indicate the default visual class for *window*'s screen: **directcolor**, **grayscale**, **pseudocolor**, **staticcolor**, **staticgray**, or **truecolor**. 


**winfo screenwidth** *window*

 Returns a decimal string giving the width of *window*'s screen, in pixels. 


**winfo server** *window*

 Returns a string containing information about the server for *window*'s display. The exact format of this string may vary from platform to platform. For X servers the string has the form “**X***major***R***minor vendor vendorVersion*” where *major* and *minor* are the version and revision numbers provided by the server (e.g., **X11R5**), *vendor* is the name of the vendor for the server, and *vendorRelease* is an integer release number provided by the server. 


**winfo toplevel** *window*

 Returns the path name of the top-of-hierarchy window containing *window*. In standard Tk this will always be a **[toplevel](toplevel.htm)** widget, but extensions may create other kinds of top-of-hierarchy widgets. 


**winfo viewable** *window*

 Returns 1 if *window* and all of its ancestors up through the nearest toplevel window are mapped. Returns 0 if any of these windows are not mapped. 


**winfo visual** *window*

 Returns one of the following strings to indicate the visual class for *window*: **directcolor**, **grayscale**, **pseudocolor**, **staticcolor**, **staticgray**, or **truecolor**. 


**winfo visualid** *window*

 Returns the X identifier for the visual for *window*. 


**winfo visualsavailable** *window* ?**includeids**?
 Returns a list whose elements describe the visuals available for *window*'s screen. Each element consists of a visual class followed by an integer depth. The class has the same form as returned by **winfo visual**. The depth gives the number of bits per pixel in the visual. In addition, if the **includeids** argument is provided, then the depth is followed by the X identifier for the visual. 


**winfo vrootheight** *window*

 Returns the height of the virtual root window associated with *window* if there is one; otherwise returns the height of *window*'s screen. 


**winfo vrootwidth** *window*

 Returns the width of the virtual root window associated with *window* if there is one; otherwise returns the width of *window*'s screen. 


**winfo vrootx** *window*

 Returns the x-offset of the virtual root window associated with *window*, relative to the root window of its screen. This is normally either zero or negative. Returns 0 if there is no virtual root window for *window*. 


**winfo vrooty** *window*

 Returns the y-offset of the virtual root window associated with *window*, relative to the root window of its screen. This is normally either zero or negative. Returns 0 if there is no virtual root window for *window*. 


**winfo width** *window*

 Returns a decimal string giving *window*'s width in pixels. When a window is first created its width will be 1 pixel; the width will eventually be changed by a geometry manager to fulfil the window's needs. If you need the true width immediately after creating a widget, invoke **[update](../tclcmd/update.htm)** to force the geometry manager to arrange it, or use **winfo reqwidth** to get the window's requested width instead of its actual width. 


**winfo x** *window*

 Returns a decimal string giving the x-coordinate, in *window*'s parent, of the upper-left corner of *window*'s border (or *window* if it has no border). 


**winfo y** *window*

 Returns a decimal string giving the y-coordinate, in *window*'s parent, of the upper-left corner of *window*'s border (or *window* if it has no border). 

 Example
-------

 Print where the mouse pointer is and what window it is currently over: 
```
lassign [**winfo pointerxy** .] x y
puts -nonewline "Mouse pointer at ($x,$y) which is "
set win [**winfo containing** $x $y]
if {$win eq ""} {
    puts "over no window"
} else {
    puts "over $win"
}
```
 Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/winfo.htm>

font
====

  
[NAME](font.htm#M2) font — Create and inspect fonts. 
[SYNOPSIS](font.htm#M3) 
[DESCRIPTION](font.htm#M4)  
[**font actual** *font* ?**-displayof** *window*? ?*option*? ?**--**? ?*char*?](font.htm#M5) 
[**font configure** *fontname* ?*option*? ?*value option value ...*?](font.htm#M6) 
[**font create** ?*fontname*? ?*option value ...*?](font.htm#M7) 
[**font delete** *fontname* ?*fontname ...*?](font.htm#M8) 
[**font families** ?**-displayof** *window*?](font.htm#M9) 
[**font measure** *font* ?**-displayof** *window*? *text*](font.htm#M10) 
[**font metrics** *font* ?**-displayof** *window*? ?*option*?](font.htm#M11) 
[**font names**](font.htm#M12) 







 
[FONT DESCRIPTIONS](font.htm#M13) 
[[1] *fontname*](font.htm#M14) 
[[2] *systemfont*](font.htm#M15) 
[[3] *family* ?*size*? ?*style*? ?*style ...*?](font.htm#M16) 
[[4] X-font names (XLFD)](font.htm#M17) 
[[5] *option value* ?*option value ...*?](font.htm#M18) 




 
[FONT METRICS](font.htm#M19)  
[**-ascent**](font.htm#M20)  
[**-descent**](font.htm#M21)  
[**-linespace**](font.htm#M22) 
[**-fixed**](font.htm#M23)  



 
[FONT OPTIONS](font.htm#M24)  
[**-family** *name*](font.htm#M25) 
[**-size** *size*](font.htm#M26) 
[**-weight** *weight*](font.htm#M27) 
[**-slant** *slant*](font.htm#M28) 
[**-underline** *boolean*](font.htm#M29) 
[**-overstrike** *boolean*](font.htm#M30) 





 
[STANDARD FONTS](font.htm#M31)  
[**TkDefaultFont**](font.htm#M32) 
[**TkTextFont**](font.htm#M33) 
[**TkFixedFont**](font.htm#M34) 
[**TkMenuFont**](font.htm#M35) 
[**TkHeadingFont**](font.htm#M36) 
[**TkCaptionFont**](font.htm#M37) 
[**TkSmallCaptionFont**](font.htm#M38) 
[**TkIconFont**](font.htm#M39) 
[**TkTooltipFont**](font.htm#M40) 








 
[PLATFORM SPECIFIC FONTS](font.htm#M41)  
[**X Windows**](font.htm#M42) 
[**MS Windows**](font.htm#M43) 
[**Mac OS X**](font.htm#M44) 


 
[EXAMPLE](font.htm#M45) 
[SEE ALSO](font.htm#M46) 
[KEYWORDS](font.htm#M47) 










 Name
----

 font — Create and inspect fonts. Synopsis
--------

 **font** *option* ?*arg arg ...*?  
 Description
-----------

 The **font** command provides several facilities for dealing with fonts, such as defining named fonts and inspecting the actual attributes of a font. The command has several different forms, determined by the first argument. The following forms are currently supported: 
 
**font actual** *font* ?**-displayof** *window*? ?*option*? ?**--**? ?*char*?
 Returns information about the actual attributes that are obtained when *font* is used on *window*'s display; the actual attributes obtained may differ from the attributes requested due to platform-dependent limitations, such as the availability of font families and point sizes. *font* is a font description; see **[FONT DESCRIPTIONS](#M13)** below. If the *window* argument is omitted, it defaults to the main window. If *option* is specified, returns the value of that attribute; if it is omitted, the return value is a list of all the attributes and their values. See **[FONT OPTIONS](#M24)** below for a list of the possible attributes. If the *char* argument is supplied, it must be a single character. The font attributes returned will be those of the specific font used to render that character, which will be different from the base font if the base font does not contain the given character. If *char* may be a hyphen, it should be preceded by **--** to distinguish it from a misspelled *option*. 


**font configure** *fontname* ?*option*? ?*value option value ...*?
 Query or modify the desired attributes for the named font called *fontname*. If no *option* is specified, returns a list describing all the options and their values for *fontname*. If a single *option* is specified with no *value*, then returns the current value of that attribute. If one or more *option*-*value* pairs are specified, then the command modifies the given named font to have the given values; in this case, all widgets using that font will redisplay themselves using the new attributes for the font. See **[FONT OPTIONS](#M24)** below for a list of the possible attributes.  Note that on Aqua/Mac OS X, the system fonts (see **[PLATFORM SPECIFIC FONTS](#M41)** below) may not be actually altered because they are implemented by the system theme. To achieve the effect of modification, use **font actual** to get their configuration and **font create** to synthesize a copy of the font which can be modified. 




**font create** ?*fontname*? ?*option value ...*?
 Creates a new named font and returns its name. *fontname* specifies the name for the font; if it is omitted, then Tk generates a new name of the form **font***x*, where *x* is an integer. There may be any number of *option*-*value* pairs, which provide the desired attributes for the new named font. See **[FONT OPTIONS](#M24)** below for a list of the possible attributes. 


**font delete** *fontname* ?*fontname ...*?
 Delete the specified named fonts. If there are widgets using the named font, the named font will not actually be deleted until all the instances are released. Those widgets will continue to display using the last known values for the named font. If a deleted named font is subsequently recreated with another call to **font create**, the widgets will use the new named font and redisplay themselves using the new attributes of that font. 


**font families** ?**-displayof** *window*?
 The return value is a list of the case-insensitive names of all font families that exist on *window*'s display. If the *window* argument is omitted, it defaults to the main window. 


**font measure** *font* ?**-displayof** *window*? *text*

 Measures the amount of space the string *text* would use in the given *font* when displayed in *window*. *font* is a font description; see **[FONT DESCRIPTIONS](#M13)** below. If the *window* argument is omitted, it defaults to the main window. The return value is the total width in pixels of *text*, not including the extra pixels used by highly exaggerated characters such as cursive “f”. If the string contains newlines or tabs, those characters are not expanded or treated specially when measuring the string. 


**font metrics** *font* ?**-displayof** *window*? ?*option*?
 Returns information about the metrics (the font-specific data), for *font* when it is used on *window*'s display. *font* is a font description; see **[FONT DESCRIPTIONS](#M13)** below. If the *window* argument is omitted, it defaults to the main window. If *option* is specified, returns the value of that metric; if it is omitted, the return value is a list of all the metrics and their values. See **[FONT METRICS](#M19)** below for a list of the possible metrics. 

**font names**
 The return value is a list of all the named fonts that are currently defined. 

 Font descriptions
-----------------

 The following formats are accepted as a font description anywhere *font* is specified as an argument above; these same forms are also permitted when specifying the **-font** option for widgets. 
[1] *fontname*

 The name of a named font, created using the **font create** command. When a widget uses a named font, it is guaranteed that this will never cause an error, as long as the named font exists, no matter what potentially invalid or meaningless set of attributes the named font has. If the named font cannot be displayed with exactly the specified attributes, some other close font will be substituted automatically. 

[2] *systemfont*

 The platform-specific name of a font, interpreted by the graphics server. This also includes, under X, an XLFD (see [4]) for which a single “**\***” character was used to elide more than one field in the middle of the name. See **[PLATFORM SPECIFIC FONTS](#M41)** for a list of the system fonts. 

[3] *family* ?*size*? ?*style*? ?*style ...*?
 A properly formed list whose first element is the desired font *family* and whose optional second element is the desired *size*. The interpretation of the *size* attribute follows the same rules described for **-size** in **[FONT OPTIONS](#M24)** below. Any additional optional arguments following the *size* are font *style*s. Possible values for the *style* arguments are as follows: 

|  |  |  |  |
| --- | --- | --- | --- |
| **normal** | **bold** | **roman** | **italic** |
| **underline** | **overstrike** |



[4] X-font names (XLFD)
 A Unix-centric font name of the form *-foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spacing-width-charset-encoding*. The “**\***” character may be used to skip individual fields that the user does not care about. There must be exactly one “**\***” for each field skipped, except that a “**\***” at the end of the XLFD skips any remaining fields; the shortest valid XLFD is simply “**\***”, signifying all fields as defaults. Any fields that were skipped are given default values. For compatibility, an XLFD always chooses a font of the specified pixel size (not point size); although this interpretation is not strictly correct, all existing applications using XLFDs assumed that one “point” was in fact one pixel and would display incorrectly (generally larger) if the correct size font were actually used. 

[5] *option value* ?*option value ...*?
 A properly formed list of *option*-*value* pairs that specify the desired attributes of the font, in the same format used when defining a named font; see **[FONT OPTIONS](#M24)** below. 

  When font description *font* is used, the system attempts to parse the description according to each of the above five rules, in the order specified. Cases [1] and [2] must match the name of an existing named font or of a system font. Cases [3], [4], and [5] are accepted on all platforms and the closest available font will be used. In some situations it may not be possible to find any close font (e.g., the font family was a garbage value); in that case, some system-dependent default font is chosen. If the font description does not match any of the above patterns, an error is generated. 


Font metrics
------------

 The following options are used by the **font metrics** command to query font-specific data determined when the font was created. These properties are for the whole font itself and not for individual characters drawn in that font. In the following definitions, the “baseline” of a font is the horizontal line where the bottom of most letters line up; certain letters, such as lower-case “g” stick below the baseline. 
 **-ascent** 
 The amount in pixels that the tallest letter sticks up above the baseline of the font, plus any extra blank space added by the designer of the font. 

**-descent** 
 The largest amount in pixels that any letter sticks down below the baseline of the font, plus any extra blank space added by the designer of the font. 

**-linespace**
 Returns how far apart vertically in pixels two lines of text using the same font should be placed so that none of the characters in one line overlap any of the characters in the other line. This is generally the sum of the ascent above the baseline line plus the descent below the baseline. 

**-fixed** 
 Returns a boolean flag that is “**1**” if this is a fixed-width font, where each normal character is the same width as all the other characters, or is “**0**” if this is a proportionally-spaced font, where individual characters have different widths. The widths of control characters, tab characters, and other non-printing characters are not included when calculating this value. 

 Font options
------------

 The following options are supported on all platforms, and are used when constructing a named font or when specifying a font using style [5] as above: 
 
**-family** *name*

 The case-insensitive font family name. Tk guarantees to support the font families named **Courier** (a monospaced “typewriter” font), **Times** (a serifed “newspaper” font), and **Helvetica** (a sans-serif “European” font). The most closely matching native font family will automatically be substituted when one of the above font families is used. The *name* may also be the name of a native, platform-specific font family; in that case it will work as desired on one platform but may not display correctly on other platforms. If the family is unspecified or unrecognized, a platform-specific default font will be chosen. 


**-size** *size*

 The desired size of the font. If the *size* argument is a positive number, it is interpreted as a size in points. If *size* is a negative number, its absolute value is interpreted as a size in pixels. If a font cannot be displayed at the specified size, a nearby size will be chosen. If *size* is unspecified or zero, a platform-dependent default size will be chosen.  Sizes should normally be specified in points so the application will remain the same ruler size on the screen, even when changing screen resolutions or moving scripts across platforms. However, specifying pixels is useful in certain circumstances such as when a piece of text must line up with respect to a fixed-size bitmap. The mapping between points and pixels is set when the application starts, based on properties of the installed monitor, but it can be overridden by calling the **[tk scaling](tk.htm)** command. 




**-weight** *weight*

 The nominal thickness of the characters in the font. The value **normal** specifies a normal weight font, while **bold** specifies a bold font. The closest available weight to the one specified will be chosen. The default weight is **normal**. 


**-slant** *slant*

 The amount the characters in the font are slanted away from the vertical. Valid values for slant are **roman** and **italic**. A roman font is the normal, upright appearance of a font, while an italic font is one that is tilted some number of degrees from upright. The closest available slant to the one specified will be chosen. The default slant is **roman**. 


**-underline** *boolean*

 The value is a boolean flag that specifies whether characters in this font should be underlined. The default value for underline is **false**. 


**-overstrike** *boolean*

 The value is a boolean flag that specifies whether a horizontal line should be drawn through the middle of characters in this font. The default value for overstrike is **false**. 

 Standard fonts
--------------

 The following named fonts are supported on all systems, and default to values that match appropriate system defaults. 
 **TkDefaultFont**
 This font is the default for all GUI items not otherwise specified. 

**TkTextFont**
 This font should be used for user text in entry widgets, listboxes etc. 

**TkFixedFont**
 This font is the standard fixed-width font. 

**TkMenuFont**
 This font is used for menu items. 

**TkHeadingFont**
 This font should be used for column headings in lists and tables. 

**TkCaptionFont**
 This font should be used for window and dialog caption bars. 

**TkSmallCaptionFont**
 This font should be used for captions on contained windows or tool dialogs. 

**TkIconFont**
 This font should be used for icon captions. 

**TkTooltipFont**
 This font should be used for tooltip windows (transient information windows). 

  It is *not* advised to change these fonts, as they may be modified by Tk itself in response to system changes. Instead, make a copy of the font and modify that. 


Platform specific fonts
-----------------------

 The following system fonts are supported: 
 **X Windows**
 All valid X font names, including those listed by xlsfonts(1), are available. 

**MS Windows**
 The following fonts are supported, and are mapped to the user's style defaults. 

|  |  |  |
| --- | --- | --- |
| **system** | **ansi** | **device** |
| **systemfixed** | **ansifixed** | **oemfixed** |



**Mac OS X**
 The following fonts are supported, and are mapped to the user's style defaults. 

|  |  |  |
| --- | --- | --- |
| **system** | **application** | **menu** |

  Additionally, the following named fonts provide access to the Aqua theme fonts: 




|  |  |
| --- | --- |
| **systemSystemFont** | **systemEmphasizedSystemFont** |
| **systemSmallSystemFont** | **systemSmallEmphasizedSystemFont** |
| **systemApplicationFont** | **systemLabelFont** |
| **systemViewsFont** | **systemMenuTitleFont** |
| **systemMenuItemFont** | **systemMenuItemMarkFont** |
| **systemMenuItemCmdKeyFont** | **systemWindowTitleFont** |
| **systemPushButtonFont** | **systemUtilityWindowTitleFont** |
| **systemAlertHeaderFont** | **systemToolbarFont** |
| **systemMiniSystemFont** | **systemDetailSystemFont** |
| **systemDetailEmphasizedSystemFont** |



 Example
-------

 Fill a text widget with lots of font demonstrators, one for every font family installed on your system: 
```
pack [text .t -wrap none] -fill both -expand 1
set count 0
set tabwidth 0
foreach family [lsort -dictionary [**font families**]] {
    .t tag configure f[incr count] -font [list $family 10]
    .t insert end ${family}:\t {} \
            "This is a simple sampler\n" f$count
    set w [**font measure** [.t cget -font] ${family}:]
    if {$w+5 > $tabwidth} {
        set tabwidth [expr {$w+5}]
        .t configure -tabs $tabwidth
    }
}
```
 See also
--------

 **[options](options.htm)** Copyright © 1996 Sun Microsystems, Inc.  
 Copyright © 2006-2007 Daniel A. Steffen <das(at)users.sourceforge.net> 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/font.htm>

ttk\_entry
==========

  
[NAME](ttk_entry.htm#M2) ttk::entry — Editable text field widget 
[SYNOPSIS](ttk_entry.htm#M3) 
[DESCRIPTION](ttk_entry.htm#M4) 
[STANDARD OPTIONS](ttk_entry.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 
[-xscrollcommand, xScrollCommand, ScrollCommand](ttk_widget.htm#M-xscrollcommand) 




 
[WIDGET-SPECIFIC OPTIONS](ttk_entry.htm#M6)  
[-exportselection, exportSelection, ExportSelection](ttk_entry.htm#M7) 
[-invalidcommand, invalidCommand, InvalidCommand](ttk_entry.htm#M8) 
[-justify, justify, Justify](ttk_entry.htm#M9) 
[-show, show, Show](ttk_entry.htm#M10) 
[-state, state, State](ttk_entry.htm#M11) 
[-textvariable, textVariable, Variable](ttk_entry.htm#M12) 
[-validate, validate, Validate](ttk_entry.htm#M-validate) 
[-validatecommand, validateCommand, ValidateCommand](ttk_entry.htm#M-validatecommand) 
[-width, width, Width](ttk_entry.htm#M13) 








 
[NOTES](ttk_entry.htm#M14) 
[INDICES](ttk_entry.htm#M15)  
[*number*](ttk_entry.htm#M16) 
[**@***number*](ttk_entry.htm#M17) 
[**end**](ttk_entry.htm#M18) 
[**insert**](ttk_entry.htm#M19) 
[**sel.first**](ttk_entry.htm#M20) 
[**sel.last**](ttk_entry.htm#M21) 





 
[WIDGET COMMAND](ttk_entry.htm#M22)  
[*pathName* **bbox** *index*](ttk_entry.htm#M23) 
[*pathName* **delete** *first* ?*last*?](ttk_entry.htm#M24) 
[*pathName* **get**](ttk_entry.htm#M25) 
[*pathName* **icursor** *index*](ttk_entry.htm#M26) 
[*pathName* **index** *index*](ttk_entry.htm#M27) 
[*pathName* **insert** *index string*](ttk_entry.htm#M28) 
[*pathName* **selection** *option arg*](ttk_entry.htm#M29)  
[*pathName* **selection clear**](ttk_entry.htm#M30) 
[*pathName* **selection present**](ttk_entry.htm#M31) 
[*pathName* **selection range** *start* *end*](ttk_entry.htm#M32) 


 
[*pathName* **validate**](ttk_entry.htm#M33) 
[*pathName* **xview** *args*](ttk_entry.htm#M34)  
[*pathName* **xview**](ttk_entry.htm#M35) 
[*pathName* **xview** *index*](ttk_entry.htm#M36) 
[*pathName* **xview moveto** *fraction*](ttk_entry.htm#M37) 
[*pathName* **xview scroll** *number what*](ttk_entry.htm#M38) 



 








 
[VALIDATION](ttk_entry.htm#M39) 
[VALIDATION MODES](ttk_entry.htm#M40)  
[**none**](ttk_entry.htm#M41) 
[**key**](ttk_entry.htm#M42) 
[**focus**](ttk_entry.htm#M43) 
[**focusin**](ttk_entry.htm#M44) 
[**focusout**](ttk_entry.htm#M45) 
[**all**](ttk_entry.htm#M46) 





 
[VALIDATION SCRIPT SUBSTITUTIONS](ttk_entry.htm#M47)  
[**%d**](ttk_entry.htm#M48) 
[**%i**](ttk_entry.htm#M49) 
[**%P**](ttk_entry.htm#M50) 
[**%s**](ttk_entry.htm#M51) 
[**%S**](ttk_entry.htm#M52) 
[**%v**](ttk_entry.htm#M53) 
[**%V**](ttk_entry.htm#M54) 
[**%W**](ttk_entry.htm#M55) 







 
[DIFFERENCES FROM TK ENTRY WIDGET VALIDATION](ttk_entry.htm#M56) 
[DEFAULT BINDINGS](ttk_entry.htm#M57) 
[WIDGET STATES](ttk_entry.htm#M58) 
[SEE ALSO](ttk_entry.htm#M59) 
[KEYWORDS](ttk_entry.htm#M60) 















 Name
----

 ttk::entry — Editable text field widget Synopsis
--------

 **ttk::entry** *pathName* ?*options*?  
 Description
-----------

 An **ttk::entry** widget displays a one-line text string and allows that string to be edited by the user. The value of the string may be linked to a Tcl variable with the **-textvariable** option. Entry widgets support horizontal scrolling with the standard **-xscrollcommand** option and **xview** widget command. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 
**[-xscrollcommand, xScrollCommand, ScrollCommand](ttk_widget.htm#M-xscrollcommand)** 




 Widget-specific options
-----------------------

  Command-Line Name: **-exportselection** Database Name: **exportSelection** Database Class: **ExportSelection** 


A boolean value specifying whether or not a selection in the widget should be linked to the X selection. If the selection is exported, then selecting in the widget deselects the current X selection, selecting outside the widget deselects any widget selection, and the widget will respond to selection retrieval requests when it has a selection. 

Command-Line Name: **-invalidcommand** Database Name: **invalidCommand** Database Class: **InvalidCommand** 


A script template to evaluate whenever the **-validatecommand** returns 0. See **[VALIDATION](#M39)** below for more information. 

Command-Line Name: **-justify** Database Name: **justify** Database Class: **Justify** 


Specifies how the text is aligned within the entry widget. One of **left**, **center**, or **right**. 

Command-Line Name: **-show** Database Name: **show** Database Class: **Show** 


If this option is specified, then the true contents of the entry are not displayed in the window. Instead, each character in the entry's value will be displayed as the first character in the value of this option, such as “\*” or a bullet. This is useful, for example, if the entry is to be used to enter a password. If characters in the entry are selected and copied elsewhere, the information copied will be what is displayed, not the true contents of the entry. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Compatibility option; see *ttk::widget(n)* for details. Specifies one of three states for the entry, **normal**, **disabled**, or **readonly**. See **[WIDGET STATES](#M58)**, below. 

Command-Line Name: **-textvariable** Database Name: **textVariable** Database Class: **Variable** 


Specifies the name of a global variable whose value is linked to the entry widget's contents. Whenever the variable changes value, the widget's contents are updated, and vice versa. 

Command-Line Name: **-validate** Database Name: **validate** Database Class: **Validate** 


Specifies the mode in which validation should operate: **none**, **focus**, **focusin**, **focusout**, **key**, or **all**. Default is **none**, meaning that validation is disabled. See **[VALIDATION](#M39)** below. 

Command-Line Name: **-validatecommand** Database Name: **validateCommand** Database Class: **ValidateCommand** 


A script template to evaluate whenever validation is triggered. If set to the empty string (the default), validation is disabled. The script must return a boolean value. See **[VALIDATION](#M39)** below. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies an integer value indicating the desired width of the entry window, in average-size characters of the widget's font. 
 Notes
-----

 A portion of the entry may be selected as described below. If an entry is exporting its selection (see the **-exportselection** option), then it will observe the standard X11 protocols for handling the selection; entry selections are available as type **[STRING](../tclcmd/string.htm)**. Entries also observe the standard Tk rules for dealing with the input focus. When an entry has the input focus it displays an *insert cursor* to indicate where new characters will be inserted.  Entries are capable of displaying strings that are too long to fit entirely within the widget's window. In this case, only a portion of the string will be displayed; commands described below may be used to change the view in the window. Entries use the standard **-xscrollcommand** mechanism for interacting with scrollbars (see the description of the **-xscrollcommand** option for details). 


Indices
-------

 Many of the **[entry](entry.htm)** widget commands take one or more indices as arguments. An index specifies a particular character in the entry's string, in any of the following ways: 
 *number*
 Specifies the character as a numerical index, where 0 corresponds to the first character in the string. 


**@***number*

 In this form, *number* is treated as an x-coordinate in the entry's window; the character spanning that x-coordinate is used. For example, “**@0**” indicates the left-most character in the window. 

**end**
 Indicates the character just after the last one in the entry's string. This is equivalent to specifying a numerical index equal to the length of the entry's string. 

**insert**
 Indicates the character adjacent to and immediately following the insert cursor. 

**sel.first**
 Indicates the first character in the selection. It is an error to use this form if the selection is not in the entry window. 

**sel.last**
 Indicates the character just after the last one in the selection. It is an error to use this form if the selection is not in the entry window. 

  Abbreviations may be used for any of the forms above, e.g. “**e**” or “**sel.l**”. In general, out-of-range indices are automatically rounded to the nearest legal value. 


Widget command
--------------

 The following subcommands are possible for entry widgets: 
 
*pathName* **bbox** *index*

 Returns a list of four numbers describing the bounding box of the character given by *index*. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window. 


*pathName* **delete** *first* ?*last*?
 Delete one or more elements of the entry. *First* is the index of the first character to delete, and *last* is the index of the character just after the last one to delete. If *last* is not specified it defaults to *first*+1, i.e. a single character is deleted. This command returns the empty string. 


*pathName* **get**

 Returns the entry's string. 


*pathName* **icursor** *index*

 Arrange for the insert cursor to be displayed just before the character given by *index*. Returns the empty string. 


*pathName* **index** *index*

 Returns the numerical index corresponding to *index*. 


*pathName* **insert** *index string*

 Insert *string* just before the character indicated by *index*. Returns the empty string. 


*pathName* **selection** *option arg*

 This command is used to adjust the selection within an entry. It has several forms, depending on *option*: 
 
*pathName* **selection clear**

 Clear the selection if it is currently in this widget. If the selection is not in this widget then the command has no effect. Returns the empty string. 


*pathName* **selection present**

 Returns 1 if there is are characters selected in the entry, 0 if nothing is selected. 


*pathName* **selection range** *start* *end*

 Sets the selection to include the characters starting with the one indexed by *start* and ending with the one just before *end*. If *end* refers to the same character as *start* or an earlier one, then the entry's selection is cleared. 




*pathName* **validate**

 Force revalidation, independent of the conditions specified by the **-validate** option. Returns 0 if validation fails, 1 if it succeeds. Sets or clears the **invalid** state accordingly. See **[VALIDATION](#M39)** below for more details. 


*pathName* **xview** *args*

 This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: 
 
*pathName* **xview**

 Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the entry's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the **-xscrollcommand** option. 


*pathName* **xview** *index*

 Adjusts the view in the window so that the character given by *index* is displayed at the left edge of the window. 


*pathName* **xview moveto** *fraction*

 Adjusts the view in the window so that the character *fraction* of the way through the text appears at the left edge of the window. *Fraction* must be a fraction between 0 and 1. 


*pathName* **xview scroll** *number what*

 This command shifts the view in the window left or right according to *number* and *what*. *Number* must be an integer. *What* must be either **units** or **pages**. If *what* is **units**, the view adjusts left or right by *number* average-width characters on the display; if it is **pages** then the view adjusts by *number* screenfuls. If *number* is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. 



  The entry widget also supports the following generic **[ttk::widget](ttk_widget.htm)** widget subcommands (see *ttk::widget(n)* for details): 




|  |  |  |
| --- | --- | --- |
| **cget** | **configure** | **identify** |
| **instate** | **state** |

 Validation
----------

 The **-validate**, **-validatecommand**, and **-invalidcommand** options are used to enable entry widget validation. ### Validation modes

 There are two main validation modes: *prevalidation*, in which the **-validatecommand** is evaluated prior to each edit and the return value is used to determine whether to accept or reject the change; and *revalidation*, in which the **-validatecommand** is evaluated to determine whether the current value is valid.  The **-validate** option determines when validation occurs; it may be set to any of the following values: 


 **none**
 Default. This means validation will only occur when specifically requested by the **validate** widget command. 

**key**
 The entry will be prevalidated prior to each edit (specifically, whenever the **insert** or **delete** widget commands are called). If prevalidation fails, the edit is rejected. 

**focus**
 The entry is revalidated when the entry receives or loses focus. 

**focusin**
 The entry is revalidated when the entry receives focus. 

**focusout**
 The entry is revalidated when the entry loses focus. 

**all**
 Validation is performed for all above conditions. 

  The **-invalidcommand** is evaluated whenever the **-validatecommand** returns a false value. 


 The **-validatecommand** and **-invalidcommand** may modify the entry widget's value via the widget **insert** or **delete** commands, or by setting the linked **-textvariable**. If either does so during prevalidation, then the edit is rejected regardless of the value returned by the **-validatecommand**. 


 If **-validatecommand** is empty (the default), validation always succeeds. 


### Validation script substitutions

 It is possible to perform percent substitutions on the **-validatecommand** and **-invalidcommand**, just as in a **[bind](bind.htm)** script. The following substitutions are recognized: 
 **%d**
 Type of action: 1 for **insert** prevalidation, 0 for **delete** prevalidation, or -1 for revalidation. 

**%i**
 Index of character string to be inserted/deleted, if any, otherwise -1. 

**%P**
 In prevalidation, the new value of the entry if the edit is accepted. In revalidation, the current value of the entry. 

**%s**
 The current value of entry prior to editing. 

**%S**
 The text string being inserted/deleted, if any, {} otherwise. 

**%v**
 The current value of the **-validate** option. 

**%V**
 The validation condition that triggered the callback (**key**, **focusin**, **focusout**, or **forced**). 

**%W**
 The name of the entry widget. 

 ### Differences from tk entry widget validation

 The standard Tk entry widget automatically disables validation (by setting **-validate** to **none**) if the **-validatecommand** or **-invalidcommand** modifies the entry's value. The Tk themed entry widget only disables validation if one of the validation scripts raises an error, or if **-validatecommand** does not return a valid boolean value. (Thus, it is not necessary to re-enable validation after modifying the entry value in a validation script).  In addition, the standard entry widget invokes validation whenever the linked **-textvariable** is modified; the Tk themed entry widget does not. 


Default bindings
----------------

 The entry widget's default bindings enable the following behavior. In the descriptions below, “word” refers to a contiguous group of letters, digits, or “\_” characters, or any single character other than these. 
* Clicking mouse button 1 positions the insert cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 down strokes out a selection between the insert cursor and the character under the mouse.
* Double-clicking with mouse button 1 selects the word under the mouse and positions the insert cursor at the end of the word. Dragging after a double click strokes out a selection consisting of whole words.
* Triple-clicking with mouse button 1 selects all of the text in the entry and positions the insert cursor at the end of the line.
* The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down. If the button is double-clicked before dragging then the selection will be adjusted in units of whole words.
* Clicking mouse button 1 with the Control key down will position the insert cursor in the entry without affecting the selection.
* If any normal printing characters are typed in an entry, they are inserted at the point of the insert cursor.
* The view in the entry can be adjusted by dragging with mouse button 2. If mouse button 2 is clicked without moving the mouse, the selection is copied into the entry at the position of the mouse cursor.
* If the mouse is dragged out of the entry on the left or right sides while button 1 is pressed, the entry will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window).
* The Left and Right keys move the insert cursor one character to the left or right; they also clear any selection in the entry. If Left or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Left and Control-Right move the insert cursor by words, and Control-Shift-Left and Control-Shift-Right move the insert cursor by words and also extend the selection. Control-b and Control-f behave the same as Left and Right, respectively.
* The Home key and Control-a move the insert cursor to the beginning of the entry and clear any selection in the entry. Shift-Home moves the insert cursor to the beginning of the entry and extends the selection to that point.
* The End key and Control-e move the insert cursor to the end of the entry and clear any selection in the entry. Shift-End moves the cursor to the end and extends the selection to that point.
* Control-/ selects all the text in the entry.
* Control-\ clears any selection in the entry.
* The standard Tk <<Cut>>, <<Copy>>, <<Paste>>, and <<Clear>> virtual events operate on the selection in the expected manner.
* The Delete key deletes the selection, if there is one in the entry. If there is no selection, it deletes the character to the right of the insert cursor.
* The BackSpace key and Control-h delete the selection, if there is one in the entry. If there is no selection, it deletes the character to the left of the insert cursor.
* Control-d deletes the character to the right of the insert cursor.
* Control-k deletes all the characters to the right of the insertion cursor.

 Widget states
-------------

 In the **disabled** state, the entry cannot be edited and the text cannot be selected. In the **readonly** state, no insert cursor is displayed and the entry cannot be edited (specifically: the **insert** and **delete** commands have no effect). The **disabled** state is the same as **readonly**, and in addition text cannot be selected.  Note that changes to the linked **-textvariable** will still be reflected in the entry, even if it is disabled or readonly. 


 Typically, the text is “grayed-out” in the **disabled** state, and a different background is used in the **readonly** state. 


 The entry widget sets the **invalid** state if revalidation fails, and clears it whenever validation succeeds. 


See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[entry](entry.htm)** Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 1998-2000 Scriptics Corporation.  
 Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_entry.htm>

ttk\_label
==========

  
[NAME](ttk_label.htm#M2) ttk::label — Display a text string and/or image 
[SYNOPSIS](ttk_label.htm#M3) 
[DESCRIPTION](ttk_label.htm#M4) 
[STANDARD OPTIONS](ttk_label.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-compound, compound, Compound](ttk_widget.htm#M-compound) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-image, image, Image](ttk_widget.htm#M-image) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 
[-text, text, Text](ttk_widget.htm#M-text) 
[-textvariable, textVariable, Variable](ttk_widget.htm#M-textvariable) 
[-underline, underline, Underline](ttk_widget.htm#M-underline) 
[-width, width, Width](ttk_widget.htm#M-width) 









 
[WIDGET-SPECIFIC OPTIONS](ttk_label.htm#M6)  
[-anchor, anchor, Anchor](ttk_label.htm#M7) 
[-background, frameColor, FrameColor](ttk_label.htm#M8) 
[-font, font, Font](ttk_label.htm#M9) 
[-foreground, textColor, TextColor](ttk_label.htm#M10) 
[-justify, justify, Justify](ttk_label.htm#M11) 
[-padding, padding, Padding](ttk_label.htm#M12) 
[-relief, relief, Relief](ttk_label.htm#M13) 
[-text, text, Text](ttk_label.htm#M14) 
[-wraplength, wrapLength, WrapLength](ttk_label.htm#M15) 








 
[WIDGET COMMAND](ttk_label.htm#M16) 
[SEE ALSO](ttk_label.htm#M17) 






 Name
----

 ttk::label — Display a text string and/or image Synopsis
--------

 **ttk::label** *pathName* ?*options*?  
 Description
-----------

 A **ttk::label** widget displays a textual label and/or image. The label may be linked to a Tcl variable to automatically change the displayed text. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-compound, compound, Compound](ttk_widget.htm#M-compound)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-image, image, Image](ttk_widget.htm#M-image)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 
**[-text, text, Text](ttk_widget.htm#M-text)** 
**[-textvariable, textVariable, Variable](ttk_widget.htm#M-textvariable)** 
**[-underline, underline, Underline](ttk_widget.htm#M-underline)** 
**[-width, width, Width](ttk_widget.htm#M-width)** 









 Widget-specific options
-----------------------

  Command-Line Name: **-anchor** Database Name: **anchor** Database Class: **Anchor** 


Specifies how the information in the widget is positioned relative to the inner margins. Legal values are **n**, **ne**, **e**, **se**, **s**, **sw**, **w**, **nw**, and **center**. See also **-justify**. 

Command-Line Name: **-background** Database Name: **frameColor** Database Class: **FrameColor** 


The widget's background color. If unspecified, the theme default is used. 

Command-Line Name: **-font** Database Name: **font** Database Class: **Font** 


Font to use for label text. 

Command-Line Name: **-foreground** Database Name: **textColor** Database Class: **TextColor** 


The widget's foreground color. If unspecified, the theme default is used. 

Command-Line Name: **-justify** Database Name: **justify** Database Class: **Justify** 


If there are multiple lines of text, specifies how the lines are laid out relative to one another. One of **left**, **center**, or **right**. See also **-anchor**. 

Command-Line Name: **-padding** Database Name: **padding** Database Class: **Padding** 


Specifies the amount of extra space to allocate for the widget. The padding is a list of up to four length specifications *left top right bottom*. If fewer than four elements are specified, *bottom* defaults to *top*, *right* defaults to *left*, and *top* defaults to *left*. 

Command-Line Name: **-relief** Database Name: **relief** Database Class: **Relief** 


Specifies the 3-D effect desired for the widget border. Valid values are **flat**, **groove**, **raised**, **ridge**, **solid**, and **sunken**. 

Command-Line Name: **-text** Database Name: **text** Database Class: **Text** 


Specifies a text string to be displayed inside the widget (unless overridden by **-textvariable**). 

Command-Line Name: **-wraplength** Database Name: **wrapLength** Database Class: **WrapLength** 


Specifies the maximum line length (in pixels). If this option is less than or equal to zero, then automatic wrapping is not performed; otherwise the text is split into lines such that no line is longer than the specified value. 
 Widget command
--------------

 Supports the standard widget commands **configure**, **cget**, **identify**, **instate**, and **state**; see *ttk::widget(n)*. See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[label](label.htm)** Copyright © 2004 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_label.htm>

loadTk
======

 Name
----

 safe::loadTk — Load Tk into a safe interpreter. Synopsis
--------

 **safe::loadTk** *slave* ?**-use** *windowId*? ?**-display** *displayName*?  
 Description
-----------

 Safe Tk is based on Safe Tcl, which provides a mechanism that allows restricted and mediated access to auto-loading and packages for safe interpreters. Safe Tk adds the ability to configure the interpreter for safe Tk operations and load Tk into safe interpreters.  The **safe::loadTk** command initializes the required data structures in the named safe interpreter and then loads Tk into it. The interpreter must have been created with **safe::interpCreate** or have been initialized with **safe::interpInit**. The command returns the name of the safe interpreter. If **-use** is specified, the window identified by the specified system dependent identifier *windowId* is used to contain the “.” window of the safe interpreter; it can be any valid id, eventually referencing a window belonging to another application. As a convenience, if the window you plan to use is a Tk Window of the application you can use the window name (e.g., “**.x.y**”) instead of its window Id (e.g., from **[winfo id](winfo.htm)** **.x.y**). When **-use** is not specified, a new toplevel window is created for the “.” window of the safe interpreter. On X11 if you want the embedded window to use another display than the default one, specify it with **-display**. See the **[SECURITY ISSUES](#M5)** section below for implementation details. 


Security issues
---------------

 Please read the **[safe](../tclcmd/safe.htm)** manual page for Tcl to learn about the basic security considerations for Safe Tcl.  **safe::loadTk** adds the value of **[tk\_library](tkvars.htm)** taken from the master interpreter to the virtual access path of the safe interpreter so that auto-loading will work in the safe interpreter. 


 Tk initialization is now safe with respect to not trusting the slave's state for startup. **safe::loadTk** registers the slave's name so when the Tk initialization (**[Tk\_SafeInit](https://www.tcl.tk/man/tcl/TkLib/Tk_Init.htm)**) is called and in turn calls the master's **safe::InitTk** it will return the desired **[argv](../tclcmd/tclvars.htm)** equivalent (**-use** *windowId*, correct **-display**, etc.) 


 When **-use** is not used, the new toplevel created is specially decorated so the user is always aware that the user interface presented comes from a potentially unsafe code and can easily delete the corresponding interpreter. 


 On X11, conflicting **-use** and **-display** are likely to generate a fatal X error. 


See also
--------

 **[safe](../tclcmd/safe.htm)**, **[interp](../tclcmd/interp.htm)**, **[library](../tclcmd/library.htm)**, **[load](../tclcmd/load.htm)**, **[package](../tclcmd/package.htm)**, **[source](../tclcmd/source.htm)**, **[unknown](../tclcmd/unknown.htm)** [safe interpreter](#), Copyright © 1995-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/loadTk.htm>

messageBox
==========

  
[NAME](messagebox.htm#M2) tk\_messageBox — pops up a message window and waits for user response. 
[SYNOPSIS](messagebox.htm#M3) 
[DESCRIPTION](messagebox.htm#M4)  
[**-default** *name*](messagebox.htm#M5) 
[**-detail** *string*](messagebox.htm#M6) 
[**-icon** *iconImage*](messagebox.htm#M7) 
[**-message** *string*](messagebox.htm#M8) 
[**-parent** *window*](messagebox.htm#M9) 
[**-title** *titleString*](messagebox.htm#M10) 
[**-type** *predefinedType*](messagebox.htm#M11)  
[**abortretryignore**](messagebox.htm#M12) 
[**ok**](messagebox.htm#M13) 
[**okcancel**](messagebox.htm#M14) 
[**retrycancel**](messagebox.htm#M15) 
[**yesno**](messagebox.htm#M16) 
[**yesnocancel**](messagebox.htm#M17) 





 






 
[EXAMPLE](messagebox.htm#M18) 
[KEYWORDS](messagebox.htm#M19) 




 Name
----

 tk\_messageBox — pops up a message window and waits for user response. Synopsis
--------

 **tk\_messageBox** ?*option value ...*?  
 Description
-----------

 This procedure creates and displays a message window with an application-specified message, an icon and a set of buttons. Each of the buttons in the message window is identified by a unique symbolic name (see the **-type** options). After the message window is popped up, **tk\_messageBox** waits for the user to select one of the buttons. Then it returns the symbolic name of the selected button.  The following option-value pairs are supported: 


 
**-default** *name*

 *Name* gives the symbolic name of the default button for this message window ( “ok”, “cancel”, and so on). See **-type** for a list of the symbolic names. If this option is not specified, the first button in the dialog will be made the default. 


**-detail** *string*

 Specifies an auxiliary message to the main message given by the **-message** option. The message detail will be presented beneath the main message and, where supported by the OS, in a less emphasized font than the main message. 


**-icon** *iconImage*

 Specifies an icon to display. *IconImage* must be one of the following: **error**, **info**, **question** or **warning**. If this option is not specified, then the info icon will be displayed. 


**-message** *string*

 Specifies the message to display in this message box. The default value is an empty string. 


**-parent** *window*

 Makes *window* the logical parent of the message box. The message box is displayed on top of its parent window. 


**-title** *titleString*

 Specifies a string to display as the title of the message box. This option is ignored on Mac OS X, where platform guidelines forbid the use of a title on this kind of dialog. 


**-type** *predefinedType*

 Arranges for a predefined set of buttons to be displayed. The following values are possible for *predefinedType*: 
 **abortretryignore**
 Displays three buttons whose symbolic names are **abort**, **retry** and **ignore**. 

**ok**
 Displays one button whose symbolic name is **ok**. 

**okcancel**
 Displays two buttons whose symbolic names are **ok** and **cancel**. 

**retrycancel**
 Displays two buttons whose symbolic names are **retry** and **cancel**. 

**yesno**
 Displays two buttons whose symbolic names are **yes** and **no**. 

**yesnocancel**
 Displays three buttons whose symbolic names are **yes**, **no** and **cancel**. 




Example
-------

 
```
set answer [**tk\_messageBox** -message "Really quit?" \
        -icon question -type yesno \
        -detail "Select \"Yes\" to make the application exit"]
switch -- $answer {
    yes exit
    no {**tk\_messageBox** -message "I know you like this application!" \
            -type ok}
}
```
 Copyright © 1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/messageBox.htm>

ttk\_labelframe
===============

  
[NAME](ttk_labelframe.htm#M2) ttk::labelframe — Container widget with optional label 
[SYNOPSIS](ttk_labelframe.htm#M3) 
[DESCRIPTION](ttk_labelframe.htm#M4) 
[STANDARD OPTIONS](ttk_labelframe.htm#M5)  
[-class, undefined, undefined](ttk_widget.htm#M-class) 
[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor) 
[-style, style, Style](ttk_widget.htm#M-style) 
[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus) 



 
[WIDGET-SPECIFIC OPTIONS](ttk_labelframe.htm#M6)  
[-labelanchor, labelAnchor, LabelAnchor](ttk_labelframe.htm#M7) 
[-text, text, Text](ttk_labelframe.htm#M8) 
[-underline, underline, Underline](ttk_labelframe.htm#M9) 
[-padding, padding, Padding](ttk_labelframe.htm#M10) 
[-labelwidget, labelWidget, LabelWidget](ttk_labelframe.htm#M11) 
[-width, width, Width](ttk_labelframe.htm#M12) 
[-height, height, Height](ttk_labelframe.htm#M13) 






 
[WIDGET COMMAND](ttk_labelframe.htm#M14) 
[SEE ALSO](ttk_labelframe.htm#M15) 
[KEYWORDS](ttk_labelframe.htm#M16) 







 Name
----

 ttk::labelframe — Container widget with optional label Synopsis
--------

 **ttk::labelframe** *pathName* ?*options*?  
 Description
-----------

 A **ttk::labelframe** widget is a container used to group other widgets together. It has an optional label, which may be a plain text string or another widget. Standard options
----------------

  
**[-class, undefined, undefined](ttk_widget.htm#M-class)** 
**[-cursor, cursor, Cursor](ttk_widget.htm#M-cursor)** 
**[-style, style, Style](ttk_widget.htm#M-style)** 
**[-takefocus, takeFocus, TakeFocus](ttk_widget.htm#M-takefocus)** 



 Widget-specific options
-----------------------

  Command-Line Name: **-labelanchor** Database Name: **labelAnchor** Database Class: **LabelAnchor** 


Specifies where to place the label. Allowed values are (clockwise from the top upper left corner): **nw**, **n**, **ne**, **en**, **e**, **es**, **se**, **s**,**sw**, **ws**, **w** and **wn**. The default value is theme-dependent. 

Command-Line Name: **-text** Database Name: **text** Database Class: **Text** 


Specifies the text of the label. 

Command-Line Name: **-underline** Database Name: **underline** Database Class: **Underline** 


If set, specifies the integer index (0-based) of a character to underline in the text string. The underlined character is used for mnemonic activation. Mnemonic activation for a **ttk::labelframe** sets the keyboard focus to the first child of the **ttk::labelframe** widget. 

Command-Line Name: **-padding** Database Name: **padding** Database Class: **Padding** 


Additional padding to include inside the border. 

Command-Line Name: **-labelwidget** Database Name: **labelWidget** Database Class: **LabelWidget** 


The name of a widget to use for the label. If set, overrides the **-text** option. The **-labelwidget** must be a child of the **[labelframe](labelframe.htm)** widget or one of the **[labelframe](labelframe.htm)**'s ancestors, and must belong to the same top-level widget as the **[labelframe](labelframe.htm)**. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


If specified, the widget's requested width in pixels. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


If specified, the widget's requested height in pixels. (See *ttk::frame(n)* for further notes on **-width** and **-height**). 
 Widget command
--------------

 Supports the standard widget commands **configure**, **cget**, **identify**, **instate**, and **state**; see *ttk::widget(n)*. See also
--------

 **[ttk::widget](ttk_widget.htm)**, **[ttk::frame](ttk_frame.htm)**, **[labelframe](labelframe.htm)** Copyright © 2005 Joe English 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/ttk_labelframe.htm>

append
======

 Name
----

 append — Append to variable Synopsis
--------

 **append** *varName* ?*value value value ...*?  
 Description
-----------

 Append all of the *value* arguments to the current value of variable *varName*. If *varName* does not exist, it is given a value equal to the concatenation of all the *value* arguments. The result of this command is the new value stored in variable *varName*. This command provides an efficient way to build up long variables incrementally. For example, “**append a $b**” is much more efficient than “**set a $a$b**” if **$a** is long. Example
-------

 Building a string of comma-separated numbers piecemeal using a loop. 

```
set var 0
for {set i 1} {$i<=10} {incr i} {
    **append** var "," $i
}
puts $var
# Prints 0,1,2,3,4,5,6,7,8,9,10
```
 See also
--------

 **[concat](concat.htm)**, **[lappend](lappend.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/append.htm>

radiobutton
===========

  
[NAME](radiobutton.htm#M2) radiobutton — Create and manipulate 'radiobutton' pick-one widgets 
[SYNOPSIS](radiobutton.htm#M3) 
[STANDARD OPTIONS](radiobutton.htm#M4)  
[-activebackground, activeBackground, Foreground](options.htm#M-activebackground) 
[-activeforeground, activeForeground, Background](options.htm#M-activeforeground) 
[-anchor, anchor, Anchor](options.htm#M-anchor) 
[-background or -bg, background, Background](options.htm#M-background) 
[-bitmap, bitmap, Bitmap](options.htm#M-bitmap) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-compound, compound, Compound](options.htm#M-compound) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-image, image, Image](options.htm#M-image) 
[-justify, justify, Justify](options.htm#M-justify) 
[-padx, padX, Pad](options.htm#M-padx) 
[-pady, padY, Pad](options.htm#M-pady) 
[-relief, relief, Relief](options.htm#M-relief) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-text, text, Text](options.htm#M-text) 
[-textvariable, textVariable, Variable](options.htm#M-textvariable) 
[-underline, underline, Underline](options.htm#M-underline) 
[-wraplength, wrapLength, WrapLength](options.htm#M-wraplength) 























 
[WIDGET-SPECIFIC OPTIONS](radiobutton.htm#M5)  
[-command, command, Command](radiobutton.htm#M6) 
[-height, height, Height](radiobutton.htm#M7) 
[-indicatoron, indicatorOn, IndicatorOn](radiobutton.htm#M8) 
[-selectcolor, selectColor, Background](radiobutton.htm#M9) 
[-offrelief, offRelief, OffRelief](radiobutton.htm#M10) 
[-overrelief, overRelief, OverRelief](radiobutton.htm#M11) 
[-selectimage, selectImage, SelectImage](radiobutton.htm#M12) 
[-state, state, State](radiobutton.htm#M13) 
[-tristateimage, tristateImage, TristateImage](radiobutton.htm#M14) 
[-tristatevalue, tristateValue, Value](radiobutton.htm#M15) 
[-value, value, Value](radiobutton.htm#M16) 
[-variable, variable, Variable](radiobutton.htm#M17) 
[-width, width, Width](radiobutton.htm#M18) 












 
[DESCRIPTION](radiobutton.htm#M19) 
[WIDGET COMMAND](radiobutton.htm#M20)  
[*pathName* **cget** *option*](radiobutton.htm#M21) 
[*pathName* **configure** ?*option*? ?*value option value ...*?](radiobutton.htm#M22) 
[*pathName* **deselect**](radiobutton.htm#M23) 
[*pathName* **flash**](radiobutton.htm#M24) 
[*pathName* **invoke**](radiobutton.htm#M25) 
[*pathName* **select**](radiobutton.htm#M26) 





 
[BINDINGS](radiobutton.htm#M27) 
[SEE ALSO](radiobutton.htm#M28) 
[KEYWORDS](radiobutton.htm#M29) 








 Name
----

 radiobutton — Create and manipulate 'radiobutton' pick-one widgets Synopsis
--------

 **radiobutton** *pathName* ?*options*?  
 Standard options
----------------

  
**[-activebackground, activeBackground, Foreground](options.htm#M-activebackground)** 
**[-activeforeground, activeForeground, Background](options.htm#M-activeforeground)** 
**[-anchor, anchor, Anchor](options.htm#M-anchor)** 
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-bitmap, bitmap, Bitmap](options.htm#M-bitmap)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-compound, compound, Compound](options.htm#M-compound)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-disabledforeground, disabledForeground, DisabledForeground](options.htm#M-disabledforeground)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-image, image, Image](options.htm#M-image)** 
**[-justify, justify, Justify](options.htm#M-justify)** 
**[-padx, padX, Pad](options.htm#M-padx)** 
**[-pady, padY, Pad](options.htm#M-pady)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-text, text, Text](options.htm#M-text)** 
**[-textvariable, textVariable, Variable](options.htm#M-textvariable)** 
**[-underline, underline, Underline](options.htm#M-underline)** 
**[-wraplength, wrapLength, WrapLength](options.htm#M-wraplength)** 























 Widget-specific options
-----------------------

  Command-Line Name: **-command** Database Name: **command** Database Class: **Command** 


Specifies a Tcl command to associate with the button. This command is typically invoked when mouse button 1 is released over the button window. The button's global variable (**-variable** option) will be updated before the command is invoked. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies a desired height for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**); for text it is in lines of text. If this option is not specified, the button's desired height is computed from the size of the image or bitmap or text being displayed in it. 

Command-Line Name: **-indicatoron** Database Name: **indicatorOn** Database Class: **IndicatorOn** 


Specifies whether or not the indicator should be drawn. Must be a proper boolean value. If false, the **-relief** option is ignored and the widget's relief is always sunken if the widget is selected and raised otherwise. 

Command-Line Name: **-selectcolor** Database Name: **selectColor** Database Class: **Background** 


Specifies a background color to use when the button is selected. If **-indicatoron** is true then the color applies to the indicator. Under Windows, this color is used as the background for the indicator regardless of the select state. If **-indicatoron** is false, this color is used as the background for the entire widget, in place of **-background** or **-activeBackground**, whenever the widget is selected. If specified as an empty string then no special color is used for displaying when the widget is selected. 

Command-Line Name: **-offrelief** Database Name: **offRelief** Database Class: **OffRelief** 


Specifies the relief for the checkbutton when the indicator is not drawn and the checkbutton is off. The default value is “raised”. By setting this option to “flat” and setting **-indicatoron** to false and **-overrelief** to “raised”, the effect is achieved of having a flat button that raises on mouse-over and which is depressed when activated. This is the behavior typically exhibited by the Align-Left, Align-Right, and Center radiobuttons on the toolbar of a word-processor, for example. 

Command-Line Name: **-overrelief** Database Name: **overRelief** Database Class: **OverRelief** 


Specifies an alternative relief for the radiobutton, to be used when the mouse cursor is over the widget. This option can be used to make toolbar buttons, by configuring **-relief flat -overrelief raised**. If the value of this option is the empty string, then no alternative relief is used when the mouse cursor is over the radiobutton. The empty string is the default value. 

Command-Line Name: **-selectimage** Database Name: **selectImage** Database Class: **SelectImage** 


Specifies an image to display (in place of the **-image** option) when the radiobutton is selected. This option is ignored unless the **-image** option has been specified. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Specifies one of three states for the radiobutton: **normal**, **active**, or **disabled**. In normal state the radiobutton is displayed using the **-foreground** and **-background** options. The active state is typically used when the pointer is over the radiobutton. In active state the radiobutton is displayed using the **-activeforeground** and **-activebackground** options. Disabled state means that the radiobutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the **-disabledforeground** and **-background** options determine how the radiobutton is displayed. 

Command-Line Name: **-tristateimage** Database Name: **tristateImage** Database Class: **TristateImage** 


Specifies an image to display (in place of the **-image** option) when the radiobutton is selected. This option is ignored unless the **-image** option has been specified. 

Command-Line Name: **-tristatevalue** Database Name: **tristateValue** Database Class: **Value** 


Specifies the value that causes the radiobutton to display the multi-value selection, also known as the tri-state mode. Defaults to “”. 

Command-Line Name: **-value** Database Name: **value** Database Class: **Value** 


Specifies value to store in the button's associated variable whenever this button is selected. 

Command-Line Name: **-variable** Database Name: **[variable](../tclcmd/variable.htm)** Database Class: **[Variable](../tclcmd/variable.htm)** 


Specifies the name of a global variable to set whenever this button is selected. Changes in this variable also cause the button to select or deselect itself. Defaults to the value **selectedButton**. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies a desired width for the button. If an image or bitmap is being displayed in the button, the value is in screen units (i.e. any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**); for text it is in characters. If this option is not specified, the button's desired width is computed from the size of the image or bitmap or text being displayed in it. 
 Description
-----------

 The **radiobutton** command creates a new window (given by the *pathName* argument) and makes it into a radiobutton widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the radiobutton such as its colors, font, text, and initial relief. The **radiobutton** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  A radiobutton is a widget that displays a textual string, bitmap or image and a diamond or circle called an *indicator*. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the **-wraplength** option) and one of the characters may optionally be underlined using the **-underline** option. A radiobutton has all of the behavior of a simple button: it can display itself in either of three different ways, according to the **-state** option; it can be made to appear raised, sunken, or flat; it can be made to flash; and it invokes a Tcl command whenever mouse button 1 is clicked over the check button. 


 In addition, radiobuttons can be *selected*. If a radiobutton is selected, the indicator is normally drawn with a selected appearance, and a Tcl variable associated with the radiobutton is set to a particular value (normally 1). Under Unix, the indicator is drawn with a sunken relief and a special color. Under Windows, the indicator is drawn with a round mark inside. If the radiobutton is not selected, then the indicator is drawn with a deselected appearance, and the associated variable is set to a different value (typically 0). The indicator is drawn without a round mark inside. Typically, several radiobuttons share a single variable and the value of the variable indicates which radiobutton is to be selected. When a radiobutton is selected it sets the value of the variable to indicate that fact; each radiobutton also monitors the value of the variable and automatically selects and deselects itself when the variable's value changes. If the variable's value matches the **-tristatevalue**, then the radiobutton is drawn using the tri-state mode. This mode is used to indicate mixed or multiple values. (This is used when the radiobutton represents the state of multiple items.) By default the variable **selectedButton** is used; its contents give the name of the button that is selected, or the empty string if no button associated with that variable is selected. The name of the variable for a radiobutton, plus the variable to be stored into it, may be modified with options on the command line or in the option database. Configuration options may also be used to modify the way the indicator is displayed (or whether it is displayed at all). By default a radiobutton is configured to select itself on button clicks. 


Widget command
--------------

 The **radiobutton** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for radiobutton widgets: 
 
*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **radiobutton** command. 


*pathName* **configure** ?*option*? ?*value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **radiobutton** command. 


*pathName* **deselect**

 Deselects the radiobutton and sets the associated variable to an empty string. If this radiobutton was not currently selected, the command has no effect. 


*pathName* **flash**

 Flashes the radiobutton. This is accomplished by redisplaying the radiobutton several times, alternating between active and normal colors. At the end of the flash the radiobutton is left in the same normal/active state as when the command was invoked. This command is ignored if the radiobutton's state is **disabled**. 


*pathName* **invoke**

 Does just what would have happened if the user invoked the radiobutton with the mouse: selects the button and invokes its associated Tcl command, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the radiobutton. This command is ignored if the radiobutton's state is **disabled**. 


*pathName* **select**

 Selects the radiobutton and sets the associated variable to the value corresponding to this widget. 

 Bindings
--------

 Tk automatically creates class bindings for radiobuttons that give them the following default behavior: 
1. On Unix systems, a radiobutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves the radiobutton. On Mac and Windows systems, when mouse button 1 is pressed over a radiobutton, the button activates whenever the mouse pointer is inside the button, and deactivates whenever the mouse pointer leaves the button.
2. When mouse button 1 is pressed over a radiobutton it is invoked (it becomes selected and the command associated with the button is invoked, if there is one).
3. When a radiobutton has the input focus, the space key causes the radiobutton to be invoked.

  If the radiobutton's state is **disabled** then none of the above actions occur: the radiobutton is completely non-responsive. 


 The behavior of radiobuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. 


See also
--------

 **[checkbutton](checkbutton.htm)**, **[labelframe](labelframe.htm)**, **[listbox](listbox.htm)**, **[options](options.htm)**, **[scale](scale.htm)**, **[ttk::radiobutton](ttk_radiobutton.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/radiobutton.htm>

after
=====

  
[NAME](after.htm#M2) after — Execute a command after a time delay 
[SYNOPSIS](after.htm#M3) 
[DESCRIPTION](after.htm#M4)  
[**after** *ms*](after.htm#M5) 
[**after** *ms* ?*script script script ...*?](after.htm#M6) 
[**after cancel** *id*](after.htm#M7) 
[**after cancel** *script script ...*](after.htm#M8) 
[**after idle** *script* ?*script script ...*?](after.htm#M9) 
[**after info** ?*id*?](after.htm#M10) 





 
[EXAMPLES](after.htm#M11) 
[SEE ALSO](after.htm#M12) 
[KEYWORDS](after.htm#M13) 





 Name
----

 after — Execute a command after a time delay Synopsis
--------

 **after** *ms*  
 **after** *ms* ?*script script script ...*?  
 **after cancel** *id*  
 **after cancel** *script script script ...*  
 **after idle** ?*script script script ...*?  
 **after info** ?*id*?  
 Description
-----------

 This command is used to delay execution of the program or to execute a command in background sometime in the future. It has several forms, depending on the first argument to the command: 
 
**after** *ms*

 *Ms* must be an integer giving a time in milliseconds. The command sleeps for *ms* milliseconds and then returns. While the command is sleeping the application does not respond to events. 


**after** *ms* ?*script script script ...*?
 In this form the command returns immediately, but it arranges for a Tcl command to be executed *ms* milliseconds later as an event handler. The command will be executed exactly once, at the given time. The delayed command is formed by concatenating all the *script* arguments in the same fashion as the **[concat](concat.htm)** command. The command will be executed at global level (outside the context of any Tcl procedure). If an error occurs while executing the delayed command then the background error will be reported by the command registered with **[interp bgerror](interp.htm)**. The **after** command returns an identifier that can be used to cancel the delayed command using **after cancel**. 


**after cancel** *id*

 Cancels the execution of a delayed command that was previously scheduled. *Id* indicates which command should be canceled; it must have been the return value from a previous **after** command. If the command given by *id* has already been executed then the **after cancel** command has no effect. 


**after cancel** *script script ...*

 This command also cancels the execution of a delayed command. The *script* arguments are concatenated together with space separators (just as in the **[concat](concat.htm)** command). If there is a pending command that matches the string, it is canceled and will never be executed; if no such command is currently pending then the **after cancel** command has no effect. 


**after idle** *script* ?*script script ...*?
 Concatenates the *script* arguments together with space separators (just as in the **[concat](concat.htm)** command), and arranges for the resulting script to be evaluated later as an idle callback. The script will be run exactly once, the next time the event loop is entered and there are no events to process. The command returns an identifier that can be used to cancel the delayed command using **after cancel**. If an error occurs while executing the script then the background error will be reported by the command registered with **[interp bgerror](interp.htm)**. 


**after info** ?*id*?
 This command returns information about existing event handlers. If no *id* argument is supplied, the command returns a list of the identifiers for all existing event handlers created by the **after** command for this interpreter. If *id* is supplied, it specifies an existing handler; *id* must have been the return value from some previous call to **after** and it must not have triggered yet or been canceled. In this case the command returns a list with two elements. The first element of the list is the script associated with *id*, and the second element is either **idle** or **timer** to indicate what kind of event handler it is. 

  The **after** *ms* and **after idle** forms of the command assume that the application is event driven: the delayed commands will not be executed unless the application enters the event loop. In applications that are not normally event-driven, such as **[tclsh](../usercmd/tclsh.htm)**, the event loop can be entered with the **[vwait](vwait.htm)** and **[update](update.htm)** commands. 


Examples
--------

 This defines a command to make Tcl do nothing at all for *N* seconds: 

```
proc sleep {N} {
    **after** [expr {int($N * 1000)}]
}
```
  This arranges for the command *wake\_up* to be run in eight hours (providing the event loop is active at that time): 



```
**after** [expr {1000 * 60 * 60 * 8}] wake_up
```
  The following command can be used to do long-running calculations (as represented here by *::my\_calc::one\_step*, which is assumed to return a boolean indicating whether another step should be performed) in a step-by-step fashion, though the calculation itself needs to be arranged so it can work step-wise. This technique is extra careful to ensure that the event loop is not starved by the rescheduling of processing steps (arranging for the next step to be done using an already-triggered timer event only when the event queue has been drained) and is useful when you want to ensure that a Tk GUI remains responsive during a slow task. 



```
proc doOneStep {} {
    if {[::my_calc::one_step]} {
        **after idle** [list **after** 0 doOneStep]
    }
}
doOneStep
```
 See also
--------

 **[concat](concat.htm)**, **[interp](interp.htm)**, **[update](update.htm)**, **[vwait](vwait.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/after.htm>

lrange
======

 Name
----

 lrange — Return one or more adjacent elements from a list Synopsis
--------

 **lrange** *list first last*  
 Description
-----------

 *List* must be a valid Tcl list. This command will return a new list consisting of elements *first* through *last*, inclusive. The index values *first* and *last* are interpreted the same as index values for the command **[string index](string.htm)**, supporting simple index arithmetic and indices relative to the end of the list. If *first* is less than zero, it is treated as if it were zero. If *last* is greater than or equal to the number of elements in the list, then it is treated as if it were **end**. If *first* is greater than *last* then an empty string is returned. Note: “**lrange** *list first first*” does not always produce the same result as “**lindex** *list first*” (although it often does for simple fields that are not enclosed in braces); it does, however, produce exactly the same results as “**list [lindex** *list first***]**” Examples
--------

 Selecting the first two elements: 

```
% **lrange** {a b c d e} 0 1
a b
```
  Selecting the last three elements: 



```
% **lrange** {a b c d e} end-2 end
c d e
```
  Selecting everything except the first and last element: 



```
% **lrange** {a b c d e} 1 end-1
b c d
```
  Selecting a single element with **lrange** is not the same as doing so with **[lindex](lindex.htm)**: 



```
% set var {some {elements to} select}
some {elements to} select
% lindex $var 1
elements to
% **lrange** $var 1 1
{elements to}
```
 See also
--------

 **[list](list.htm)**, **[lappend](lappend.htm)**, **[lindex](lindex.htm)**, **[linsert](linsert.htm)**, **[llength](llength.htm)**, **[lsearch](lsearch.htm)**, **[lset](lset.htm)**, **[lreplace](lreplace.htm)**, **[lsort](lsort.htm)**, **[string](string.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2001 Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/lrange.htm>

lrepeat
=======

 Name
----

 lrepeat — Build a list by repeating elements Synopsis
--------

 **lrepeat** *count* ?*element ...*?  
 Description
-----------

 The **lrepeat** command creates a list of size *count \* number of elements* by repeating *count* times the sequence of elements *element ...*. *count* must be a non-negative integer, *element* can be any Tcl value. Note that **lrepeat 1 element ...** is identical to **list element ...**. Examples
--------

 
```
**lrepeat** 3 a
      *→ a a a*
**lrepeat** 3 [**lrepeat** 3 0]
      *→ {0 0 0} {0 0 0} {0 0 0}*
**lrepeat** 3 a b c
      *→ a b c a b c a b c*
**lrepeat** 3 [**lrepeat** 2 a] b c
      *→ {a a} b c {a a} b c {a a} b c*
```
 See also
--------

 **[list](list.htm)**, **[lappend](lappend.htm)**, **[linsert](linsert.htm)**, **[llength](llength.htm)**, **[lset](lset.htm)** Copyright © 2003 by Simon Geard. All rights reserved. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/lrepeat.htm>

load
====

 Name
----

 load — Load machine code and initialize new commands Synopsis
--------

 **load** ?**-global**? ?**-lazy**? ?**--**? *fileName*  
 **load** ?**-global**? ?**-lazy**? ?**--**? *fileName packageName*  
 **load** ?**-global**? ?**-lazy**? ?**--**? *fileName packageName interp*  
 Description
-----------

 This command loads binary code from a file into the application's address space and calls an initialization procedure in the package to incorporate it into an interpreter. *fileName* is the name of the file containing the code; its exact form varies from system to system but on most systems it is a shared library, such as a **.so** file under Solaris or a DLL under Windows. *packageName* is the name of the package, and is used to compute the name of an initialization procedure. *interp* is the path name of the interpreter into which to load the package (see the **[interp](interp.htm)** manual entry for details); if *interp* is omitted, it defaults to the interpreter in which the **load** command was invoked.  Once the file has been loaded into the application's address space, one of two initialization procedures will be invoked in the new code. Typically the initialization procedure will add new commands to a Tcl interpreter. The name of the initialization procedure is determined by *packageName* and whether or not the target interpreter is a safe one. For normal interpreters the name of the initialization procedure will have the form *pkg***\_Init**, where *pkg* is the same as *packageName* except that the first letter is converted to upper case and all other letters are converted to lower case. For example, if *packageName* is **foo** or **FOo**, the initialization procedure's name will be **Foo\_Init**. 


 If the target interpreter is a safe interpreter, then the name of the initialization procedure will be *pkg***\_SafeInit** instead of *pkg***\_Init**. The *pkg***\_SafeInit** function should be written carefully, so that it initializes the safe interpreter only with partial functionality provided by the package that is safe for use by untrusted code. For more information on Safe-Tcl, see the **[safe](safe.htm)** manual entry. 


 The initialization procedure must match the following prototype: 



```
typedef int **Tcl\_PackageInitProc**(
        [Tcl\_Interp](https://www.tcl.tk/man/tcl/TclLib/Interp.htm) **interp*);
```
  The *interp* argument identifies the interpreter in which the package is to be loaded. The initialization procedure must return **[TCL\_OK](catch.htm)** or **[TCL\_ERROR](catch.htm)** to indicate whether or not it completed successfully; in the event of an error it should set the interpreter's result to point to an error message. The result of the **load** command will be the result returned by the initialization procedure. 


 The actual loading of a file will only be done once for each *fileName* in an application. If a given *fileName* is loaded into multiple interpreters, then the first **load** will load the code and call the initialization procedure; subsequent **load**s will call the initialization procedure without loading the code again. For Tcl versions lower than 8.5, it is not possible to unload or reload a package. From version 8.5 however, the **[unload](unload.htm)** command allows the unloading of libraries loaded with **load**, for libraries that are aware of the Tcl's unloading mechanism. 


 The **load** command also supports packages that are statically linked with the application, if those packages have been registered by calling the **[Tcl\_StaticPackage](https://www.tcl.tk/man/tcl/TclLib/StaticPkg.htm)** procedure. If *fileName* is an empty string, then *packageName* must be specified. 


 If *packageName* is omitted or specified as an empty string, Tcl tries to guess the name of the package. This may be done differently on different platforms. The default guess, which is used on most UNIX platforms, is to take the last element of *fileName*, strip off the first three characters if they are **lib**, and use any following alphabetic and underline characters as the module name. For example, the command **load libxyz4.2.so** uses the module name **xyz** and the command **load bin/last.so {}** uses the module name **last**. 


 If *fileName* is an empty string, then *packageName* must be specified. The **load** command first searches for a statically loaded package (one that has been registered by calling the **[Tcl\_StaticPackage](https://www.tcl.tk/man/tcl/TclLib/StaticPkg.htm)** procedure) by that name; if one is found, it is used. Otherwise, the **load** command searches for a dynamically loaded package by that name, and uses it if it is found. If several different files have been **load**ed with different versions of the package, Tcl picks the file that was loaded first. 


 If **-global** is specified preceding the filename, all symbols found in the shared library are exported for global use by other libraries. The option **-lazy** delays the actual loading of symbols until their first actual use. The options may be abbreviated. The option **--** indicates the end of the options, and should be used if you wish to use a filename which starts with **-** and you provide a packageName to the **load** command. 


 On platforms which do not support the **-global** or **-lazy** options, the options still exist but have no effect. Note that use of the **-global** or **-lazy** option may lead to crashes in your application later (in case of symbol conflicts resp. missing symbols), which cannot be detected during the **load**. So, only use this when you know what you are doing, you will not get a nice error message when something is wrong with the loaded library. 


Portability issues
------------------

  **Windows**
 When a load fails with “library not found” error, it is also possible that a dependent library was not found. To see the dependent libraries, type “dumpbin -imports <dllname>” in a DOS console to see what the library must import. When loading a DLL in the current directory, Windows will ignore “./” as a path specifier and use a search heuristic to find the DLL instead. To avoid this, load the DLL with: 

```
**load** [file join [pwd] mylib.DLL]
```


 Bugs
----

 If the same file is **load**ed by different *fileName*s, it will be loaded into the process's address space multiple times. The behavior of this varies from system to system (some systems may detect the redundant loads, others may not). Example
-------

 The following is a minimal extension: 

```
#include <tcl.h>
#include <stdio.h>
static int fooCmd(ClientData clientData,
        [Tcl\_Interp](https://www.tcl.tk/man/tcl/TclLib/Interp.htm) *interp, int objc, [Tcl\_Obj](https://www.tcl.tk/man/tcl/TclLib/Object.htm) *const objv[]) {
    printf("called with %d arguments\n", objc);
    return TCL_OK;
}
int Foo_Init([Tcl\_Interp](https://www.tcl.tk/man/tcl/TclLib/Interp.htm) *interp) {
    if ([Tcl\_InitStubs](https://www.tcl.tk/man/tcl/TclLib/InitStubs.htm)(interp, "8.1", 0) == NULL) {
	return TCL_ERROR;
    }
    printf("creating foo command");
    [Tcl\_CreateObjCommand](https://www.tcl.tk/man/tcl/TclLib/CrtObjCmd.htm)(interp, "foo", fooCmd, NULL, NULL);
    return TCL_OK;
}
```
  When built into a shared/dynamic library with a suitable name (e.g. **foo.dll** on Windows, **libfoo.so** on Solaris and Linux) it can then be loaded into Tcl with the following: 



```
# Load the extension
switch $tcl_platform(platform) {
    windows {
        **load** [file join [pwd] foo.dll]
    }
    unix {
        **load** [file join [pwd] libfoo[info sharedlibextension]]
    }
}

# Now execute the command defined by the extension
foo
```
 See also
--------

 **[info sharedlibextension](info.htm)**, **[package](package.htm)**, **[Tcl\_StaticPackage](https://www.tcl.tk/man/tcl/TclLib/StaticPkg.htm)**, **[safe](safe.htm)** Copyright © 1995-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/load.htm>

read
====

 Name
----

 read — Read from a channel Synopsis
--------

 **read** ?**-nonewline**? *channelId*  
 **read** *channelId numChars*  
 Description
-----------

 In the first form, the **read** command reads all of the data from *channelId* up to the end of the file. If the **-nonewline** switch is specified then the last character of the file is discarded if it is a newline. In the second form, the extra argument specifies how many characters to read. Exactly that many characters will be read and returned, unless there are fewer than *numChars* left in the file; in this case all the remaining characters are returned. If the channel is configured to use a multi-byte encoding, then the number of characters read may not be the same as the number of bytes read.  *ChannelId* must be an identifier for an open channel such as the Tcl standard input channel (**[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**), the return value from an invocation of **[open](open.htm)** or **[socket](socket.htm)**, or the result of a channel creation command provided by a Tcl extension. The channel must have been opened for input. 


 If *channelId* is in nonblocking mode, the command may not read as many characters as requested: once all available input has been read, the command will return the data that is available rather than blocking for more input. If the channel is configured to use a multi-byte encoding, then there may actually be some bytes remaining in the internal buffers that do not form a complete character. These bytes will not be returned until a complete character is available or end-of-file is reached. The **-nonewline** switch is ignored if the command returns before reaching the end of the file. 


 **Read** translates end-of-line sequences in the input into newline characters according to the **-translation** option for the channel. See the **[fconfigure](fconfigure.htm)** manual entry for a discussion on ways in which **[fconfigure](fconfigure.htm)** will alter input. 


Use with serial ports
---------------------

 For most applications a channel connected to a serial port should be configured to be nonblocking: **[fconfigure](fconfigure.htm)** *channelId* **-blocking** *0*. Then **read** behaves much like described above. Care must be taken when using **read** on blocking serial ports: 
 
**read** *channelId numChars*

 In this form **read** blocks until *numChars* have been received from the serial port. 


**read** *channelId*

 In this form **read** blocks until the reception of the end-of-file character, see **[fconfigure](fconfigure.htm)** **-eofchar**. If there no end-of-file character has been configured for the channel, then **read** will block forever. 

 Example
-------

 This example code reads a file all at once, and splits it into a list, with each line in the file corresponding to an element in the list: 

```
set fl [open /proc/meminfo]
set data [**read** $fl]
close $fl
set lines [split $data \n]
```
 See also
--------

 **[file](file.htm)**, **[eof](eof.htm)**, **[fblocked](fblocked.htm)**, **[fconfigure](fconfigure.htm)**, **[Tcl\_StandardChannels](https://www.tcl.tk/man/tcl/TclLib/StdChannels.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/read.htm>

apply
=====

 Name
----

 apply — Apply an anonymous function Synopsis
--------

 **apply** *func* ?*arg1 arg2 ...*?  
 Description
-----------

 The command **apply** applies the function *func* to the arguments *arg1 arg2 ...* and returns the result.  The function *func* is a two element list *{args body}* or a three element list *{args body namespace}* (as if the **[list](list.htm)** command had been used). The first element *args* specifies the formal arguments to *func*. The specification of the formal arguments *args* is shared with the **[proc](proc.htm)** command, and is described in detail in the corresponding manual page. 


 The contents of *body* are executed by the Tcl interpreter after the local variables corresponding to the formal arguments are given the values of the actual parameters *arg1 arg2 ...*. When *body* is being executed, variable names normally refer to local variables, which are created automatically when referenced and deleted when **apply** returns. One local variable is automatically created for each of the function's arguments. Global variables can only be accessed by invoking the **[global](global.htm)** command or the **[upvar](upvar.htm)** command. Namespace variables can only be accessed by invoking the **[variable](variable.htm)** command or the **[upvar](upvar.htm)** command. 


 The invocation of **apply** adds a call frame to Tcl's evaluation stack (the stack of frames accessed via **[uplevel](uplevel.htm)**). The execution of *body* proceeds in this call frame, in the namespace given by *namespace* or in the global namespace if none was specified. If given, *namespace* is interpreted relative to the global namespace even if its name does not start with “::”. 


 The semantics of **apply** can also be described by: 



```
proc apply {fun args} {
    set len [llength $fun]
    if {($len < 2) || ($len > 3)} {
         error "can't interpret \"$fun\" as anonymous function"
    }
    lassign $fun argList body ns
    set name ::$ns::[getGloballyUniqueName]
    set body0 {
         rename [lindex [info level 0] 0] {}
    }
    proc $name $argList ${body0}$body
    set code [catch {uplevel 1 $name $args} res opt]
    return -options $opt $res
}
```
 Examples
--------

 This shows how to make a simple general command that applies a transformation to each element of a list. 

```
proc map {lambda list} {
    set result {}
    foreach item $list {
        lappend result [**apply** $lambda $item]
    }
    return $result
}
map {x {return [string length $x]:$x}} {a bb ccc dddd}
      *→ 1:a 2:bb 3:ccc 4:dddd*
map {x {expr {$x**2 + 3*$x - 2}}} {-4 -3 -2 -1 0 1 2 3 4}
      *→ 2 -2 -4 -4 -2 2 8 16 26*
```
  The **apply** command is also useful for defining callbacks for use in the **[trace](trace.htm)** command: 



```
set vbl "123abc"
trace add variable vbl write {**apply** {{v1 v2 op} {
    upvar 1 $v1 v
    puts "updated variable to \"$v\""
}}}
set vbl 123
set vbl abc
```
 See also
--------

 **[proc](proc.htm)**, **[uplevel](uplevel.htm)** Copyright © 2006 Miguel Sofer  
 Copyright © 2006 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/apply.htm>

lreplace
========

 Name
----

 lreplace — Replace elements in a list with new elements Synopsis
--------

 **lreplace** *list first last* ?*element element ...*?  
 Description
-----------

 **lreplace** returns a new list formed by replacing one or more elements of *list* with the *element* arguments. *first* and *last* are index values specifying the first and last elements of the range to replace. The index values *first* and *last* are interpreted the same as index values for the command **[string index](string.htm)**, supporting simple index arithmetic and indices relative to the end of the list. 0 refers to the first element of the list, and **end** refers to the last element of the list. If *list* is empty, then *first* and *last* are ignored.  If *first* is less than zero, it is considered to refer to before the first element of the list. For non-empty lists, the element indicated by *first* must exist or *first* must indicate before the start of the list. 


 If *last* is less than *first*, then any specified elements will be inserted into the list before the point specified by *first* with no elements being deleted. 


 The *element* arguments specify zero or more new arguments to be added to the list in place of those that were deleted. Each *element* argument will become a separate element of the list. If no *element* arguments are specified, then the elements between *first* and *last* are simply deleted. If *list* is empty, any *element* arguments are added to the end of the list. 


Examples
--------

 Replacing an element of a list with another: 

```
% **lreplace** {a b c d e} 1 1 foo
a foo c d e
```
  Replacing two elements of a list with three: 



```
% **lreplace** {a b c d e} 1 2 three more elements
a three more elements d e
```
  Deleting the last element from a list in a variable: 



```
% set var {a b c d e}
a b c d e
% set var [**lreplace** $var end end]
a b c d
```
  A procedure to delete a given element from a list: 



```
proc lremove {listVariable value} {
    upvar 1 $listVariable var
    set idx [lsearch -exact $var $value]
    set var [**lreplace** $var $idx $idx]
}
```
 See also
--------

 **[list](list.htm)**, **[lappend](lappend.htm)**, **[lindex](lindex.htm)**, **[linsert](linsert.htm)**, **[llength](llength.htm)**, **[lsearch](lsearch.htm)**, **[lset](lset.htm)**, **[lrange](lrange.htm)**, **[lsort](lsort.htm)**, **[string](string.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2001 Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/lreplace.htm>

lreverse
========

 Name
----

 lreverse — Reverse the order of a list Synopsis
--------

 **lreverse** *list*  
 Description
-----------

 The **lreverse** command returns a list that has the same elements as its input list, *list*, except with the elements in the reverse order. Examples
--------

 
```
**lreverse** {a a b c}
      *→ c b a a*
**lreverse** {a b {c d} e f}
      *→ f e {c d} b a*
```
 See also
--------

 **[list](list.htm)**, **[lsearch](lsearch.htm)**, **[lsort](lsort.htm)** Copyright © 2006 by Donal K. Fellows. All rights reserved. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/lreverse.htm>

wm
==

  
[NAME](wm.htm#M2) wm — Communicate with window manager 
[SYNOPSIS](wm.htm#M3) 
[DESCRIPTION](wm.htm#M4)  
[**wm aspect** *window* ?*minNumer minDenom maxNumer maxDenom*?](wm.htm#M5) 
[**wm attributes** *window*](wm.htm#M6) 
[**wm attributes** *window* ?**option**?](wm.htm#M7) 
[**wm attributes** *window* ?**option value option value...**?](wm.htm#M8)  
[**-alpha**](wm.htm#M9) 
[**-fullscreen**](wm.htm#M10) 
[**-topmost**](wm.htm#M11) 


  
[**-disabled**](wm.htm#M12) 
[**-toolwindow**](wm.htm#M13) 
[**-transparentcolor**](wm.htm#M14) 


  
[**-modified**](wm.htm#M15) 
[**-notify**](wm.htm#M16) 
[**-titlepath**](wm.htm#M17) 
[**-transparent**](wm.htm#M18) 



  
[**-type**](wm.htm#M19)  
[**desktop**](wm.htm#M20) 
[**dock**](wm.htm#M21) 
[**toolbar**](wm.htm#M22) 
[**menu**](wm.htm#M23) 
[**utility**](wm.htm#M24) 
[**splash**](wm.htm#M25) 
[**dialog**](wm.htm#M26) 
[**dropdown\_menu**](wm.htm#M27) 
[**popup\_menu**](wm.htm#M28) 
[**tooltip**](wm.htm#M29) 
[**notification**](wm.htm#M30) 
[**combo**](wm.htm#M31) 
[**dnd**](wm.htm#M32) 
[**normal**](wm.htm#M33) 













 
[**-zoomed**](wm.htm#M34) 

 
[**wm client** *window* ?*name*?](wm.htm#M35) 
[**wm colormapwindows** *window* ?*windowList*?](wm.htm#M36) 
[**wm command** *window* ?*value*?](wm.htm#M37) 
[**wm deiconify** *window*](wm.htm#M38) 
[**wm focusmodel** *window* ?**active**|**passive**?](wm.htm#M39) 
[**wm forget** *window*](wm.htm#M40) 
[**wm frame** *window*](wm.htm#M41) 
[**wm geometry** *window* ?*newGeometry*?](wm.htm#M42) 
[**wm grid** *window* ?*baseWidth baseHeight widthInc heightInc*?](wm.htm#M43) 
[**wm group** *window* ?*pathName*?](wm.htm#M44) 
[**wm iconbitmap** *window* ?*bitmap*?](wm.htm#M45)  
[**wm iconbitmap** *window* ?**-default**? ?*image*?](wm.htm#M46) 
 
[**wm iconify** *window*](wm.htm#M47) 
[**wm iconmask** *window* ?*bitmap*?](wm.htm#M48) 
[**wm iconname** *window* ?*newName*?](wm.htm#M49) 
[**wm iconphoto** *window* ?**-default**? *image1* ?*image2 ...*?](wm.htm#M50) 
[**wm iconposition** *window* ?*x y*?](wm.htm#M51) 
[**wm iconwindow** *window* ?*pathName*?](wm.htm#M52) 
[**wm manage** *widget*](wm.htm#M53) 
[**wm maxsize** *window* ?*width height*?](wm.htm#M54) 
[**wm minsize** *window* ?*width height*?](wm.htm#M55) 
[**wm overrideredirect** *window* ?*boolean*?](wm.htm#M56) 
[**wm positionfrom** *window* ?*who*?](wm.htm#M57) 
[**wm protocol** *window* ?*name*? ?*command*?](wm.htm#M58) 
[**wm resizable** *window* ?*width height*?](wm.htm#M59) 
[**wm sizefrom** *window* ?*who*?](wm.htm#M60) 
[**wm stackorder** *window* ?**isabove**|**isbelow** *window*?](wm.htm#M61) 
[**wm state** *window* ?newstate?](wm.htm#M62) 
[**wm title** *window* ?*string*?](wm.htm#M63) 
[**wm transient** *window* ?*master*?](wm.htm#M64) 
[**wm withdraw** *window*](wm.htm#M65) 

































 
[GEOMETRY MANAGEMENT](wm.htm#M66) 
[GRIDDED GEOMETRY MANAGEMENT](wm.htm#M67) 
[BUGS](wm.htm#M68) 
[EXAMPLES](wm.htm#M69) 
[SEE ALSO](wm.htm#M70) 
[KEYWORDS](wm.htm#M71) 








 Name
----

 wm — Communicate with window manager Synopsis
--------

 **wm** *option window* ?*args*?  
 Description
-----------

 The **wm** command is used to interact with window managers in order to control such things as the title for a window, its geometry, or the increments in terms of which it may be resized. The **wm** command can take any of a number of different forms, depending on the *option* argument. All of the forms expect at least one additional argument, *window*, which must be the path name of a top-level window.  The legal forms for the **wm** command are: 


 
**wm aspect** *window* ?*minNumer minDenom maxNumer maxDenom*?
 If *minNumer*, *minDenom*, *maxNumer*, and *maxDenom* are all specified, then they will be passed to the window manager and the window manager should use them to enforce a range of acceptable aspect ratios for *window*. The aspect ratio of *window* (width/length) will be constrained to lie between *minNumer*/*minDenom* and *maxNumer*/*maxDenom*. If *minNumer* etc. are all specified as empty strings, then any existing aspect ratio restrictions are removed. If *minNumer* etc. are specified, then the command returns an empty string. Otherwise, it returns a Tcl list containing four elements, which are the current values of *minNumer*, *minDenom*, *maxNumer*, and *maxDenom* (if no aspect restrictions are in effect, then an empty string is returned). 


**wm attributes** *window*


**wm attributes** *window* ?**option**?

**wm attributes** *window* ?**option value option value...**?
 This subcommand returns or sets platform specific attributes associated with a window. The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows:  All platforms support the following attributes (though X11 users should see the notes below): 


 **-alpha**
 Specifies the alpha transparency level of the toplevel. It accepts a value from **0.0** (fully transparent) to **1.0** (opaque). Values outside that range will be constrained. Where not supported, the **-alpha** value remains at **1.0**. 

**-fullscreen**
 Places the window in a mode that takes up the entire screen, has no borders, and covers the general use area (i.e. Start menu and taskbar on Windows, dock and menubar on OSX, general window decorations on X11). 

**-topmost**
 Specifies whether this is a topmost window (displays above all other windows). 

  On Windows, the following attributes may be set. 


 **-disabled**
 Specifies whether the window is in a disabled state. 

**-toolwindow**
 Specifies a toolwindow style window (as defined in the MSDN). 

**-transparentcolor**
 Specifies the transparent color index of the toplevel. It takes any color value accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. If the empty string is specified (default), no transparent color is used. This is supported on Windows 2000/XP+. Where not supported, the **-transparentcolor** value remains at **{}**. 

  On Mac OS X, the following attributes may be set. 


 **-modified**
 Specifies the modification state of the window (determines whether the window close widget contains the modification indicator and whether the proxy icon is draggable). 

**-notify**
 Specifies process notification state (bouncing of the application dock icon). 

**-titlepath**
 Specifies the path of the file referenced as the window proxy icon (which can be dragged and dropped in lieu of the file's finder icon). 

**-transparent**
 Makes the window content area transparent and turns off the window shadow. For the transparency to be effective, the toplevel background needs to be set to a color with some alpha, e.g. “systemTransparent”. 

  On X11, the following attributes may be set. These are not supported by all window managers, and will have no effect under older WMs. 


 **-type**
 Requests that the window should be interpreted by the window manager as being of the specified type(s). This may cause the window to be decorated in a different way or otherwise managed differently, though exactly what happens is entirely up to the window manager. A list of types may be used, in order of preference. The following values are mapped to constants defined in the EWMH specification (using others is possible, but not advised): 
 **desktop**
 indicates a desktop feature, 

**dock**
 indicates a dock/panel feature, 

**toolbar**
 indicates a toolbar window that should be acting on behalf of another window, as indicated with **wm transient**, 

**menu**
 indicates a torn-off menu that should be acting on behalf of another window, as indicated with **wm transient**, 

**utility**
 indicates a utility window (e.g., palette or toolbox) that should be acting on behalf of another window, as indicated with **wm transient**, 

**splash**
 indicates a splash screen, displayed during application start up, 

**dialog**
 indicates a general dialog window, that should be acting on behalf of another window, as indicated with **wm transient**, 

**dropdown\_menu**
 indicates a menu summoned from a menu bar, which should usually also be set to be override-redirected (with **wm overrideredirect**), 

**popup\_menu**
 indicates a popup menu, which should usually also be set to be override-redirected (with **wm overrideredirect**), 

**tooltip**
 indicates a tooltip window, which should usually also be set to be override-redirected (with **wm overrideredirect**), 

**notification**
 indicates a window that provides a background notification of some event, which should usually also be set to be override-redirected (with **wm overrideredirect**), 

**combo**
 indicates the drop-down list of a combobox widget, which should usually also be set to be override-redirected (with **wm overrideredirect**), 

**dnd**
 indicates a window that represents something being dragged, which should usually also be set to be override-redirected (with **wm overrideredirect**), 

**normal**
 indicates a window that has no special interpretation. 



**-zoomed**
 Requests that the window should be maximized. This is the same as **wm state zoomed** on Windows and Mac OS X. 

On X11, changes to window attributes are performed asynchronously. Querying the value of an attribute returns the current state, which will not be the same as the value most recently set if the window manager has not yet processed the request or if it does not support the attribute.




**wm client** *window* ?*name*?
 If *name* is specified, this command stores *name* (which should be the name of the host on which the application is executing) in *window*'s **WM\_CLIENT\_MACHINE** property for use by the window manager or session manager. The command returns an empty string in this case. If *name* is not specified, the command returns the last name set in a **wm client** command for *window*. If *name* is specified as an empty string, the command deletes the **WM\_CLIENT\_MACHINE** property from *window*. 


**wm colormapwindows** *window* ?*windowList*?
 This command is used to manipulate the **WM\_COLORMAP\_WINDOWS** property, which provides information to the window managers about windows that have private colormaps.  If *windowList* is not specified, the command returns a list whose elements are the names of the windows in the **WM\_COLORMAP\_WINDOWS** property. If *windowList* is specified, it consists of a list of window path names; the command overwrites the **WM\_COLORMAP\_WINDOWS** property with the given windows and returns an empty string. The **WM\_COLORMAP\_WINDOWS** property should normally contain a list of the internal windows within *window* whose colormaps differ from their parents. 


The order of the windows in the property indicates a priority order: the window manager will attempt to install as many colormaps as possible from the head of this list when *window* gets the colormap focus. If *window* is not included among the windows in *windowList*, Tk implicitly adds it at the end of the **WM\_COLORMAP\_WINDOWS** property, so that its colormap is lowest in priority. If **wm colormapwindows** is not invoked, Tk will automatically set the property for each top-level window to all the internal windows whose colormaps differ from their parents, followed by the top-level itself; the order of the internal windows is undefined. See the ICCCM documentation for more information on the **WM\_COLORMAP\_WINDOWS** property. 




**wm command** *window* ?*value*?
 If *value* is specified, this command stores *value* in *window*'s **WM\_COMMAND** property for use by the window manager or session manager and returns an empty string. *Value* must have proper list structure; the elements should contain the words of the command used to invoke the application. If *value* is not specified then the command returns the last value set in a **wm command** command for *window*. If *value* is specified as an empty string, the command deletes the **WM\_COMMAND** property from *window*. 


**wm deiconify** *window*

 Arrange for *window* to be displayed in normal (non-iconified) form. This is done by mapping the window. If the window has never been mapped then this command will not map the window, but it will ensure that when the window is first mapped it will be displayed in de-iconified form. On Windows, a deiconified window will also be raised and be given the focus (made the active window). Returns an empty string. 


**wm focusmodel** *window* ?**active**|**passive**?
 If **active** or **passive** is supplied as an optional argument to the command, then it specifies the focus model for *window*. In this case the command returns an empty string. If no additional argument is supplied, then the command returns the current focus model for *window*.  An **active** focus model means that *window* will claim the input focus for itself or its descendants, even at times when the focus is currently in some other application. **Passive** means that *window* will never claim the focus for itself: the window manager should give the focus to *window* at appropriate times. However, once the focus has been given to *window* or one of its descendants, the application may re-assign the focus among *window*'s descendants. The focus model defaults to **passive**, and Tk's **[focus](focus.htm)** command assumes a passive model of focusing. 




**wm forget** *window*

 The *window* will be unmapped from the screen and will no longer be managed by **wm**. Windows created with the **[toplevel](toplevel.htm)** command will be treated like **[frame](frame.htm)** windows once they are no longer managed by **wm**, however, the **-menu** configuration will be remembered and the menus will return once the widget is managed again. 


**wm frame** *window*

 If *window* has been reparented by the window manager into a decorative frame, the command returns the platform specific window identifier for the outermost frame that contains *window* (the window whose parent is the root or virtual root). If *window* has not been reparented by the window manager then the command returns the platform specific window identifier for *window*. 


**wm geometry** *window* ?*newGeometry*?
 If *newGeometry* is specified, then the geometry of *window* is changed and an empty string is returned. Otherwise the current geometry for *window* is returned (this is the most recent geometry specified either by manual resizing or in a **wm geometry** command). *NewGeometry* has the form **=***width***x***height***±***x***±***y*, where any of **=**, *width***x***height*, or **±***x***±***y* may be omitted. *Width* and *height* are positive integers specifying the desired dimensions of *window*. If *window* is gridded (see **[GRIDDED GEOMETRY MANAGEMENT](#M67)** below) then the dimensions are specified in grid units; otherwise they are specified in pixel units.  *X* and *y* specify the desired location of *window* on the screen, in pixels. If *x* is preceded by **+**, it specifies the number of pixels between the left edge of the screen and the left edge of *window*'s border; if preceded by **-** then *x* specifies the number of pixels between the right edge of the screen and the right edge of *window*'s border. If *y* is preceded by **+** then it specifies the number of pixels between the top of the screen and the top of *window*'s border; if *y* is preceded by **-** then it specifies the number of pixels between the bottom of *window*'s border and the bottom of the screen. 


 If *newGeometry* is specified as an empty string then any existing user-specified geometry for *window* is cancelled, and the window will revert to the size requested internally by its widgets. 


Note that this is related to **[winfo geometry](winfo.htm)**, but not the same. That can only query the geometry, and always reflects Tk's current understanding of the actual size and location of *window*, whereas **wm geometry** allows both setting and querying of the *window manager*'s understanding of the size and location of the window. This can vary significantly, for example to reflect the addition of decorative elements to *window* such as title bars, and window managers are not required to precisely follow the requests made through this command. 




**wm grid** *window* ?*baseWidth baseHeight widthInc heightInc*?
 This command indicates that *window* is to be managed as a gridded window. It also specifies the relationship between grid units and pixel units. *BaseWidth* and *baseHeight* specify the number of grid units corresponding to the pixel dimensions requested internally by *window* using **[Tk\_GeometryRequest](https://www.tcl.tk/man/tcl/TkLib/GeomReq.htm)**. *WidthInc* and *heightInc* specify the number of pixels in each horizontal and vertical grid unit. These four values determine a range of acceptable sizes for *window*, corresponding to grid-based widths and heights that are non-negative integers. Tk will pass this information to the window manager; during manual resizing, the window manager will restrict the window's size to one of these acceptable sizes.  Furthermore, during manual resizing the window manager will display the window's current size in terms of grid units rather than pixels. If *baseWidth* etc. are all specified as empty strings, then *window* will no longer be managed as a gridded window. If *baseWidth* etc. are specified then the return value is an empty string. 


 Otherwise the return value is a Tcl list containing four elements corresponding to the current *baseWidth*, *baseHeight*, *widthInc*, and *heightInc*; if *window* is not currently gridded, then an empty string is returned. 


Note: this command should not be needed very often, since the **[Tk\_SetGrid](https://www.tcl.tk/man/tcl/TkLib/SetGrid.htm)** library procedure and the **setGrid** option provide easier access to the same functionality. 




**wm group** *window* ?*pathName*?
 If *pathName* is specified, it gives the path name for the leader of a group of related windows. The window manager may use this information, for example, to unmap all of the windows in a group when the group's leader is iconified. *PathName* may be specified as an empty string to remove *window* from any group association. If *pathName* is specified then the command returns an empty string; otherwise it returns the path name of *window*'s current group leader, or an empty string if *window* is not part of any group. 


**wm iconbitmap** *window* ?*bitmap*?
 If *bitmap* is specified, then it names a bitmap in the standard forms accepted by Tk (see the **[Tk\_GetBitmap](https://www.tcl.tk/man/tcl/TkLib/GetBitmap.htm)** manual entry for details). This bitmap is passed to the window manager to be displayed in *window*'s icon, and the command returns an empty string. If an empty string is specified for *bitmap*, then any current icon bitmap is cancelled for *window*. If *bitmap* is specified then the command returns an empty string. Otherwise it returns the name of the current icon bitmap associated with *window*, or an empty string if *window* has no icon bitmap. On the Windows operating system, an additional flag is supported: 
 
**wm iconbitmap** *window* ?**-default**? ?*image*?
 If the **-default** flag is given, the icon is applied to all toplevel windows (existing and future) to which no other specific icon has yet been applied. In addition to bitmap image types, a full path specification to any file which contains a valid Windows icon is also accepted (usually .ico or .icr files), or any file for which the shell has assigned an icon. Tcl will first test if the file contains an icon, then if it has an assigned icon, and finally, if that fails, test for a bitmap. 




**wm iconify** *window*

 Arrange for *window* to be iconified. It *window* has not yet been mapped for the first time, this command will arrange for it to appear in the iconified state when it is eventually mapped. 


**wm iconmask** *window* ?*bitmap*?
 If *bitmap* is specified, then it names a bitmap in the standard forms accepted by Tk (see the **[Tk\_GetBitmap](https://www.tcl.tk/man/tcl/TkLib/GetBitmap.htm)** manual entry for details). This bitmap is passed to the window manager to be used as a mask in conjunction with the **iconbitmap** option: where the mask has zeroes no icon will be displayed; where it has ones, the bits from the icon bitmap will be displayed. If an empty string is specified for *bitmap* then any current icon mask is cancelled for *window* (this is equivalent to specifying a bitmap of all ones). If *bitmap* is specified then the command returns an empty string. Otherwise it returns the name of the current icon mask associated with *window*, or an empty string if no mask is in effect. 


**wm iconname** *window* ?*newName*?
 If *newName* is specified, then it is passed to the window manager; the window manager should display *newName* inside the icon associated with *window*. In this case an empty string is returned as result. If *newName* is not specified then the command returns the current icon name for *window*, or an empty string if no icon name has been specified (in this case the window manager will normally display the window's title, as specified with the **wm title** command). 


**wm iconphoto** *window* ?**-default**? *image1* ?*image2 ...*?
 Sets the titlebar icon for *window* based on the named photo images. If **-default** is specified, this is applied to all future created toplevels as well. The data in the images is taken as a snapshot at the time of invocation. If the images are later changed, this is not reflected to the titlebar icons. Multiple images are accepted to allow different images sizes (e.g., 16x16 and 32x32) to be provided. The window manager may scale provided icons to an appropriate size.  On Windows, the images are packed into a Windows icon structure. This will override an ico specified to **wm iconbitmap**, and vice versa. 


 On X, the images are arranged into the \_NET\_WM\_ICON X property, which most modern window managers support. A **wm iconbitmap** may exist simultaneously. It is recommended to use not more than 2 icons, placing the larger icon first. 


On Macintosh, this currently does nothing. 




**wm iconposition** *window* ?*x y*?
 If *x* and *y* are specified, they are passed to the window manager as a hint about where to position the icon for *window*. In this case an empty string is returned. If *x* and *y* are specified as empty strings then any existing icon position hint is cancelled. If neither *x* nor *y* is specified, then the command returns a Tcl list containing two values, which are the current icon position hints (if no hints are in effect then an empty string is returned). 


**wm iconwindow** *window* ?*pathName*?
 If *pathName* is specified, it is the path name for a window to use as icon for *window*: when *window* is iconified then *pathName* will be mapped to serve as icon, and when *window* is de-iconified then *pathName* will be unmapped again. If *pathName* is specified as an empty string then any existing icon window association for *window* will be cancelled. If the *pathName* argument is specified then an empty string is returned. Otherwise the command returns the path name of the current icon window for *window*, or an empty string if there is no icon window currently specified for *window*. Button press events are disabled for *window* as long as it is an icon window; this is needed in order to allow window managers to “own” those events. Note: not all window managers support the notion of an icon window. 


**wm manage** *widget*

 The *widget* specified will become a stand alone top-level window. The window will be decorated with the window managers title bar, etc. Only *frame*, *labelframe* and *toplevel* widgets can be used with this command. Attempting to pass any other widget type will raise an error. Attempting to manage a *toplevel* widget is benign and achieves nothing. See also **[GEOMETRY MANAGEMENT](#M66)**. 


**wm maxsize** *window* ?*width height*?
 If *width* and *height* are specified, they give the maximum permissible dimensions for *window*. For gridded windows the dimensions are specified in grid units; otherwise they are specified in pixel units. The window manager will restrict the window's dimensions to be less than or equal to *width* and *height*. If *width* and *height* are specified, then the command returns an empty string. Otherwise it returns a Tcl list with two elements, which are the maximum width and height currently in effect. The maximum size defaults to the size of the screen. See the sections on geometry management below for more information. 


**wm minsize** *window* ?*width height*?
 If *width* and *height* are specified, they give the minimum permissible dimensions for *window*. For gridded windows the dimensions are specified in grid units; otherwise they are specified in pixel units. The window manager will restrict the window's dimensions to be greater than or equal to *width* and *height*. If *width* and *height* are specified, then the command returns an empty string. Otherwise it returns a Tcl list with two elements, which are the minimum width and height currently in effect. The minimum size defaults to one pixel in each dimension. See the sections on geometry management below for more information. 


**wm overrideredirect** *window* ?*boolean*?
 If *boolean* is specified, it must have a proper boolean form and the override-redirect flag for *window* is set to that value. If *boolean* is not specified then **1** or **0** is returned to indicate whether or not the override-redirect flag is currently set for *window*. Setting the override-redirect flag for a window causes it to be ignored by the window manager; among other things, this means that the window will not be reparented from the root window into a decorative frame and the user will not be able to manipulate the window using the normal window manager mechanisms.  Note that the override-redirect flag is only guaranteed to be taken notice of when the window is first mapped or when mapped after the state is changed from withdrawn to normal. Some, but not all, platforms will take notice at additional times. 




**wm positionfrom** *window* ?*who*?
 If *who* is specified, it must be either **program** or **user**, or an abbreviation of one of these two. It indicates whether *window*'s current position was requested by the program or by the user. Many window managers ignore program-requested initial positions and ask the user to manually position the window; if **user** is specified then the window manager should position the window at the given place without asking the user for assistance. If *who* is specified as an empty string, then the current position source is cancelled. If *who* is specified, then the command returns an empty string. Otherwise it returns **user** or **program** to indicate the source of the window's current position, or an empty string if no source has been specified yet. Most window managers interpret “no source” as equivalent to **program**. Tk will automatically set the position source to **user** when a **wm geometry** command is invoked, unless the source has been set explicitly to **program**. 


**wm protocol** *window* ?*name*? ?*command*?
 This command is used to manage window manager protocols such as **WM\_DELETE\_WINDOW**. *Name* is the name of an atom corresponding to a window manager protocol, such as **WM\_DELETE\_WINDOW** or **WM\_SAVE\_YOURSELF** or **WM\_TAKE\_FOCUS**. If both *name* and *command* are specified, then *command* is associated with the protocol specified by *name*. *Name* will be added to *window*'s **WM\_PROTOCOLS** property to tell the window manager that the application has a protocol handler for *name*, and *command* will be invoked in the future whenever the window manager sends a message to the client for that protocol. In this case the command returns an empty string. If *name* is specified but *command* is not, then the current command for *name* is returned, or an empty string if there is no handler defined for *name*. If *command* is specified as an empty string then the current handler for *name* is deleted and it is removed from the **WM\_PROTOCOLS** property on *window*; an empty string is returned. Lastly, if neither *name* nor *command* is specified, the command returns a list of all the protocols for which handlers are currently defined for *window*.  Tk always defines a protocol handler for **WM\_DELETE\_WINDOW**, even if you have not asked for one with **wm protocol**. If a **WM\_DELETE\_WINDOW** message arrives when you have not defined a handler, then Tk handles the message by destroying the window for which it was received. 




**wm resizable** *window* ?*width height*?
 This command controls whether or not the user may interactively resize a top-level window. If *width* and *height* are specified, they are boolean values that determine whether the width and height of *window* may be modified by the user. In this case the command returns an empty string. If *width* and *height* are omitted then the command returns a list with two 0/1 elements that indicate whether the width and height of *window* are currently resizable. By default, windows are resizable in both dimensions. If resizing is disabled, then the window's size will be the size from the most recent interactive resize or **wm geometry** command. If there has been no such operation then the window's natural size will be used. 


**wm sizefrom** *window* ?*who*?
 If *who* is specified, it must be either **program** or **user**, or an abbreviation of one of these two. It indicates whether *window*'s current size was requested by the program or by the user. Some window managers ignore program-requested sizes and ask the user to manually size the window; if **user** is specified then the window manager should give the window its specified size without asking the user for assistance. If *who* is specified as an empty string, then the current size source is cancelled. If *who* is specified, then the command returns an empty string. Otherwise it returns **user** or **window** to indicate the source of the window's current size, or an empty string if no source has been specified yet. Most window managers interpret “no source” as equivalent to **program**. 


**wm stackorder** *window* ?**isabove**|**isbelow** *window*?
 The **stackorder** command returns a list of toplevel windows in stacking order, from lowest to highest. When a single toplevel window is passed, the returned list recursively includes all of the window's children that are toplevels. Only those toplevels that are currently mapped to the screen are returned. The **stackorder** command can also be used to determine if one toplevel is positioned above or below a second toplevel. When two window arguments separated by either **isabove** or **isbelow** are passed, a boolean result indicates whether or not the first window is currently above or below the second window in the stacking order. 


**wm state** *window* ?newstate?
 If *newstate* is specified, the window will be set to the new state, otherwise it returns the current state of *window*: either **normal**, **iconic**, **withdrawn**, **icon**, or (Windows and Mac OS X only) **zoomed**. The difference between **iconic** and **icon** is that **iconic** refers to a window that has been iconified (e.g., with the **wm iconify** command) while **icon** refers to a window whose only purpose is to serve as the icon for some other window (via the **wm iconwindow** command). The **icon** state cannot be set. 


**wm title** *window* ?*string*?
 If *string* is specified, then it will be passed to the window manager for use as the title for *window* (the window manager should display this string in *window*'s title bar). In this case the command returns an empty string. If *string* is not specified then the command returns the current title for the *window*. The title for a window defaults to its name. 


**wm transient** *window* ?*master*?
 If *master* is specified, then the window manager is informed that *window* is a transient window (e.g. pull-down menu) working on behalf of *master* (where *master* is the path name for a top-level window). If *master* is specified as an empty string then *window* is marked as not being a transient window any more. Otherwise the command returns the path name of *window*'s current master, or an empty string if *window* is not currently a transient window. A transient window will mirror state changes in the master and inherit the state of the master when initially mapped. It is an error to attempt to make a window a transient of itself. The window manager may also decorate a transient window differently, removing some features normally present (e.g., minimize and maximize buttons) though this is entirely at the discretion of the window manager. 


**wm withdraw** *window*

 Arranges for *window* to be withdrawn from the screen. This causes the window to be unmapped and forgotten about by the window manager. If the window has never been mapped, then this command causes the window to be mapped in the withdrawn state. Not all window managers appear to know how to handle windows that are mapped in the withdrawn state. Note: it sometimes seems to be necessary to withdraw a window and then re-map it (e.g. with **wm deiconify**) to get some window managers to pay attention to changes in window attributes such as group. 

 Geometry management
-------------------

 By default a top-level window appears on the screen in its *natural size*, which is the one determined internally by its widgets and geometry managers. If the natural size of a top-level window changes, then the window's size changes to match. A top-level window can be given a size other than its natural size in two ways. First, the user can resize the window manually using the facilities of the window manager, such as resize handles. Second, the application can request a particular size for a top-level window using the **wm geometry** command. These two cases are handled identically by Tk; in either case, the requested size overrides the natural size. You can return the window to its natural by invoking **wm geometry** with an empty *geometry* string.  Normally a top-level window can have any size from one pixel in each dimension up to the size of its screen. However, you can use the **wm minsize** and **wm maxsize** commands to limit the range of allowable sizes. The range set by **wm minsize** and **wm maxsize** applies to all forms of resizing, including the window's natural size as well as manual resizes and the **wm geometry** command. You can also use the command **wm resizable** to completely disable interactive resizing in one or both dimensions. 


 The **wm manage** and **wm forget** commands may be used to perform undocking and docking of windows. After a widget is managed by **wm manage** command, all other **wm** subcommands may be used with the widget. Only widgets created using the toplevel command may have an attached menu via the **-menu** configure option. A toplevel widget may be used as a frame and managed with any of the other geometry managers after using the **wm forget** command. Any menu associated with a toplevel widget will be hidden when managed by another geometry managers. The menus will reappear once the window is managed by **wm**. All custom bindtags for widgets in a subtree that have their top-level widget changed via a **wm manage** or **wm forget** command, must be redone to adjust any top-level widget path in the bindtags. Bindtags that have not been customized do not have to be redone. 


Gridded geometry management
---------------------------

 Gridded geometry management occurs when one of the widgets of an application supports a range of useful sizes. This occurs, for example, in a text editor where the scrollbars, menus, and other adornments are fixed in size but the edit widget can support any number of lines of text or characters per line. In this case, it is usually desirable to let the user specify the number of lines or characters-per-line, either with the **wm geometry** command or by interactively resizing the window. In the case of text, and in other interesting cases also, only discrete sizes of the window make sense, such as integral numbers of lines and characters-per-line; arbitrary pixel sizes are not useful.  Gridded geometry management provides support for this kind of application. Tk (and the window manager) assume that there is a grid of some sort within the application and that the application should be resized in terms of *grid units* rather than pixels. Gridded geometry management is typically invoked by turning on the **setGrid** option for a widget; it can also be invoked with the **wm grid** command or by calling **[Tk\_SetGrid](https://www.tcl.tk/man/tcl/TkLib/SetGrid.htm)**. In each of these approaches the particular widget (or sometimes code in the application as a whole) specifies the relationship between integral grid sizes for the window and pixel sizes. To return to non-gridded geometry management, invoke **wm grid** with empty argument strings. 


 When gridded geometry management is enabled then all the dimensions specified in **wm minsize**, **wm maxsize**, and **wm geometry** commands are treated as grid units rather than pixel units. Interactive resizing is also carried out in even numbers of grid units rather than pixels. 


Bugs
----

 Most existing window managers appear to have bugs that affect the operation of the **wm** command. For example, some changes will not take effect if the window is already active: the window will have to be withdrawn and de-iconified in order to make the change happen. Examples
--------

 A fixed-size window that says that it is fixed-size too: 
```
toplevel .fixed
**wm title**     .fixed "Fixed-size Window"
**wm resizable** .fixed 0 0
```
  A simple dialog-like window, centred on the screen: 



```
# Create and arrange the dialog contents.
toplevel .msg
label  .msg.l  -text "This is a very simple dialog demo."
button .msg.ok -text OK -default active -command {destroy .msg}
pack .msg.ok -side bottom -fill x
pack .msg.l  -expand 1    -fill both

# Now set the widget up as a centred dialog.

# But first, we need the geometry managers to finish setting
# up the interior of the dialog, for which we need to run the
# event loop with the widget hidden completely...
**wm withdraw** .msg
update
set x [expr {([winfo screenwidth .]-[winfo width .msg])/2}]
set y [expr {([winfo screenheight .]-[winfo height .msg])/2}]
**wm geometry**  .msg +$x+$y
**wm transient** .msg .
**wm title**     .msg "Dialog demo"
**wm deiconify** .msg
```
 See also
--------

 **[toplevel](toplevel.htm)**, **[winfo](winfo.htm)** Copyright © 1991-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/wm.htm>

library
=======

  
[NAME](library.htm#M2) auto\_execok, auto\_import, auto\_load, auto\_mkindex, auto\_qualify, auto\_reset, tcl\_findLibrary, parray, tcl\_endOfWord, tcl\_startOfNextWord, tcl\_startOfPreviousWord, tcl\_wordBreakAfter, tcl\_wordBreakBefore — standard library of Tcl procedures 
[SYNOPSIS](library.htm#M3) 
[INTRODUCTION](library.htm#M4) 
[COMMAND PROCEDURES](library.htm#M5)  
[**auto\_execok** *cmd*](library.htm#M6) 
[**auto\_import** *pattern*](library.htm#M7) 
[**auto\_load** *cmd*](library.htm#M8) 
[**auto\_mkindex** *dir pattern pattern ...*](library.htm#M9) 
[**auto\_reset**](library.htm#M10) 
[**auto\_qualify** *command namespace*](library.htm#M11) 
[**tcl\_findLibrary** *basename version patch initScript enVarName varName*](library.htm#M12) 
[**parray** *arrayName* ?*pattern*?](library.htm#M13) 
[**tcl\_endOfWord** *str start*](library.htm#M14) 
[**tcl\_startOfNextWord** *str start*](library.htm#M15) 
[**tcl\_startOfPreviousWord** *str start*](library.htm#M16) 
[**tcl\_wordBreakAfter** *str start*](library.htm#M17) 
[**tcl\_wordBreakBefore** *str start*](library.htm#M18) 












 
[VARIABLES](library.htm#M19) 
[AUTOLOADING AND PACKAGE MANAGEMENT VARIABLES](library.htm#M20)  
[**auto\_execs**](library.htm#M21) 
[**auto\_index**](library.htm#M22) 
[**auto\_noexec**](library.htm#M23) 
[**auto\_noload**](library.htm#M24) 
[**auto\_path**](library.htm#M25) 
[**env(TCL\_LIBRARY)**](library.htm#M26) 
[**env(TCLLIBPATH)**](library.htm#M27) 






 
[WORD BOUNDARY DETERMINATION VARIABLES](library.htm#M28)  
[**tcl\_nonwordchars**](library.htm#M29) 
[**tcl\_wordchars**](library.htm#M30) 

 
[SEE ALSO](library.htm#M31) 
[KEYWORDS](library.htm#M32) 








 Name
----

 auto\_execok, auto\_import, auto\_load, auto\_mkindex, auto\_qualify, auto\_reset, tcl\_findLibrary, parray, tcl\_endOfWord, tcl\_startOfNextWord, tcl\_startOfPreviousWord, tcl\_wordBreakAfter, tcl\_wordBreakBefore — standard library of Tcl procedures Synopsis
--------

 **auto\_execok** *cmd*  
 **auto\_import** *pattern*  
 **auto\_load** *cmd*  
 **auto\_mkindex** *dir pattern pattern ...*  
 **auto\_qualify** *command namespace*  
 **auto\_reset**  
 **tcl\_findLibrary** *basename version patch initScript enVarName varName*  
 **parray** *arrayName* ?*pattern*?  
 **tcl\_endOfWord** *str start*  
 **tcl\_startOfNextWord** *str start*  
 **tcl\_startOfPreviousWord** *str start*  
 **tcl\_wordBreakAfter** *str start*  
 **tcl\_wordBreakBefore** *str start*  
 Introduction
------------

 Tcl includes a library of Tcl procedures for commonly-needed functions. The procedures defined in the Tcl library are generic ones suitable for use by many different applications. The location of the Tcl library is returned by the **[info library](info.htm)** command. In addition to the Tcl library, each application will normally have its own library of support procedures as well; the location of this library is normally given by the value of the **$***app***\_library** global variable, where *app* is the name of the application. For example, the location of the Tk library is kept in the variable **[tk\_library](../tkcmd/tkvars.htm)**.  To access the procedures in the Tcl library, an application should source the file **init.tcl** in the library, for example with the Tcl command 



```
**source [file join [info library] init.tcl]**
```
  If the library procedure **[Tcl\_Init](https://www.tcl.tk/man/tcl/TclLib/Init.htm)** is invoked from an application's **[Tcl\_AppInit](https://www.tcl.tk/man/tcl/TclLib/AppInit.htm)** procedure, this happens automatically. The code in **init.tcl** will define the **[unknown](unknown.htm)** procedure and arrange for the other procedures to be loaded on-demand using the auto-load mechanism defined below. 


Command procedures
------------------

 The following procedures are provided in the Tcl library: 
 
**auto\_execok** *cmd*

 Determines whether there is an executable file or shell builtin by the name *cmd*. If so, it returns a list of arguments to be passed to **[exec](exec.htm)** to execute the executable file or shell builtin named by *cmd*. If not, it returns an empty string. This command examines the directories in the current search path (given by the PATH environment variable) in its search for an executable file named *cmd*. On Windows platforms, the search is expanded with the same directories and file extensions as used by **[exec](exec.htm)**. **Auto\_execok** remembers information about previous searches in an array named **auto\_execs**; this avoids the path search in future calls for the same *cmd*. The command **auto\_reset** may be used to force **auto\_execok** to forget its cached information. 


**auto\_import** *pattern*

 **Auto\_import** is invoked during **[namespace import](namespace.htm)** to see if the imported commands specified by *pattern* reside in an autoloaded library. If so, the commands are loaded so that they will be available to the interpreter for creating the import links. If the commands do not reside in an autoloaded library, **auto\_import** does nothing. The pattern matching is performed according to the matching rules of **[namespace import](namespace.htm)**. 


**auto\_load** *cmd*

 This command attempts to load the definition for a Tcl command named *cmd*. To do this, it searches an *auto-load path*, which is a list of one or more directories. The auto-load path is given by the global variable **[auto\_path](tclvars.htm)** if it exists. If there is no **[auto\_path](tclvars.htm)** variable, then the TCLLIBPATH environment variable is used, if it exists. Otherwise the auto-load path consists of just the Tcl library directory. Within each directory in the auto-load path there must be a file **tclIndex** that describes one or more commands defined in that directory and a script to evaluate to load each of the commands. The **tclIndex** file should be generated with the **auto\_mkindex** command. If *cmd* is found in an index file, then the appropriate script is evaluated to create the command. The **auto\_load** command returns 1 if *cmd* was successfully created. The command returns 0 if there was no index entry for *cmd* or if the script did not actually define *cmd* (e.g. because index information is out of date). If an error occurs while processing the script, then that error is returned. **Auto\_load** only reads the index information once and saves it in the array **auto\_index**; future calls to **auto\_load** check for *cmd* in the array rather than re-reading the index files. The cached index information may be deleted with the command **auto\_reset**. This will force the next **auto\_load** command to reload the index database from disk. 


**auto\_mkindex** *dir pattern pattern ...*

 Generates an index suitable for use by **auto\_load**. The command searches *dir* for all files whose names match any of the *pattern* arguments (matching is done with the **[glob](glob.htm)** command), generates an index of all the Tcl command procedures defined in all the matching files, and stores the index information in a file named **tclIndex** in *dir*. If no pattern is given a pattern of **\*.tcl** will be assumed. For example, the command 

```
**auto\_mkindex foo \*.tcl**
```
  will read all the **.tcl** files in subdirectory **foo** and generate a new index file **foo/tclIndex**. 


 **Auto\_mkindex** parses the Tcl scripts by sourcing them into a slave interpreter and monitoring the proc and namespace commands that are executed. Extensions can use the (undocumented) auto\_mkindex\_parser package to register other commands that can contribute to the auto\_load index. You will have to read through auto.tcl to see how this works. 


**Auto\_mkindex\_old** (which has the same syntax as **auto\_mkindex**) parses the Tcl scripts in a relatively unsophisticated way: if any line contains the word “**[proc](proc.htm)**” as its first characters then it is assumed to be a procedure definition and the next word of the line is taken as the procedure's name. Procedure definitions that do not appear in this way (e.g. they have spaces before the **[proc](proc.htm)**) will not be indexed. If your script contains “dangerous” code, such as global initialization code or procedure names with special characters like **$**, **\***, **[** or **]**, you are safer using **auto\_mkindex\_old**. 



**auto\_reset**
 Destroys all the information cached by **auto\_execok** and **auto\_load**. This information will be re-read from disk the next time it is needed. **Auto\_reset** also deletes any procedures listed in the auto-load index, so that fresh copies of them will be loaded the next time that they are used. 


**auto\_qualify** *command namespace*

 Computes a list of fully qualified names for *command*. This list mirrors the path a standard Tcl interpreter follows for command lookups: first it looks for the command in the current namespace, and then in the global namespace. Accordingly, if *command* is relative and *namespace* is not **::**, the list returned has two elements: *command* scoped by *namespace*, as if it were a command in the *namespace* namespace; and *command* as if it were a command in the global namespace. Otherwise, if either *command* is absolute (it begins with **::**), or *namespace* is **::**, the list contains only *command* as if it were a command in the global namespace.  **Auto\_qualify** is used by the auto-loading facilities in Tcl, both for producing auto-loading indexes such as *pkgIndex.tcl*, and for performing the actual auto-loading of functions at runtime. 




**tcl\_findLibrary** *basename version patch initScript enVarName varName*

 This is a standard search procedure for use by extensions during their initialization. They call this procedure to look for their script library in several standard directories. The last component of the name of the library directory is normally *basenameversion* (e.g., tk8.0), but it might be “library” when in the build hierarchies. The *initScript* file will be sourced into the interpreter once it is found. The directory in which this file is found is stored into the global variable *varName*. If this variable is already defined (e.g., by C code during application initialization) then no searching is done. Otherwise the search looks in these directories: the directory named by the environment variable *enVarName*; relative to the Tcl library directory; relative to the executable file in the standard installation bin or bin/*arch* directory; relative to the executable file in the current build tree; relative to the executable file in a parallel build tree. 


**parray** *arrayName* ?*pattern*?
 Prints on standard output the names and values of all the elements in the array *arrayName*, or just the names that match *pattern* (using the matching rules of **[string match](string.htm)**) and their values if *pattern* is given. *ArrayName* must be an array accessible to the caller of **parray**. It may be either local or global. 


**tcl\_endOfWord** *str start*

 Returns the index of the first end-of-word location that occurs after a starting index *start* in the string *str*. An end-of-word location is defined to be the first non-word character following the first word character after the starting point. Returns -1 if there are no more end-of-word locations after the starting point. See the description of **[tcl\_wordchars](tclvars.htm)** and **[tcl\_nonwordchars](tclvars.htm)** below for more details on how Tcl determines which characters are word characters. 


**tcl\_startOfNextWord** *str start*

 Returns the index of the first start-of-word location that occurs after a starting index *start* in the string *str*. A start-of-word location is defined to be the first word character following a non-word character. Returns -1 if there are no more start-of-word locations after the starting point. 


**tcl\_startOfPreviousWord** *str start*

 Returns the index of the first start-of-word location that occurs before a starting index *start* in the string *str*. Returns -1 if there are no more start-of-word locations before the starting point. 


**tcl\_wordBreakAfter** *str start*

 Returns the index of the first word boundary after the starting index *start* in the string *str*. Returns -1 if there are no more boundaries after the starting point in the given string. The index returned refers to the second character of the pair that comprises a boundary. 


**tcl\_wordBreakBefore** *str start*

 Returns the index of the first word boundary before the starting index *start* in the string *str*. Returns -1 if there are no more boundaries before the starting point in the given string. The index returned refers to the second character of the pair that comprises a boundary. 

 Variables
---------

 The following global variables are defined or used by the procedures in the Tcl library. They fall into two broad classes, handling unknown commands and packages, and determining what are words. ### Autoloading and package management variables

  **auto\_execs**
 Used by **auto\_execok** to record information about whether particular commands exist as executable files. 

**auto\_index**
 Used by **auto\_load** to save the index information read from disk. 

**auto\_noexec**
 If set to any value, then **[unknown](unknown.htm)** will not attempt to auto-exec any commands. 

**auto\_noload**
 If set to any value, then **[unknown](unknown.htm)** will not attempt to auto-load any commands. 

**auto\_path**
 If set, then it must contain a valid Tcl list giving directories to search during auto-load operations (including for package index files when using the default **[package unknown](package.htm)** handler). This variable is initialized during startup to contain, in order: the directories listed in the **TCLLIBPATH** environment variable, the directory named by the **[tcl\_library](tclvars.htm)** global variable, the parent directory of **[tcl\_library](tclvars.htm)**, the directories listed in the **[tcl\_pkgPath](tclvars.htm)** variable. Additional locations to look for files and package indices should normally be added to this variable using **[lappend](lappend.htm)**. 

**env(TCL\_LIBRARY)**
 If set, then it specifies the location of the directory containing library scripts (the value of this variable will be assigned to the **[tcl\_library](tclvars.htm)** variable and therefore returned by the command **[info library](info.htm)**). If this variable is not set then a default value is used. 

**env(TCLLIBPATH)**
 If set, then it must contain a valid Tcl list giving directories to search during auto-load operations. Directories must be specified in Tcl format, using “/” as the path separator, regardless of platform. This variable is only used when initializing the **[auto\_path](tclvars.htm)** variable. 

 ### Word boundary determination variables

 These variables are only used in the **tcl\_endOfWord**, **tcl\_startOfNextWord**, **tcl\_startOfPreviousWord**, **tcl\_wordBreakAfter**, and **tcl\_wordBreakBefore** commands. 
 **tcl\_nonwordchars**
 This variable contains a regular expression that is used by routines like **tcl\_endOfWord** to identify whether a character is part of a word or not. If the pattern matches a character, the character is considered to be a non-word character. On Windows platforms, spaces, tabs, and newlines are considered non-word characters. Under Unix, everything but numbers, letters and underscores are considered non-word characters. 

**tcl\_wordchars**
 This variable contains a regular expression that is used by routines like **tcl\_endOfWord** to identify whether a character is part of a word or not. If the pattern matches a character, the character is considered to be a word character. On Windows platforms, words are comprised of any character that is not a space, tab, or newline. Under Unix, words are comprised of numbers, letters or underscores. 

 See also
--------

 **[env](tclvars.htm)**, **[info](info.htm)**, **[re\_syntax](re_syntax.htm)** Copyright © 1991-1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/library.htm>

canvas
======

  
[NAME](canvas.htm#M2) canvas — Create and manipulate 'canvas' hypergraphics drawing surface widgets 
[SYNOPSIS](canvas.htm#M3) 
[STANDARD OPTIONS](canvas.htm#M4)  
[-background or -bg, background, Background](options.htm#M-background) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-insertbackground, insertBackground, Foreground](options.htm#M-insertbackground) 
[-insertborderwidth, insertBorderWidth, BorderWidth](options.htm#M-insertborderwidth) 
[-insertofftime, insertOffTime, OffTime](options.htm#M-insertofftime) 
[-insertontime, insertOnTime, OnTime](options.htm#M-insertontime) 
[-insertwidth, insertWidth, InsertWidth](options.htm#M-insertwidth) 
[-relief, relief, Relief](options.htm#M-relief) 
[-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground) 
[-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth) 
[-selectforeground, selectForeground, Background](options.htm#M-selectforeground) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand) 
[-yscrollcommand, yScrollCommand, ScrollCommand](options.htm#M-yscrollcommand) 

















 
[WIDGET-SPECIFIC OPTIONS](canvas.htm#M5)  
[-closeenough, closeEnough, CloseEnough](canvas.htm#M6) 
[-confine, confine, Confine](canvas.htm#M7) 
[-height, height, Height](canvas.htm#M8) 
[-scrollregion, scrollRegion, ScrollRegion](canvas.htm#M9) 
[-state, state, State](canvas.htm#M10) 
[-width, width, width](canvas.htm#M11) 
[-xscrollincrement, xScrollIncrement, ScrollIncrement](canvas.htm#M12) 
[-yscrollincrement, yScrollIncrement, ScrollIncrement](canvas.htm#M13) 







 
[INTRODUCTION](canvas.htm#M14) 
[DISPLAY LIST](canvas.htm#M15) 
[ITEM IDS AND TAGS](canvas.htm#M16) 
[COORDINATES](canvas.htm#M17) 
[TRANSFORMATIONS](canvas.htm#M18) 
[INDICES](canvas.htm#M19)  
[*number*](canvas.htm#M20) 
[**end**](canvas.htm#M21) 
[**insert**](canvas.htm#M22) 
[**sel.first**](canvas.htm#M23) 
[**sel.last**](canvas.htm#M24) 
[**@***x,y*](canvas.htm#M25) 





 
[DASH PATTERNS](canvas.htm#M26) 
[WIDGET COMMAND](canvas.htm#M27)  
[*pathName* **addtag** *tag searchSpec* ?*arg arg ...*?](canvas.htm#M28)  
[**above** *tagOrId*](canvas.htm#M29) 
[**all**](canvas.htm#M30) 
[**below** *tagOrId*](canvas.htm#M31) 
[**closest** *x y* ?*halo*? ?*start*?](canvas.htm#M32) 
[**enclosed** *x1* *y1* *x2* *y2*](canvas.htm#M33) 
[**overlapping** *x1* *y1* *x2* *y2*](canvas.htm#M34) 
[**withtag** *tagOrId*](canvas.htm#M35) 






 
[*pathName* **bbox** *tagOrId* ?*tagOrId tagOrId ...*?](canvas.htm#M36) 
[*pathName* **bind** *tagOrId* ?*sequence*? ?*command*?](canvas.htm#M37) 
[*pathName* **canvasx** *screenx* ?*gridspacing*?](canvas.htm#M38) 
[*pathName* **canvasy** *screeny* ?*gridspacing*?](canvas.htm#M39) 
[*pathName* **cget** *option*](canvas.htm#M40) 
[*pathName* **configure ?***option*? ?*value*? ?*option value ...*?](canvas.htm#M41) 
[*pathName* **coords** *tagOrId* ?*x0 y0 ...*?](canvas.htm#M42) 
[*pathName* **coords** *tagOrId* ?*coordList*?](canvas.htm#M43) 
[*pathName* **create** *type x y* ?*x y ...*? ?*option value ...*?](canvas.htm#M44) 
[*pathName* **create** *type coordList* ?*option value ...*?](canvas.htm#M45) 
[*pathName* **dchars** *tagOrId first* ?*last*?](canvas.htm#M46) 
[*pathName* **delete** ?*tagOrId tagOrId ...*?](canvas.htm#M47) 
[*pathName* **dtag** *tagOrId* ?*tagToDelete*?](canvas.htm#M48) 
[*pathName* **find** *searchCommand* ?*arg arg ...*?](canvas.htm#M49) 
[*pathName* **focus** ?*tagOrId*?](canvas.htm#M50) 
[*pathName* **gettags** *tagOrId*](canvas.htm#M51) 
[*pathName* **icursor** *tagOrId index*](canvas.htm#M52) 
[*pathName* **imove** *tagOrId index x y*](canvas.htm#M53) 
[*pathName* **index** *tagOrId index*](canvas.htm#M54) 
[*pathName* **insert** *tagOrId beforeThis string*](canvas.htm#M55) 
[*pathName* **itemcget** *tagOrId* *option*](canvas.htm#M56) 
[*pathName* **itemconfigure** *tagOrId* ?*option*? ?*value*? ?*option value ...*?](canvas.htm#M57) 
[*pathName* **lower** *tagOrId* ?*belowThis*?](canvas.htm#M58) 
[*pathName* **move** *tagOrId xAmount yAmount*](canvas.htm#M59) 
[*pathName* **moveto** *tagOrId xPos yPos*](canvas.htm#M60) 
[*pathName* **postscript** ?*option value option value ...*?](canvas.htm#M61)  
[**-channel** *channelName*](canvas.htm#M62) 
[**-colormap** *varName*](canvas.htm#M63) 
[**-colormode** *mode*](canvas.htm#M64) 
[**-file** *fileName*](canvas.htm#M65) 
[**-fontmap** *varName*](canvas.htm#M66) 
[**-height** *size*](canvas.htm#M67) 
[**-pageanchor** *anchor*](canvas.htm#M68) 
[**-pageheight** *size*](canvas.htm#M69) 
[**-pagewidth** *size*](canvas.htm#M70) 
[**-pagex** *position*](canvas.htm#M71) 
[**-pagey** *position*](canvas.htm#M72) 
[**-rotate** *boolean*](canvas.htm#M73) 
[**-width** *size*](canvas.htm#M74) 
[**-x** *position*](canvas.htm#M75) 
[**-y** *position*](canvas.htm#M76) 














 
[*pathName* **raise** *tagOrId* ?*aboveThis*?](canvas.htm#M77) 
[*pathName* **rchars** *tagOrId first last string*](canvas.htm#M78) 
[*pathName* **scale** *tagOrId xOrigin yOrigin xScale yScale*](canvas.htm#M79) 
[*pathName* **scan** *option args*](canvas.htm#M80)  
[*pathName* **scan mark** *x y*](canvas.htm#M81) 
[*pathName* **scan dragto** *x y ?gain?*](canvas.htm#M82) 

 
[*pathName* **select** *option* ?*tagOrId arg*?](canvas.htm#M83)  
[*pathName* **select adjust** *tagOrId index*](canvas.htm#M84) 
[*pathName* **select clear**](canvas.htm#M85) 
[*pathName* **select from** *tagOrId index*](canvas.htm#M86) 
[*pathName* **select item**](canvas.htm#M87) 
[*pathName* **select to** *tagOrId index*](canvas.htm#M88) 




 
[*pathName* **type** *tagOrId*](canvas.htm#M89) 
[*pathName* **xview** ?*args*?](canvas.htm#M90)  
[*pathName* **xview**](canvas.htm#M91) 
[*pathName* **xview moveto** *fraction*](canvas.htm#M92) 
[*pathName* **xview scroll** *number what*](canvas.htm#M93) 


 
[*pathName* **yview** *?args*?](canvas.htm#M94)  
[*pathName* **yview**](canvas.htm#M95) 
[*pathName* **yview moveto** *fraction*](canvas.htm#M96) 
[*pathName* **yview scroll** *number what*](canvas.htm#M97) 


 


































 
[OVERVIEW OF ITEM TYPES](canvas.htm#M98) 
[COMMON ITEM OPTIONS](canvas.htm#M99)  
[**-anchor** *anchorPos*](canvas.htm#M100) 
[**-dash** *pattern*](canvas.htm#M101) 
[**-activedash** *pattern*](canvas.htm#M102) 
[**-disableddash** *pattern*](canvas.htm#M103) 
[**-dashoffset** *offset*](canvas.htm#M104) 
[**-fill** *color*](canvas.htm#M105) 
[**-activefill** *color*](canvas.htm#M106) 
[**-disabledfill** *color*](canvas.htm#M107) 
[**-outline** *color*](canvas.htm#M108) 
[**-activeoutline** *color*](canvas.htm#M109) 
[**-disabledoutline** *color*](canvas.htm#M110) 
[**-offset** *offset*](canvas.htm#M111) 
[**-outlinestipple** *bitmap*](canvas.htm#M112) 
[**-activeoutlinestipple** *bitmap*](canvas.htm#M113) 
[**-disabledoutlinestipple** *bitmap*](canvas.htm#M114) 
[**-outlineoffset** *offset*](canvas.htm#M115) 
[**-stipple** *bitmap*](canvas.htm#M116) 
[**-activestipple** *bitmap*](canvas.htm#M117) 
[**-disabledstipple** *bitmap*](canvas.htm#M118) 
[**-state** *state*](canvas.htm#M119) 
[**-tags** *tagList*](canvas.htm#M120) 
[**-width** *outlineWidth*](canvas.htm#M121) 
[**-activewidth** *outlineWidth*](canvas.htm#M122) 
[**-disabledwidth** *outlineWidth*](canvas.htm#M123) 























 
[STANDARD ITEM TYPES](canvas.htm#M124) 
[ARC ITEMS](canvas.htm#M125)  
[**-extent** *degrees*](canvas.htm#M126) 
[**-start** *degrees*](canvas.htm#M127) 
[**-style** *type*](canvas.htm#M128) 


 
[BITMAP ITEMS](canvas.htm#M129)  
[**-background** *color*](canvas.htm#M130) 
[**-activebackground** *color*](canvas.htm#M131) 
[**-disabledbackground** *color*](canvas.htm#M132) 
[**-bitmap** *bitmap*](canvas.htm#M133) 
[**-activebitmap** *bitmap*](canvas.htm#M134) 
[**-disabledbitmap** *bitmap*](canvas.htm#M135) 
[**-foreground** *color*](canvas.htm#M136) 
[**-activeforeground** *color*](canvas.htm#M137) 
[**-disabledforeground** *color*](canvas.htm#M138) 








 
[IMAGE ITEMS](canvas.htm#M139)  
[**-image** *name*](canvas.htm#M140) 
[**-activeimage** *name*](canvas.htm#M141) 
[**-disabledimage** *name*](canvas.htm#M142) 


 
[LINE ITEMS](canvas.htm#M143)  
[**-arrow** *where*](canvas.htm#M144) 
[**-arrowshape** *shape*](canvas.htm#M145) 
[**-capstyle** *style*](canvas.htm#M146) 
[**-joinstyle** *style*](canvas.htm#M147) 
[**-smooth** *smoothMethod*](canvas.htm#M148) 
[**-splinesteps** *number*](canvas.htm#M149) 





 
[OVAL ITEMS](canvas.htm#M150) 
[POLYGON ITEMS](canvas.htm#M151)  
[**-joinstyle** *style*](canvas.htm#M152) 
[**-smooth** *boolean*](canvas.htm#M153) 
[**-splinesteps** *number*](canvas.htm#M154) 


 
[RECTANGLE ITEMS](canvas.htm#M155) 
[TEXT ITEMS](canvas.htm#M156)  
[**-angle** *rotationDegrees*](canvas.htm#M157) 
[**-font** *fontName*](canvas.htm#M158) 
[**-justify** *how*](canvas.htm#M159) 
[**-text** *string*](canvas.htm#M160) 
[**-underline**](canvas.htm#M161)  
[**-width** *lineLength*](canvas.htm#M162) 





 
[WINDOW ITEMS](canvas.htm#M163)  
[**-height** *pixels*](canvas.htm#M164) 
[**-width** *pixels*](canvas.htm#M165) 
[**-window** *pathName*](canvas.htm#M166) 


 
[APPLICATION-DEFINED ITEM TYPES](canvas.htm#M167) 
[BINDINGS](canvas.htm#M168) 
[CREDITS](canvas.htm#M169) 
[SEE ALSO](canvas.htm#M170) 
[KEYWORDS](canvas.htm#M171) 




























 Name
----

 canvas — Create and manipulate 'canvas' hypergraphics drawing surface widgets Synopsis
--------

 **canvas** *pathName* ?*options*?  
 Standard options
----------------

  
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-insertbackground, insertBackground, Foreground](options.htm#M-insertbackground)** 
**[-insertborderwidth, insertBorderWidth, BorderWidth](options.htm#M-insertborderwidth)** 
**[-insertofftime, insertOffTime, OffTime](options.htm#M-insertofftime)** 
**[-insertontime, insertOnTime, OnTime](options.htm#M-insertontime)** 
**[-insertwidth, insertWidth, InsertWidth](options.htm#M-insertwidth)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground)** 
**[-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth)** 
**[-selectforeground, selectForeground, Background](options.htm#M-selectforeground)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand)** 
**[-yscrollcommand, yScrollCommand, ScrollCommand](options.htm#M-yscrollcommand)** 

















 Widget-specific options
-----------------------

  Command-Line Name: **-closeenough** Database Name: **closeEnough** Database Class: **CloseEnough** 


Specifies a floating-point value indicating how close the mouse cursor must be to an item before it is considered to be “inside” the item. Defaults to 1.0. 

Command-Line Name: **-confine** Database Name: **confine** Database Class: **Confine** 


Specifies a boolean value that indicates whether or not it should be allowable to set the canvas's view outside the region defined by the **scrollRegion** argument. Defaults to true, which means that the view will be constrained within the scroll region. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies a desired window height that the canvas widget should request from its geometry manager. The value may be specified in any of the forms described in the **[COORDINATES](#M17)** section below. 

Command-Line Name: **-scrollregion** Database Name: **scrollRegion** Database Class: **ScrollRegion** 


Specifies a list with four coordinates describing the left, top, right, and bottom coordinates of a rectangular region. This region is used for scrolling purposes and is considered to be the boundary of the information in the canvas. Each of the coordinates may be specified in any of the forms given in the **[COORDINATES](#M17)** section below. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Modifies the default state of the canvas where *state* may be set to one of: **normal**, **disabled**, or **hidden**. Individual canvas objects all have their own state option which may override the default state. Many options can take separate specifications such that the appearance of the item can be different in different situations. The options that start with **active** control the appearance when the mouse pointer is over it, while the option starting with **disabled** controls the appearance when the state is disabled. Canvas items which are **disabled** will not react to canvas bindings. 

Command-Line Name: **-width** Database Name: **width** Database Class: **width** 


Specifies a desired window width that the canvas widget should request from its geometry manager. The value may be specified in any of the forms described in the **[COORDINATES](#M17)** section below. 

Command-Line Name: **-xscrollincrement** Database Name: **xScrollIncrement** Database Class: **ScrollIncrement** 


Specifies an increment for horizontal scrolling, in any of the usual forms permitted for screen distances. If the value of this option is greater than zero, the horizontal view in the window will be constrained so that the canvas x coordinate at the left edge of the window is always an even multiple of **xScrollIncrement**; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar are selected) will also be **xScrollIncrement**. If the value of this option is less than or equal to zero, then horizontal scrolling is unconstrained. 

Command-Line Name: **-yscrollincrement** Database Name: **yScrollIncrement** Database Class: **ScrollIncrement** 


Specifies an increment for vertical scrolling, in any of the usual forms permitted for screen distances. If the value of this option is greater than zero, the vertical view in the window will be constrained so that the canvas y coordinate at the top edge of the window is always an even multiple of **yScrollIncrement**; furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will also be **yScrollIncrement**. If the value of this option is less than or equal to zero, then vertical scrolling is unconstrained. 
 Introduction
------------

 The **canvas** command creates a new window (given by the *pathName* argument) and makes it into a canvas widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the canvas such as its colors and 3-D relief. The **canvas** command returns its *pathName* argument. At the time this command is invoked, there must not exist a window named *pathName*, but *pathName*'s parent must exist.  Canvas widgets implement structured graphics. A canvas displays any number of *items*, which may be things like rectangles, circles, lines, and text. Items may be manipulated (e.g. moved or re-colored) and commands may be associated with items in much the same way that the **[bind](bind.htm)** command allows commands to be bound to widgets. For example, a particular command may be associated with the <Button-1> event so that the command is invoked whenever button 1 is pressed with the mouse cursor over an item. This means that items in a canvas can have behaviors defined by the Tcl scripts bound to them. 


Display list
------------

 The items in a canvas are ordered for purposes of display, with the first item in the display list being displayed first, followed by the next item in the list, and so on. Items later in the display list obscure those that are earlier in the display list and are sometimes referred to as being “on top” of earlier items. When a new item is created it is placed at the end of the display list, on top of everything else. Widget commands may be used to re-arrange the order of the display list.  Window items are an exception to the above rules. The underlying window systems require them always to be drawn on top of other items. In addition, the stacking order of window items is not affected by any of the canvas widget commands; you must use the Tk **[raise](raise.htm)** command and **[lower](lower.htm)** command instead. 


Item ids and tags
-----------------

 Items in a canvas widget may be named in either of two ways: by id or by tag. Each item has a unique identifying number, which is assigned to that item when it is created. The id of an item never changes and id numbers are never re-used within the lifetime of a canvas widget.  Each item may also have any number of *tags* associated with it. A tag is just a string of characters, and it may take any form except that of an integer. For example, “x123” is OK but “123” is not. The same tag may be associated with many different items. This is commonly done to group items in various interesting ways; for example, all selected items might be given the tag “selected”. 


 The tag **all** is implicitly associated with every item in the canvas; it may be used to invoke operations on all the items in the canvas. 


 The tag **current** is managed automatically by Tk; it applies to the *current item*, which is the topmost item whose drawn area covers the position of the mouse cursor (different item types interpret this in varying ways; see the individual item type documentation for details). If the mouse is not in the canvas widget or is not over an item, then no item has the **current** tag. 


 When specifying items in canvas widget commands, if the specifier is an integer then it is assumed to refer to the single item with that id. If the specifier is not an integer, then it is assumed to refer to all of the items in the canvas that have a tag matching the specifier. The symbol *tagOrId* is used below to indicate that an argument specifies either an id that selects a single item or a tag that selects zero or more items. 


 *tagOrId* may contain a logical expressions of tags by using operators: “**&&**”, “**||**”, “**^**”, “**!**”, and parenthesized subexpressions. For example: 



```
.c find withtag {(a&&!b)||(!a&&b)}
```
 or equivalently: 
```
.c find withtag {a^b}
```
 will find only those items with either “a” or “b” tags, but not both.  Some widget commands only operate on a single item at a time; if *tagOrId* is specified in a way that names multiple items, then the normal behavior is for the command to use the first (lowest) of these items in the display list that is suitable for the command. Exceptions are noted in the widget command descriptions below. 


Coordinates
-----------

 All coordinates related to canvases are stored as floating-point numbers. Coordinates and distances are specified in screen units, which are floating-point numbers optionally followed by one of several letters. If no letter is supplied then the distance is in pixels. If the letter is **m** then the distance is in millimeters on the screen; if it is **c** then the distance is in centimeters; **i** means inches, and **p** means printers points (1/72 inch). Larger y-coordinates refer to points lower on the screen; larger x-coordinates refer to points farther to the right. Coordinates can be specified either as an even number of parameters, or as a single list parameter containing an even number of x and y coordinate values. ### Transformations

 Normally the origin of the canvas coordinate system is at the upper-left corner of the window containing the canvas. It is possible to adjust the origin of the canvas coordinate system relative to the origin of the window using the **xview** and **yview** widget commands; this is typically used for scrolling. Canvases do not support scaling or rotation of the canvas coordinate system relative to the window coordinate system.  Individual items may be moved or scaled using widget commands described below, but they may not be rotated. 


 Note that the default origin of the canvas's visible area is coincident with the origin for the whole window as that makes bindings using the mouse position easier to work with; you only need to use the **canvasx** and **canvasy** widget commands if you adjust the origin of the visible area. However, this also means that any focus ring (as controlled by the **-highlightthickness** option) and window border (as controlled by the **-borderwidth** option) must be taken into account before you get to the visible area of the canvas. 


Indices
-------

 Text items support the notion of an *index* for identifying particular positions within the item. In a similar fashion, line and polygon items support *index* for identifying, inserting and deleting subsets of their coordinates. Indices are used for commands such as inserting or deleting a range of characters or coordinates, and setting the insertion cursor position. An index may be specified in any of a number of ways, and different types of items may support different forms for specifying indices. Text items support the following forms for an index; if you define new types of text-like items, it would be advisable to support as many of these forms as practical. Note that it is possible to refer to the character just after the last one in the text item; this is necessary for such tasks as inserting new text at the end of the item. Lines and Polygons do not support the insertion cursor and the selection. Their indices are supposed to be even always, because coordinates always appear in pairs. 
 *number*
 A decimal number giving the position of the desired character within the text item. 0 refers to the first character, 1 to the next character, and so on. If indexes are odd for lines and polygons, they will be automatically decremented by one. A number less than 0 is treated as if it were zero, and a number greater than the length of the text item is treated as if it were equal to the length of the text item. For polygons, numbers less than 0 or greater than the length of the coordinate list will be adjusted by adding or subtracting the length until the result is between zero and the length, inclusive. 

**end**
 Refers to the character or coordinate just after the last one in the item (same as the number of characters or coordinates in the item). 

**insert**
 Refers to the character just before which the insertion cursor is drawn in this item. Not valid for lines and polygons. 

**sel.first**
 Refers to the first selected character in the item. If the selection is not in this item then this form is illegal. 

**sel.last**
 Refers to the last selected character in the item. If the selection is not in this item then this form is illegal. 


**@***x,y*

 Refers to the character or coordinate at the point given by *x* and *y*, where *x* and *y* are specified in the coordinate system of the canvas. If *x* and *y* lie outside the coordinates covered by the text item, then they refer to the first or last character in the line that is closest to the given point. 

 Dash patterns
-------------

 Many items support the notion of a dash pattern for outlines.  The first possible syntax is a list of integers. Each element represents the number of pixels of a line segment. Only the odd segments are drawn using the “outline” color. The other segments are drawn transparent. 


 The second possible syntax is a character list containing only 5 possible characters “**.,-\_** ”. The space can be used to enlarge the space between other line elements, and cannot occur as the first position in the string. Some examples: 



```
-dash .     → -dash {2 4}
-dash -     → -dash {6 4}
-dash -.    → -dash {6 4 2 4}
-dash -..   → -dash {6 4 2 4 2 4}
-dash {. }  → -dash {2 8}
-dash ,     → -dash {4 4}
```
  The main difference of this syntax with the previous is that it is shape-conserving. This means that all values in the dash list will be multiplied by the line width before display. This assures that “.” will always be displayed as a dot and “-” always as a dash regardless of the line width. 


 On systems which support only a limited set of dash patterns, the dash pattern will be displayed as the closest dash pattern that is available. For example, on Windows only the first 4 of the above examples are available. The last 2 examples will be displayed identically to the first one. 


Widget command
--------------

 The **canvas** command creates a new Tcl command whose name is *pathName*. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *Option* and the *arg*s determine the exact behavior of the command. The following widget commands are possible for canvas widgets: 
 
*pathName* **addtag** *tag searchSpec* ?*arg arg ...*?
 For each item that meets the constraints specified by *searchSpec* and the *arg*s, add *tag* to the list of tags associated with the item if it is not already present on that list. It is possible that no items will satisfy the constraints given by *searchSpec* and *arg*s, in which case the command has no effect. This command returns an empty string as result. *SearchSpec* and *arg*'s may take any of the following forms: 
 
**above** *tagOrId*

 Selects the item just after (above) the one given by *tagOrId* in the display list. If *tagOrId* denotes more than one item, then the last (topmost) of these items in the display list is used. 

**all**
 Selects all the items in the canvas. 


**below** *tagOrId*

 Selects the item just before (below) the one given by *tagOrId* in the display list. If *tagOrId* denotes more than one item, then the first (lowest) of these items in the display list is used. 


**closest** *x y* ?*halo*? ?*start*?
 Selects the item closest to the point given by *x* and *y*. If more than one item is at the same closest distance (e.g. two items overlap the point), then the top-most of these items (the last one in the display list) is used. If *halo* is specified, then it must be a non-negative value. Any item closer than *halo* to the point is considered to overlap it. The *start* argument may be used to step circularly through all the closest items. If *start* is specified, it names an item using a tag or id (if by tag, it selects the first item in the display list with the given tag). Instead of selecting the topmost closest item, this form will select the topmost closest item that is below *start* in the display list; if no such item exists, then the selection behaves as if the *start* argument had not been specified. 


**enclosed** *x1* *y1* *x2* *y2*

 Selects all the items completely enclosed within the rectangular region given by *x1*, *y1*, *x2*, and *y2*. *X1* must be no greater than *x2* and *y1* must be no greater than *y2*. 


**overlapping** *x1* *y1* *x2* *y2*

 Selects all the items that overlap or are enclosed within the rectangular region given by *x1*, *y1*, *x2*, and *y2*. *X1* must be no greater than *x2* and *y1* must be no greater than *y2*. 


**withtag** *tagOrId*

 Selects all the items given by *tagOrId*. 




*pathName* **bbox** *tagOrId* ?*tagOrId tagOrId ...*?
 Returns a list with four elements giving an approximate bounding box for all the items named by the *tagOrId* arguments. The list has the form “*x1 y1 x2 y2*” such that the drawn areas of all the named elements are within the region bounded by *x1* on the left, *x2* on the right, *y1* on the top, and *y2* on the bottom. The return value may overestimate the actual bounding box by a few pixels. If no items match any of the *tagOrId* arguments or if the matching items have empty bounding boxes (i.e. they have nothing to display) then an empty string is returned. 


*pathName* **bind** *tagOrId* ?*sequence*? ?*command*?
 This command associates *command* with all the items given by *tagOrId* such that whenever the event sequence given by *sequence* occurs for one of the items the command will be invoked. This widget command is similar to the **[bind](bind.htm)** command except that it operates on items in a canvas rather than entire widgets. See the **[bind](bind.htm)** manual entry for complete details on the syntax of *sequence* and the substitutions performed on *command* before invoking it. If all arguments are specified then a new binding is created, replacing any existing binding for the same *sequence* and *tagOrId* (if the first character of *command* is “+” then *command* augments an existing binding rather than replacing it). In this case the return value is an empty string. If *command* is omitted then the command returns the *command* associated with *tagOrId* and *sequence* (an error occurs if there is no such binding). If both *command* and *sequence* are omitted then the command returns a list of all the sequences for which bindings have been defined for *tagOrId*.  The only events for which bindings may be specified are those related to the mouse and keyboard (such as **Enter**, **Leave**, **ButtonPress**, **Motion**, and **KeyPress**) or virtual events. The handling of events in canvases uses the current item defined in **[ITEM IDS AND TAGS](#M16)** above. **Enter** and **Leave** events trigger for an item when it becomes the current item or ceases to be the current item; note that these events are different than **Enter** and **Leave** events for windows. Mouse-related events are directed to the current item, if any. Keyboard-related events are directed to the focus item, if any (see the **focus** widget command below for more on this). If a virtual event is used in a binding, that binding can trigger only if the virtual event is defined by an underlying mouse-related or keyboard-related event. 


 It is possible for multiple bindings to match a particular event. This could occur, for example, if one binding is associated with the item's id and another is associated with one of the item's tags. When this occurs, all of the matching bindings are invoked. A binding associated with the **all** tag is invoked first, followed by one binding for each of the item's tags (in order), followed by a binding associated with the item's id. If there are multiple matching bindings for a single tag, then only the most specific binding is invoked. A **[continue](../tclcmd/continue.htm)** command in a binding script terminates that script, and a **[break](../tclcmd/break.htm)** command terminates that script and skips any remaining scripts for the event, just as for the **[bind](bind.htm)** command. 


If bindings have been created for a canvas window using the **[bind](bind.htm)** command, then they are invoked in addition to bindings created for the canvas's items using the **bind** widget command. The bindings for items will be invoked before any of the bindings for the window as a whole. 




*pathName* **canvasx** *screenx* ?*gridspacing*?
 Given a window x-coordinate in the canvas *screenx*, this command returns the canvas x-coordinate that is displayed at that location. If *gridspacing* is specified, then the canvas coordinate is rounded to the nearest multiple of *gridspacing* units. 


*pathName* **canvasy** *screeny* ?*gridspacing*?
 Given a window y-coordinate in the canvas *screeny* this command returns the canvas y-coordinate that is displayed at that location. If *gridspacing* is specified, then the canvas coordinate is rounded to the nearest multiple of *gridspacing* units. 


*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **canvas** command. 


*pathName* **configure ?***option*? ?*value*? ?*option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **canvas** command. 


*pathName* **coords** *tagOrId* ?*x0 y0 ...*?

*pathName* **coords** *tagOrId* ?*coordList*?
 Query or modify the coordinates that define an item. If no coordinates are specified, this command returns a list whose elements are the coordinates of the item named by *tagOrId*. If coordinates are specified, then they replace the current coordinates for the named item. If *tagOrId* refers to multiple items, then the first one in the display list is used. 


*pathName* **create** *type x y* ?*x y ...*? ?*option value ...*?

*pathName* **create** *type coordList* ?*option value ...*?
 Create a new item in *pathName* of type *type*. The exact format of the arguments after *type* depends on *type*, but usually they consist of the coordinates for one or more points, followed by specifications for zero or more item options. See the subsections on individual item types below for more on the syntax of this command. This command returns the id for the new item. 


*pathName* **dchars** *tagOrId first* ?*last*?
 For each item given by *tagOrId*, delete the characters, or coordinates, in the range given by *first* and *last*, inclusive. If some of the items given by *tagOrId* do not support indexing operations then they ignore this operation. Text items interpret *first* and *last* as indices to a character, line and polygon items interpret them as indices to a coordinate (an x,y pair). Indices are described in **[INDICES](#M19)** above. If *last* is omitted, it defaults to *first*. This command returns an empty string. 


*pathName* **delete** ?*tagOrId tagOrId ...*?
 Delete each of the items given by each *tagOrId*, and return an empty string. 


*pathName* **dtag** *tagOrId* ?*tagToDelete*?
 For each of the items given by *tagOrId*, delete the tag given by *tagToDelete* from the list of those associated with the item. If an item does not have the tag *tagToDelete* then the item is unaffected by the command. If *tagToDelete* is omitted then it defaults to *tagOrId*. This command returns an empty string. 


*pathName* **find** *searchCommand* ?*arg arg ...*?
 This command returns a list consisting of all the items that meet the constraints specified by *searchCommand* and *arg*'s. *SearchCommand* and *args* have any of the forms accepted by the **addtag** command. The items are returned in stacking order, with the lowest item first. 


*pathName* **focus** ?*tagOrId*?
 Set the keyboard focus for the canvas widget to the item given by *tagOrId*. If *tagOrId* refers to several items, then the focus is set to the first such item in the display list that supports the insertion cursor. If *tagOrId* does not refer to any items, or if none of them support the insertion cursor, then the focus is not changed. If *tagOrId* is an empty string, then the focus item is reset so that no item has the focus. If *tagOrId* is not specified then the command returns the id for the item that currently has the focus, or an empty string if no item has the focus.  Once the focus has been set to an item, the item will display the insertion cursor and all keyboard events will be directed to that item. The focus item within a canvas and the focus window on the screen (set with the **[focus](focus.htm)** command) are totally independent: a given item does not actually have the input focus unless (a) its canvas is the focus window and (b) the item is the focus item within the canvas. In most cases it is advisable to follow the **focus** widget command with the **[focus](focus.htm)** command to set the focus window to the canvas (if it was not there already). 




*pathName* **gettags** *tagOrId*

 Return a list whose elements are the tags associated with the item given by *tagOrId*. If *tagOrId* refers to more than one item, then the tags are returned from the first such item in the display list. If *tagOrId* does not refer to any items, or if the item contains no tags, then an empty string is returned. 


*pathName* **icursor** *tagOrId index*

 Set the position of the insertion cursor for the item(s) given by *tagOrId* to just before the character whose position is given by *index*. If some or all of the items given by *tagOrId* do not support an insertion cursor then this command has no effect on them. See **[INDICES](#M19)** above for a description of the legal forms for *index*. Note: the insertion cursor is only displayed in an item if that item currently has the keyboard focus (see the **focus** widget command, above), but the cursor position may be set even when the item does not have the focus. This command returns an empty string. 


*pathName* **imove** *tagOrId index x y*

 This command causes the *index*'th coordinate of each of the items indicated by *tagOrId* to be relocated to the location (*x*,*y*). Each item interprets *index* independently according to the rules described in **[INDICES](#M19)** above. Out of the standard set of items, only line and polygon items may have their coordinates relocated this way. 


*pathName* **index** *tagOrId index*

 This command returns a decimal string giving the numerical index within *tagOrId* corresponding to *index*. *Index* gives a textual description of the desired position as described in **[INDICES](#M19)** above. Text items interpret *index* as an index to a character, line and polygon items interpret it as an index to a coordinate (an x,y pair). The return value is guaranteed to lie between 0 and the number of characters, or coordinates, within the item, inclusive. If *tagOrId* refers to multiple items, then the index is processed in the first of these items that supports indexing operations (in display list order). 


*pathName* **insert** *tagOrId beforeThis string*

 For each of the items given by *tagOrId*, if the item supports text or coordinate, insertion then *string* is inserted into the item's text just before the character, or coordinate, whose index is *beforeThis*. Text items interpret *beforeThis* as an index to a character, line and polygon items interpret it as an index to a coordinate (an x,y pair). For lines and polygons the *string* must be a valid coordinate sequence. See **[INDICES](#M19)** above for information about the forms allowed for *beforeThis*. This command returns an empty string. 


*pathName* **itemcget** *tagOrId* *option*

 Returns the current value of the configuration option for the item given by *tagOrId* whose name is *option*. This command is similar to the **cget** widget command except that it applies to a particular item rather than the widget as a whole. *Option* may have any of the values accepted by the **create** widget command when the item was created. If *tagOrId* is a tag that refers to more than one item, the first (lowest) such item is used. 


*pathName* **itemconfigure** *tagOrId* ?*option*? ?*value*? ?*option value ...*?
 This command is similar to the **configure** widget command except that it modifies item-specific options for the items given by *tagOrId* instead of modifying options for the overall canvas widget. If no *option* is specified, returns a list describing all of the available options for the first item given by *tagOrId* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s) in each of the items given by *tagOrId*; in this case the command returns an empty string. The *option*s and *value*s are the same as those permissible in the **create** widget command when the item(s) were created; see the sections describing individual item types below for details on the legal options. 


*pathName* **lower** *tagOrId* ?*belowThis*?
 Move all of the items given by *tagOrId* to a new position in the display list just before the item given by *belowThis*. If *tagOrId* refers to more than one item then all are moved but the relative order of the moved items will not be changed. *BelowThis* is a tag or id; if it refers to more than one item then the first (lowest) of these items in the display list is used as the destination location for the moved items. Note: this command has no effect on window items. Window items always obscure other item types, and the stacking order of window items is determined by the **[raise](raise.htm)** command and **[lower](lower.htm)** command, not the **raise** widget command and **lower** widget command for canvases. This command returns an empty string. 


*pathName* **move** *tagOrId xAmount yAmount*

 Move each of the items given by *tagOrId* in the canvas coordinate space by adding *xAmount* to the x-coordinate of each point associated with the item and *yAmount* to the y-coordinate of each point associated with the item. This command returns an empty string. 


*pathName* **moveto** *tagOrId xPos yPos*

 Move the items given by *tagOrId* in the canvas coordinate space so that the first coordinate pair of the bottommost item with tag *tagOrId* is located at position (*xPos*,*yPos*). *xPos* and *yPos* may be the empty string, in which case the corresponding coordinate will be unchanged. All items matching *tagOrId* remain in the same positions relative to each other. This command returns an empty string. 


*pathName* **postscript** ?*option value option value ...*?
 Generate a Postscript representation for part or all of the canvas. If the **-file** option is specified then the Postscript is written to a file and an empty string is returned; otherwise the Postscript is returned as the result of the command. If the interpreter that owns the canvas is marked as safe, the operation will fail because safe interpreters are not allowed to write files. If the **-channel** option is specified, the argument denotes the name of a channel already opened for writing. The Postscript is written to that channel, and the channel is left open for further writing at the end of the operation. The Postscript is created in Encapsulated Postscript form using version 3.0 of the Document Structuring Conventions. Note: by default Postscript is only generated for information that appears in the canvas's window on the screen. If the canvas is freshly created it may still have its initial size of 1x1 pixel so nothing will appear in the Postscript. To get around this problem either invoke the **[update](../tclcmd/update.htm)** command to wait for the canvas window to reach its final size, or else use the **-width** and **-height** options to specify the area of the canvas to print. The *option*-*value* argument pairs provide additional information to control the generation of Postscript. The following options are supported: 
 
**-channel** *channelName*

 Specifies the name of the channel to which to write the Postscript. If this option and the **-file** option are not specified then the Postscript is returned as the result of the command. 


**-colormap** *varName*

 *VarName* must be the name of an array variable that specifies a color mapping to use in the Postscript. Each element of *varName* must consist of Postscript code to set a particular color value (e.g. “**1.0 1.0 0.0 setrgbcolor**”). When outputting color information in the Postscript, Tk checks to see if there is an element of *varName* with the same name as the color. If so, Tk uses the value of the element as the Postscript command to set the color. If this option has not been specified, or if there is no entry in *varName* for a given color, then Tk uses the red, green, and blue intensities from the X color. 


**-colormode** *mode*

 Specifies how to output color information. *Mode* must be either **color** (for full color output), **gray** (convert all colors to their gray-scale equivalents) or **mono** (convert all colors to black or white). 


**-file** *fileName*

 Specifies the name of the file in which to write the Postscript. If this option and the **-channel** option are not specified then the Postscript is returned as the result of the command. 


**-fontmap** *varName*

 *VarName* must be the name of an array variable that specifies a font mapping to use in the Postscript. Each element of *varName* must consist of a Tcl list with two elements, which are the name and point size of a Postscript font. When outputting Postscript commands for a particular font, Tk checks to see if *varName* contains an element with the same name as the font. If there is such an element, then the font information contained in that element is used in the Postscript. Otherwise Tk attempts to guess what Postscript font to use. Tk's guesses generally only work for well-known fonts such as Times and Helvetica and Courier, and only if the X font name does not omit any dashes up through the point size. For example, **-\*-Courier-Bold-R-Normal--\*-120-\*** will work but **\*Courier-Bold-R-Normal\*120\*** will not; Tk needs the dashes to parse the font name). 


**-height** *size*

 Specifies the height of the area of the canvas to print. Defaults to the height of the canvas window. 


**-pageanchor** *anchor*

 Specifies which point of the printed area of the canvas should appear over the positioning point on the page (which is given by the **-pagex** and **-pagey** options). For example, **-pageanchor n** means that the top center of the area of the canvas being printed (as it appears in the canvas window) should be over the positioning point. Defaults to **center**. 


**-pageheight** *size*

 Specifies that the Postscript should be scaled in both x and y so that the printed area is *size* high on the Postscript page. *Size* consists of a floating-point number followed by **c** for centimeters, **i** for inches, **m** for millimeters, or **p** or nothing for printer's points (1/72 inch). Defaults to the height of the printed area on the screen. If both **-pageheight** and **-pagewidth** are specified then the scale factor from **-pagewidth** is used (non-uniform scaling is not implemented). 


**-pagewidth** *size*

 Specifies that the Postscript should be scaled in both x and y so that the printed area is *size* wide on the Postscript page. *Size* has the same form as for **-pageheight**. Defaults to the width of the printed area on the screen. If both **-pageheight** and **-pagewidth** are specified then the scale factor from **-pagewidth** is used (non-uniform scaling is not implemented). 


**-pagex** *position*

 *Position* gives the x-coordinate of the positioning point on the Postscript page, using any of the forms allowed for **-pageheight**. Used in conjunction with the **-pagey** and **-pageanchor** options to determine where the printed area appears on the Postscript page. Defaults to the center of the page. 


**-pagey** *position*

 *Position* gives the y-coordinate of the positioning point on the Postscript page, using any of the forms allowed for **-pageheight**. Used in conjunction with the **-pagex** and **-pageanchor** options to determine where the printed area appears on the Postscript page. Defaults to the center of the page. 


**-rotate** *boolean*

 *Boolean* specifies whether the printed area is to be rotated 90 degrees. In non-rotated output the x-axis of the printed area runs along the short dimension of the page (“portrait” orientation); in rotated output the x-axis runs along the long dimension of the page (“landscape” orientation). Defaults to non-rotated. 


**-width** *size*

 Specifies the width of the area of the canvas to print. Defaults to the width of the canvas window. 


**-x** *position*

 Specifies the x-coordinate of the left edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the left edge of the window. 


**-y** *position*

 Specifies the y-coordinate of the top edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the top edge of the window. 




*pathName* **raise** *tagOrId* ?*aboveThis*?
 Move all of the items given by *tagOrId* to a new position in the display list just after the item given by *aboveThis*. If *tagOrId* refers to more than one item then all are moved but the relative order of the moved items will not be changed. *AboveThis* is a tag or id; if it refers to more than one item then the last (topmost) of these items in the display list is used as the destination location for the moved items. This command returns an empty string.  Note: this command has no effect on window items. Window items always obscure other item types, and the stacking order of window items is determined by the **[raise](raise.htm)** command and **[lower](lower.htm)** command, not the **raise** widget command and **lower** widget command for canvases. 




*pathName* **rchars** *tagOrId first last string*

 This command causes the text or coordinates between *first* and *last* for each of the items indicated by *tagOrId* to be replaced by *string*. Each item interprets *first* and *last* independently according to the rules described in **[INDICES](#M19)** above. Out of the standard set of items, text items support this operation by altering their text as directed, and line and polygon items support this operation by altering their coordinate list (in which case *string* should be a list of coordinates to use as a replacement). The other items ignore this operation. 


*pathName* **scale** *tagOrId xOrigin yOrigin xScale yScale*

 Rescale the coordinates of all of the items given by *tagOrId* in canvas coordinate space. *XOrigin* and *yOrigin* identify the origin for the scaling operation and *xScale* and *yScale* identify the scale factors for x- and y-coordinates, respectively (a scale factor of 1.0 implies no change to that coordinate). For each of the points defining each item, the x-coordinate is adjusted to change the distance from *xOrigin* by a factor of *xScale*. Similarly, each y-coordinate is adjusted to change the distance from *yOrigin* by a factor of *yScale*. This command returns an empty string.  Note that some items have only a single pair of coordinates (e.g., text, images and windows) and so scaling of them by this command can only move them around. 




*pathName* **scan** *option args*

 This command is used to implement scanning on canvases. It has two forms, depending on *option*: 
 
*pathName* **scan mark** *x y*

 Records *x* and *y* and the canvas's current view; used in conjunction with later **scan dragto** commands. Typically this command is associated with a mouse button press in the widget and *x* and *y* are the coordinates of the mouse. It returns an empty string. 


*pathName* **scan dragto** *x y ?gain?*

 This command computes the difference between its *x* and *y* arguments (which are typically mouse coordinates) and the *x* and *y* arguments to the last **scan mark** command for the widget. It then adjusts the view by *gain* times the difference in coordinates, where *gain* defaults to 10. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the canvas at high speed through its window. The return value is an empty string. 




*pathName* **select** *option* ?*tagOrId arg*?
 Manipulates the selection in one of several ways, depending on *option*. The command may take any of the forms described below. In all of the descriptions below, *tagOrId* must refer to an item that supports indexing and selection; if it refers to multiple items then the first of these that supports indexing and the selection is used. *Index* gives a textual description of a position within *tagOrId*, as described in **[INDICES](#M19)** above. 
 
*pathName* **select adjust** *tagOrId index*

 Locate the end of the selection in *tagOrId* nearest to the character given by *index*, and adjust that end of the selection to be at *index* (i.e. including but not going beyond *index*). The other end of the selection is made the anchor point for future **select to** commands. If the selection is not currently in *tagOrId* then this command behaves the same as the **select to** widget command. Returns an empty string. 


*pathName* **select clear**

 Clear the selection if it is in this widget. If the selection is not in this widget then the command has no effect. Returns an empty string. 


*pathName* **select from** *tagOrId index*

 Set the selection anchor point for the widget to be just before the character given by *index* in the item given by *tagOrId*. This command does not change the selection; it just sets the fixed end of the selection for future **select to** commands. Returns an empty string. 


*pathName* **select item**

 Returns the id of the selected item, if the selection is in an item in this canvas. If the selection is not in this canvas then an empty string is returned. 


*pathName* **select to** *tagOrId index*

 Set the selection to consist of those characters of *tagOrId* between the selection anchor point and *index*. The new selection will include the character given by *index*; it will include the character given by the anchor point only if *index* is greater than or equal to the anchor point. The anchor point is determined by the most recent **select adjust** or **select from** command for this widget. If the selection anchor point for the widget is not currently in *tagOrId*, then it is set to the same character given by *index*. Returns an empty string. 




*pathName* **type** *tagOrId*

 Returns the type of the item given by *tagOrId*, such as **rectangle** or **text**. If *tagOrId* refers to more than one item, then the type of the first item in the display list is returned. If *tagOrId* does not refer to any items at all then an empty string is returned. 


*pathName* **xview** ?*args*?
 This command is used to query and change the horizontal position of the information displayed in the canvas's window. It can take any of the following forms: 
 
*pathName* **xview**

 Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the canvas's area (as defined by the **-scrollregion** option) is off-screen to the left, the middle 40% is visible in the window, and 40% of the canvas is off-screen to the right. These are the same values passed to scrollbars via the **-xscrollcommand** option. 


*pathName* **xview moveto** *fraction*

 Adjusts the view in the window so that *fraction* of the total width of the canvas is off-screen to the left. *Fraction* must be a fraction between 0 and 1. 


*pathName* **xview scroll** *number what*

 This command shifts the view in the window left or right according to *number* and *what*. *Number* must be an integer. *What* must be either **units** or **pages** or an abbreviation of one of these. If *what* is **units**, the view adjusts left or right in units of the **xScrollIncrement** option, if it is greater than zero, or in units of one-tenth the window's width otherwise. If *what is* **pages** then the view adjusts in units of nine-tenths the window's width. If *number* is negative then information farther to the left becomes visible; if it is positive then information farther to the right becomes visible. 




*pathName* **yview** *?args*?
 This command is used to query and change the vertical position of the information displayed in the canvas's window. It can take any of the following forms: 
 
*pathName* **yview**

 Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the vertical span that is visible in the window. For example, if the first element is .6 and the second element is 1.0, the lowest 40% of the canvas's area (as defined by the **-scrollregion** option) is visible in the window. These are the same values passed to scrollbars via the **-yscrollcommand** option. 


*pathName* **yview moveto** *fraction*

 Adjusts the view in the window so that *fraction* of the canvas's area is off-screen to the top. *Fraction* is a fraction between 0 and 1. 


*pathName* **yview scroll** *number what*

 This command adjusts the view in the window up or down according to *number* and *what*. *Number* must be an integer. *What* must be either **units** or **pages**. If *what* is **units**, the view adjusts up or down in units of the **yScrollIncrement** option, if it is greater than zero, or in units of one-tenth the window's height otherwise. If *what* is **pages** then the view adjusts in units of nine-tenths the window's height. If *number* is negative then higher information becomes visible; if it is positive then lower information becomes visible. 



 Overview of item types
----------------------

 The sections below describe the various types of items supported by canvas widgets. Each item type is characterized by two things: first, the form of the **create** command used to create instances of the type; and second, a set of configuration options for items of that type, which may be used in the **create** and **itemconfigure** widget commands. Most items do not support indexing or selection or the commands related to them, such as **index** and **insert**. Where items do support these facilities, it is noted explicitly in the descriptions below. At present, text, line and polygon items provide this support. For lines and polygons the indexing facility is used to manipulate the coordinates of the item. ### Common item options

 Many items share a common set of options. These options are explained here, and then referred to be each widget type for brevity. 
 
**-anchor** *anchorPos*

 *AnchorPos* tells how to position the item relative to the positioning point for the item; it may have any of the forms accepted by **[Tk\_GetAnchor](https://www.tcl.tk/man/tcl/TkLib/GetAnchor.htm)**. For example, if *anchorPos* is **center** then the item is centered on the point; if *anchorPos* is **n** then the item will be drawn so that its top center point is at the positioning point. This option defaults to **center**. 


**-dash** *pattern*


**-activedash** *pattern*


**-disableddash** *pattern*

 This option specifies dash patterns for the normal, active state, and disabled state of an item. *pattern* may have any of the forms accepted by **[Tk\_GetDash](https://www.tcl.tk/man/tcl/TkLib/GetDash.htm)**. If the dash options are omitted then the default is a solid outline. See **[DASH PATTERNS](#M26)** for more information. 


**-dashoffset** *offset*

 The starting *offset* in pixels into the pattern provided by the **-dash** option. **-dashoffset** is ignored if there is no **-dash** pattern. The *offset* may have any of the forms described in the **[COORDINATES](#M17)** section above. 


**-fill** *color*


**-activefill** *color*


**-disabledfill** *color*

 Specifies the color to be used to fill item's area. in its normal, active, and disabled states, *Color* may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. If *color* is an empty string (the default), then the item will not be filled. For the line item, it specifies the color of the line drawn. For the text item, it specifies the foreground color of the text. 


**-outline** *color*


**-activeoutline** *color*


**-disabledoutline** *color*

 This option specifies the color that should be used to draw the outline of the item in its normal, active and disabled states. *Color* may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. This option defaults to **black**. If *color* is specified as an empty string then no outline is drawn for the item. 


**-offset** *offset*

 Specifies the offset of stipples. The offset value can be of the form **x,y** or *side*, where side can be **n**, **ne**, **e**, **se**, **s**, **sw**, **w**, **nw**, or **center**. In the first case the origin is the origin of the toplevel of the current window. For the canvas itself and canvas objects the origin is the canvas origin, but putting **#** in front of the coordinate pair indicates using the toplevel origin instead. For canvas objects, the **-offset** option is used for stippling as well. For the line and polygon canvas items you can also specify an index as argument, which connects the stipple origin to one of the coordinate points of the line/polygon. Note that stipple offsets are *only supported on X11*; they are silently ignored on other platforms. 


**-outlinestipple** *bitmap*


**-activeoutlinestipple** *bitmap*


**-disabledoutlinestipple** *bitmap*

 This option specifies stipple patterns that should be used to draw the outline of the item in its normal, active and disabled states. Indicates that the outline for the item should be drawn with a stipple pattern; *bitmap* specifies the stipple pattern to use, in any of the forms accepted by **[Tk\_GetBitmap](https://www.tcl.tk/man/tcl/TkLib/GetBitmap.htm)**. If the **-outline** option has not been specified then this option has no effect. If *bitmap* is an empty string (the default), then the outline is drawn in a solid fashion. *Note that stipples are not well supported on platforms that do not use X11 as their drawing API.*


**-outlineoffset** *offset*

 Specifies the offset of the stipple pattern used for outlines, in the same way that the **-outline** option controls fill stipples. (See the **-outline** option for a description of the syntax of *offset*.) 


**-stipple** *bitmap*


**-activestipple** *bitmap*


**-disabledstipple** *bitmap*

 This option specifies stipple patterns that should be used to fill the item in its normal, active and disabled states. *bitmap* specifies the stipple pattern to use, in any of the forms accepted by **[Tk\_GetBitmap](https://www.tcl.tk/man/tcl/TkLib/GetBitmap.htm)**. If the **-fill** option has not been specified then this option has no effect. If *bitmap* is an empty string (the default), then filling is done in a solid fashion. For the text item, it affects the actual text. *Note that stipples are not well supported on platforms that do not use X11 as their drawing API.*


**-state** *state*

 This allows an item to override the canvas widget's global *state* option. It takes the same values: *normal*, *disabled* or *hidden*. 


**-tags** *tagList*

 Specifies a set of tags to apply to the item. *TagList* consists of a list of tag names, which replace any existing tags for the item. *TagList* may be an empty list. 


**-width** *outlineWidth*


**-activewidth** *outlineWidth*


**-disabledwidth** *outlineWidth*

 Specifies the width of the outline to be drawn around the item's region, in its normal, active and disabled states. *outlineWidth* may be in any of the forms described in the **[COORDINATES](#M17)** section above. If the **-outline** option has been specified as an empty string then this option has no effect. This option defaults to 1.0. For arcs, wide outlines will be drawn centered on the edges of the arc's region. 

 Standard item types
-------------------

 ### Arc items

 Items of type **arc** appear on the display as arc-shaped regions. An arc is a section of an oval delimited by two angles (specified by the **-start** and **-extent** options) and displayed in one of several ways (specified by the **-style** option). Arcs are created with widget commands of the following form: 
```
*pathName* **create arc** *x1 y1 x2 y2* ?*option value ...*?
*pathName* **create arc** *coordList* ?*option value ...*?
```
 The arguments *x1*, *y1*, *x2*, and *y2* or *coordList* give the coordinates of two diagonally opposite corners of a rectangular region enclosing the oval that defines the arc. After the coordinates there may be any number of *option*-*value* pairs, each of which sets one of the configuration options for the item. These same *option*-*value* pairs may be used in **itemconfigure** widget commands to change the item's configuration. An arc item becomes the current item when the mouse pointer is over any part that is painted or (when fully transparent) that would be painted if both the **-fill** and **-outline** options were non-empty.  The following standard options are supported by arcs: 




|  |  |
| --- | --- |
| **-dash** | **-activedash** |
| **-disableddash** | **-dashoffset** |
| **-fill** | **-activefill** |
| **-disabledfill** | **-offset** |
| **-outline** | **-activeoutline** |
| **-disabledoutline** | **-outlineoffset** |
| **-outlinestipple** | **-activeoutlinestipple** |
| **-disabledoutlinestipple** | **-stipple** |
| **-activestipple** | **-disabledstipple** |
| **-state** | **-tags** |
| **-width** | **-activewidth** |
| **-disabledwidth** |

 The following extra options are supported for arcs: 
 
**-extent** *degrees*

 Specifies the size of the angular range occupied by the arc. The arc's range extends for *degrees* degrees counter-clockwise from the starting angle given by the **-start** option. *Degrees* may be negative. If it is greater than 360 or less than -360, then *degrees* modulo 360 is used as the extent. 


**-start** *degrees*

 Specifies the beginning of the angular range occupied by the arc. *Degrees* is given in units of degrees measured counter-clockwise from the 3-o'clock position; it may be either positive or negative. 


**-style** *type*

 Specifies how to draw the arc. If *type* is **pieslice** (the default) then the arc's region is defined by a section of the oval's perimeter plus two line segments, one between the center of the oval and each end of the perimeter section. If *type* is **chord** then the arc's region is defined by a section of the oval's perimeter plus a single line segment connecting the two end points of the perimeter section. If *type* is **arc** then the arc's region consists of a section of the perimeter alone. In this last case the **-fill** option is ignored. 

 ### Bitmap items

 Items of type **bitmap** appear on the display as images with two colors, foreground and background. Bitmaps are created with widget commands of the following form: 
```
*pathName* **create bitmap** *x y* ?*option value ...*?
*pathName* **create bitmap** *coordList* ?*option value ...*?
```
 The arguments *x* and *y* or *coordList* (which must have two elements) specify the coordinates of a point used to position the bitmap on the display, as controlled by the **-anchor** option. After the coordinates there may be any number of *option*-*value* pairs, each of which sets one of the configuration options for the item. These same *option*-*value* pairs may be used in **itemconfigure** widget commands to change the item's configuration. A bitmap item becomes the current item when the mouse pointer is over any part of its bounding box.  The following standard options are supported by bitmaps: 




|  |  |
| --- | --- |
| **-anchor** | **-state** |
| **-tags** |

 The following extra options are supported for bitmaps: 
 
**-background** *color*


**-activebackground** *color*


**-disabledbackground** *color*

 Specifies the color to use for each of the bitmap's “0” valued pixels in its normal, active and disabled states. *Color* may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. If this option is not specified, or if it is specified as an empty string, then nothing is displayed where the bitmap pixels are 0; this produces a transparent effect. 


**-bitmap** *bitmap*


**-activebitmap** *bitmap*


**-disabledbitmap** *bitmap*

 Specifies the bitmaps to display in the item in its normal, active and disabled states. *Bitmap* may have any of the forms accepted by **[Tk\_GetBitmap](https://www.tcl.tk/man/tcl/TkLib/GetBitmap.htm)**. 


**-foreground** *color*


**-activeforeground** *color*


**-disabledforeground** *color*

 Specifies the color to use for each of the bitmap's “1” valued pixels in its normal, active and disabled states. *Color* may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)** and defaults to **black**. 

 ### Image items

 Items of type **image** are used to display images on a canvas. Images are created with widget commands of the following form: 
```
*pathName* **create image** *x y* ?*option value ...*?
*pathName* **create image** *coordList* ?*option value ...*?
```
 The arguments *x* and *y* or *coordList* specify the coordinates of a point used to position the image on the display, as controlled by the **-anchor** option. After the coordinates there may be any number of *option*-*value* pairs, each of which sets one of the configuration options for the item. These same *option*-*value* pairs may be used in **itemconfigure** widget commands to change the item's configuration. An image item becomes the current item when the mouse pointer is over any part of its bounding box.  The following standard options are supported by images: 




|  |  |
| --- | --- |
| **-anchor** | **-state** |
| **-tags** |

 The following extra options are supported for images: 
 
**-image** *name*


**-activeimage** *name*


**-disabledimage** *name*

 Specifies the name of the images to display in the item in is normal, active and disabled states. This image must have been created previously with the **[image create](image.htm)** command. 

 ### Line items

 Items of type **line** appear on the display as one or more connected line segments or curves. Line items support coordinate indexing operations using the **dchars**, **index** and **insert** widget commands. Lines are created with widget commands of the following form: 
```
*pathName* **create line** *x1 y1... xn yn* ?*option value ...*?
*pathName* **create line** *coordList* ?*option value ...*?
```
 The arguments *x1* through *yn* or *coordList* give the coordinates for a series of two or more points that describe a series of connected line segments. After the coordinates there may be any number of *option*-*value* pairs, each of which sets one of the configuration options for the item. These same *option*-*value* pairs may be used in **itemconfigure** widget commands to change the item's configuration. A line item is the current item whenever the mouse pointer is over any segment of the line, whether drawn or not and whether or not the line is smoothed.  The following standard options are supported by lines: 




|  |  |
| --- | --- |
| **-dash** | **-activedash** |
| **-disableddash** | **-dashoffset** |
| **-fill** | **-activefill** |
| **-disabledfill** | **-stipple** |
| **-activestipple** | **-disabledstipple** |
| **-state** | **-tags** |
| **-width** | **-activewidth** |
| **-disabledwidth** |

 The following extra options are supported for lines: 
 
**-arrow** *where*

 Indicates whether or not arrowheads are to be drawn at one or both ends of the line. *Where* must have one of the values **none** (for no arrowheads), **first** (for an arrowhead at the first point of the line), **last** (for an arrowhead at the last point of the line), or **both** (for arrowheads at both ends). This option defaults to **none**. 


**-arrowshape** *shape*

 This option indicates how to draw arrowheads. The *shape* argument must be a list with three elements, each specifying a distance in any of the forms described in the **[COORDINATES](#M17)** section above. The first element of the list gives the distance along the line from the neck of the arrowhead to its tip. The second element gives the distance along the line from the trailing points of the arrowhead to the tip, and the third element gives the distance from the outside edge of the line to the trailing points. If this option is not specified then Tk picks a “reasonable” shape. 


**-capstyle** *style*

 Specifies the ways in which caps are to be drawn at the endpoints of the line. *Style* may have any of the forms accepted by **[Tk\_GetCapStyle](https://www.tcl.tk/man/tcl/TkLib/GetCapStyl.htm)** (**butt**, **projecting**, or **round**). If this option is not specified then it defaults to **butt**. Where arrowheads are drawn the cap style is ignored. 


**-joinstyle** *style*

 Specifies the ways in which joints are to be drawn at the vertices of the line. *Style* may have any of the forms accepted by **[Tk\_GetJoinStyle](https://www.tcl.tk/man/tcl/TkLib/GetJoinStl.htm)** (**bevel**, **miter**, or **round**). If this option is not specified then it defaults to **round**. If the line only contains two points then this option is irrelevant. 


**-smooth** *smoothMethod*

 *smoothMethod* must have one of the forms accepted by **[Tcl\_GetBoolean](https://www.tcl.tk/man/tcl/TclLib/GetInt.htm)** or a line smoothing method. Only **true** and **raw** are supported in the core (with **bezier** being an alias for **true**), but more can be added at runtime. If a boolean false value or empty string is given, no smoothing is applied. A boolean truth value assumes **true** smoothing. If the smoothing method is **true**, this indicates that the line should be drawn as a curve, rendered as a set of quadratic splines: one spline is drawn for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated within a curve by duplicating the end-points of the desired line segment. If the smoothing method is **raw**, this indicates that the line should also be drawn as a curve but where the list of coordinates is such that the first coordinate pair (and every third coordinate pair thereafter) is a knot point on a cubic Bezier curve, and the other coordinates are control points on the cubic Bezier curve. Straight line segments can be generated within a curve by making control points equal to their neighbouring knot points. If the last point is a control point and not a knot point, the point is repeated (one or two times) so that it also becomes a knot point. 


**-splinesteps** *number*

 Specifies the degree of smoothness desired for curves: each spline will be approximated with *number* line segments. This option is ignored unless the **-smooth** option is true or **raw**. 

 ### Oval items

 Items of type **oval** appear as circular or oval regions on the display. Each oval may have an outline, a fill, or both. Ovals are created with widget commands of the following form: 
```
*pathName* **create oval** *x1 y1 x2 y2* ?*option value ...*?
*pathName* **create oval** *coordList* ?*option value ...*?
```
 The arguments *x1*, *y1*, *x2*, and *y2* or *coordList* give the coordinates of two diagonally opposite corners of a rectangular region enclosing the oval. The oval will include the top and left edges of the rectangle not the lower or right edges. If the region is square then the resulting oval is circular; otherwise it is elongated in shape. After the coordinates there may be any number of *option*-*value* pairs, each of which sets one of the configuration options for the item. These same *option*-*value* pairs may be used in **itemconfigure** widget commands to change the item's configuration. An oval item becomes the current item when the mouse pointer is over any part that is painted or (when fully transparent) that would be painted if both the **-fill** and **-outline** options were non-empty.  The following standard options are supported by ovals: 




|  |  |
| --- | --- |
| **-dash** | **-activedash** |
| **-disableddash** | **-dashoffset** |
| **-fill** | **-activefill** |
| **-disabledfill** | **-offset** |
| **-outline** | **-activeoutline** |
| **-disabledoutline** | **-outlineoffset** |
| **-outlinestipple** | **-activeoutlinestipple** |
| **-disabledoutlinestipple** | **-stipple** |
| **-activestipple** | **-disabledstipple** |
| **-state** | **-tags** |
| **-width** | **-activewidth** |
| **-disabledwidth** |

 There are no oval-specific options. ### Polygon items

 Items of type **polygon** appear as polygonal or curved filled regions on the display. Polygon items support coordinate indexing operations using the **dchars**, **index** and **insert** widget commands. Polygons are created with widget commands of the following form: 
```
*pathName* **create polygon** *x1 y1 ... xn yn* ?*option value ...*?
*pathName* **create polygon** *coordList* ?*option value ...*?
```
 The arguments *x1* through *yn* or *coordList* specify the coordinates for three or more points that define a polygon. The first point should not be repeated as the last to close the shape; Tk will automatically close the periphery between the first and last points. After the coordinates there may be any number of *option*-*value* pairs, each of which sets one of the configuration options for the item. These same *option*-*value* pairs may be used in **itemconfigure** widget commands to change the item's configuration. A polygon item is the current item whenever the mouse pointer is over any part of the polygon, whether drawn or not and whether or not the outline is smoothed.  The following standard options are supported by polygons: 




|  |  |
| --- | --- |
| **-dash** | **-activedash** |
| **-disableddash** | **-dashoffset** |
| **-fill** | **-activefill** |
| **-disabledfill** | **-offset** |
| **-outline** | **-activeoutline** |
| **-disabledoutline** | **-outlineoffset** |
| **-outlinestipple** | **-activeoutlinestipple** |
| **-disabledoutlinestipple** | **-stipple** |
| **-activestipple** | **-disabledstipple** |
| **-state** | **-tags** |
| **-width** | **-activewidth** |
| **-disabledwidth** |

 The following extra options are supported for polygons: 
 
**-joinstyle** *style*

 Specifies the ways in which joints are to be drawn at the vertices of the outline. *Style* may have any of the forms accepted by **[Tk\_GetJoinStyle](https://www.tcl.tk/man/tcl/TkLib/GetJoinStl.htm)** (**bevel**, **miter**, or **round**). If this option is not specified then it defaults to **round**. 


**-smooth** *boolean*

 *Boolean* must have one of the forms accepted by **[Tcl\_GetBoolean](https://www.tcl.tk/man/tcl/TclLib/GetInt.htm)** or a line smoothing method. Only **true** and **raw** are supported in the core (with **bezier** being an alias for **true**), but more can be added at runtime. If a boolean false value or empty string is given, no smoothing is applied. A boolean truth value assumes **true** smoothing. If the smoothing method is **true**, this indicates that the polygon should be drawn as a curve, rendered as a set of quadratic splines: one spline is drawn for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated within a curve by duplicating the end-points of the desired line segment. If the smoothing method is **raw**, this indicates that the polygon should also be drawn as a curve but where the list of coordinates is such that the first coordinate pair (and every third coordinate pair thereafter) is a knot point on a cubic Bezier curve, and the other coordinates are control points on the cubic Bezier curve. Straight line segments can be venerated within a curve by making control points equal to their neighbouring knot points. If the last point is not the second point of a pair of control points, the point is repeated (one or two times) so that it also becomes the second point of a pair of control points (the associated knot point will be the first control point). 


**-splinesteps** *number*

 Specifies the degree of smoothness desired for curves: each spline will be approximated with *number* line segments. This option is ignored unless the **-smooth** option is true or **raw**. 

  Polygon items are different from other items such as rectangles, ovals and arcs in that interior points are considered to be “inside” a polygon (e.g. for purposes of the **find closest** and **find overlapping** widget commands) even if it is not filled. For most other item types, an interior point is considered to be inside the item only if the item is filled or if it has neither a fill nor an outline. If you would like an unfilled polygon whose interior points are not considered to be inside the polygon, use a line item instead. 


### Rectangle items

 Items of type **rectangle** appear as rectangular regions on the display. Each rectangle may have an outline, a fill, or both. Rectangles are created with widget commands of the following form: 
```
*pathName* **create rectangle** *x1 y1 x2 y2* ?*option value ...*?
*pathName* **create rectangle** *coordList* ?*option value ...*?
```
 The arguments *x1*, *y1*, *x2*, and *y2* or *coordList* (which must have four elements) give the coordinates of two diagonally opposite corners of the rectangle (the rectangle will include its upper and left edges but not its lower or right edges). After the coordinates there may be any number of *option*-*value* pairs, each of which sets one of the configuration options for the item. These same *option*-*value* pairs may be used in **itemconfigure** widget commands to change the item's configuration. A rectangle item becomes the current item when the mouse pointer is over any part that is painted or (when fully transparent) that would be painted if both the **-fill** and **-outline** options were non-empty.  The following standard options are supported by rectangles: 




|  |  |
| --- | --- |
| **-dash** | **-activedash** |
| **-disableddash** | **-dashoffset** |
| **-fill** | **-activefill** |
| **-disabledfill** | **-offset** |
| **-outline** | **-activeoutline** |
| **-disabledoutline** | **-outlineoffset** |
| **-outlinestipple** | **-activeoutlinestipple** |
| **-disabledoutlinestipple** | **-stipple** |
| **-activestipple** | **-disabledstipple** |
| **-state** | **-tags** |
| **-width** | **-activewidth** |
| **-disabledwidth** |

 There are no rectangle-specific options. ### Text items

 A text item displays a string of characters on the screen in one or more lines. Text items support indexing, editing and selection through the **dchars** widget command, the **focus** widget command, the **icursor** widget command, the **index** widget command, the **insert** widget command, and the **select** widget command. Text items are created with widget commands of the following form: 
```
*pathName* **create text** *x y* ?*option value ...*?
*pathName* **create text** *coordList* ?*option value ...*?
```
 The arguments *x* and *y* or *coordList* (which must have two elements) specify the coordinates of a point used to position the text on the display (see the options below for more information on how text is displayed). After the coordinates there may be any number of *option*-*value* pairs, each of which sets one of the configuration options for the item. These same *option*-*value* pairs may be used in **itemconfigure** widget commands to change the item's configuration. A text item becomes the current item when the mouse pointer is over any part of its bounding box.  The following standard options are supported by text items: 




|  |  |
| --- | --- |
| **-anchor** | **-fill** |
| **-activefill** | **-disabledfill** |
| **-stipple** | **-activestipple** |
| **-disabledstipple** | **-state** |
| **-tags** |

 The following extra options are supported for text items: 
 
**-angle** *rotationDegrees*

 *RotationDegrees* tells how many degrees to rotate the text anticlockwise about the positioning point for the text; it may have any floating-point value from 0.0 to 360.0. For example, if *rotationDegrees* is **90**, then the text will be drawn vertically from bottom to top. This option defaults to **0.0**. 


**-font** *fontName*

 Specifies the font to use for the text item. *FontName* may be any string acceptable to **[Tk\_GetFont](https://www.tcl.tk/man/tcl/TkLib/GetFont.htm)**. If this option is not specified, it defaults to a system-dependent font. 


**-justify** *how*

 Specifies how to justify the text within its bounding region. *How* must be one of the values **left**, **right**, or **center**. This option will only matter if the text is displayed as multiple lines. If the option is omitted, it defaults to **left**. 


**-text** *string*

 *String* specifies the characters to be displayed in the text item. Newline characters cause line breaks. The characters in the item may also be changed with the **insert** and **delete** widget commands. This option defaults to an empty string. 


**-underline** 

 Specifies the integer index of a character within the text to be underlined. 0 corresponds to the first character of the text displayed, 1 to the next character, and so on. -1 means that no underline should be drawn (if the whole text item is to be underlined, the appropriate font should be used instead). 


**-width** *lineLength*

 Specifies a maximum line length for the text, in any of the forms described in the **[COORDINATES](#M17)** section above. If this option is zero (the default) the text is broken into lines only at newline characters. However, if this option is non-zero then any line that would be longer than *lineLength* is broken just before a space character to make the line shorter than *lineLength*; the space character is treated as if it were a newline character. 

 ### Window items

 Items of type **window** cause a particular window to be displayed at a given position on the canvas. Window items are created with widget commands of the following form: 
```
*pathName* **create window** *x y* ?*option value ...*?
*pathName* **create window** *coordList* ?*option value ...*?
```
 The arguments *x* and *y* or *coordList* (which must have two elements) specify the coordinates of a point used to position the window on the display, as controlled by the **-anchor** option. After the coordinates there may be any number of *option*-*value* pairs, each of which sets one of the configuration options for the item. These same *option*-*value* pairs may be used in **itemconfigure** widget commands to change the item's configuration. Theoretically, a window item becomes the current item when the mouse pointer is over any part of its bounding box, but in practice this typically does not happen because the mouse pointer ceases to be over the canvas at that point.  The following standard options are supported by window items: 




|  |  |
| --- | --- |
| **-anchor** | **-state** |
| **-tags** |

 The following extra options are supported for window items: 
 
**-height** *pixels*

 Specifies the height to assign to the item's window. *Pixels* may have any of the forms described in the **[COORDINATES](#M17)** section above. If this option is not specified, or if it is specified as zero, then the window is given whatever height it requests internally. 


**-width** *pixels*

 Specifies the width to assign to the item's window. *Pixels* may have any of the forms described in the **[COORDINATES](#M17)** section above. If this option is not specified, or if it is specified as zero, then the window is given whatever width it requests internally. 


**-window** *pathName*

 Specifies the window to associate with this item. The window specified by *pathName* must either be a child of the canvas widget or a child of some ancestor of the canvas widget. *PathName* may not refer to a top-level window. 

  Note: due to restrictions in the ways that windows are managed, it is not possible to draw other graphical items (such as lines and images) on top of window items. A window item always obscures any graphics that overlap it, regardless of their order in the display list. Also note that window items, unlike other canvas items, are not clipped for display by their containing canvas's border, and are instead clipped by the parent widget of the window specified by the **-window** option; when the parent widget is the canvas, this means that the window item can overlap the canvas's border. 


Application-defined item types
------------------------------

 It is possible for individual applications to define new item types for canvas widgets using C code. See the documentation for **[Tk\_CreateItemType](https://www.tcl.tk/man/tcl/TkLib/CrtItemType.htm)**. Bindings
--------

 In the current implementation, new canvases are not given any default behavior: you will have to execute explicit Tcl commands to give the canvas its behavior. Credits
-------

 Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's *ezd* program. *Ezd* provides structured graphics in a Scheme environment and preceded canvases by a year or two. Its simple mechanisms for placing and animating graphical objects inspired the functions of canvases. See also
--------

 **[bind](bind.htm)**, **[font](font.htm)**, **[image](image.htm)**, **[scrollbar](scrollbar.htm)** Copyright © 1992-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 1997-1999 Scriptics Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/canvas.htm>

refchan
=======

  
[NAME](refchan.htm#M2) refchan — command handler API of reflected channels 
[SYNOPSIS](refchan.htm#M3) 
[DESCRIPTION](refchan.htm#M4) 
[MANDATORY SUBCOMMANDS](refchan.htm#M5)  
[*cmdPrefix* **initialize** *channelId mode*](refchan.htm#M6) 
[*cmdPrefix* **finalize** *channelId*](refchan.htm#M7) 
[*cmdPrefix* **watch** *channelId eventspec*](refchan.htm#M8) 


 
[OPTIONAL SUBCOMMANDS](refchan.htm#M9)  
[*cmdPrefix* **read** *channelId count*](refchan.htm#M10) 
[*cmdPrefix* **write** *channelId data*](refchan.htm#M11) 
[*cmdPrefix* **seek** *channelId offset base*](refchan.htm#M12)  
[**start**](refchan.htm#M13) 
[**current**](refchan.htm#M14) 
[**end**](refchan.htm#M15) 


 
[*cmdPrefix* **configure** *channelId option value*](refchan.htm#M16) 
[*cmdPrefix* **cget** *channelId option*](refchan.htm#M17) 
[*cmdPrefix* **cgetall** *channelId*](refchan.htm#M18) 
[*cmdPrefix* **blocking** *channelId mode*](refchan.htm#M19) 






 
[NOTES](refchan.htm#M20) 
[EXAMPLE](refchan.htm#M21) 
[SEE ALSO](refchan.htm#M22) 
[KEYWORDS](refchan.htm#M23) 








 Name
----

 refchan — command handler API of reflected channels Synopsis
--------

 **cmdPrefix** *option* ?*arg arg ...*?  
 Description
-----------

 The Tcl-level handler for a reflected channel has to be a command with subcommands (termed an *ensemble*, as it is a command such as that created by **[namespace ensemble](namespace.htm)** **create**, though the implementation of handlers for reflected channel *is not* tied to **namespace ensemble**s in any way; see **[EXAMPLE](#M21)** below for how to build an **[oo::class](class.htm)** that supports the API). Note that *cmdPrefix* is whatever was specified in the call to **[chan create](chan.htm)**, and may consist of multiple arguments; this will be expanded to multiple words in place of the prefix.  Of all the possible subcommands, the handler *must* support **initialize**, **finalize**, and **watch**. Support for the other subcommands is optional. 


### Mandatory subcommands

  
*cmdPrefix* **initialize** *channelId mode*

 An invocation of this subcommand will be the first call the *cmdPrefix* will receive for the specified new *channelId*. It is the responsibility of this subcommand to set up any internal data structures required to keep track of the channel and its state.  The return value of the method has to be a list containing the names of all subcommands supported by the *cmdPrefix*. This also tells the Tcl core which version of the API for reflected channels is used by this command handler. 


 Any error thrown by the method will abort the creation of the channel and no channel will be created. The thrown error will appear as error thrown by **[chan create](chan.htm)**. Any exception other than an **[error](error.htm)** (e.g., **[break](break.htm)**, etc.) is treated as (and converted to) an error. 


 **Note:** If the creation of the channel was aborted due to failures here, then the **finalize** subcommand will not be called. 


 The *mode* argument tells the handler whether the channel was opened for reading, writing, or both. It is a list containing any of the strings **[read](read.htm)** or **write**. The list will always contain at least one element. 


The subcommand must throw an error if the chosen mode is not supported by the *cmdPrefix*. 




*cmdPrefix* **finalize** *channelId*

 An invocation of this subcommand will be the last call the *cmdPrefix* will receive for the specified *channelId*. It will be generated just before the destruction of the data structures of the channel held by the Tcl core. The command handler *must not* access the *channelId* anymore in no way. Upon this subcommand being called, any internal resources allocated to this channel must be cleaned up.  The return value of this subcommand is ignored. 


 If the subcommand throws an error the command which caused its invocation (usually **[chan close](chan.htm)**) will appear to have thrown this error. Any exception beyond **[error](error.htm)** (e.g., **[break](break.htm)**, etc.) is treated as (and converted to) an error. 


This subcommand is not invoked if the creation of the channel was aborted during **initialize** (See above). 




*cmdPrefix* **watch** *channelId eventspec*

 This subcommand notifies the *cmdPrefix* that the specified *channelId* is interested in the events listed in the *eventspec*. This argument is a list containing any of **[read](read.htm)** and **write**. The list may be empty, which signals that the channel does not wish to be notified of any events. In that situation, the handler should disable event generation completely.  **Warning:** Any return value of the subcommand is ignored. This includes all errors thrown by the subcommand, **[break](break.htm)**, **[continue](continue.htm)**, and custom return codes. 


This subcommand interacts with **[chan postevent](chan.htm)**. Trying to post an event which was not listed in the last call to **watch** will cause **[chan postevent](chan.htm)** to throw an error. 



 ### Optional subcommands

  
*cmdPrefix* **read** *channelId count*

 This *optional* subcommand is called when the user requests data from the channel *channelId*. *count* specifies how many *bytes* have been requested. If the subcommand is not supported then it is not possible to read from the channel handled by the command.  The return value of this subcommand is taken as the requested data *bytes*. If the returned data contains more bytes than requested, an error will be signaled and later thrown by the command which performed the read (usually **[gets](gets.htm)** or **[read](read.htm)**). However, returning fewer bytes than requested is acceptable. 


 Note that returning nothing (0 bytes) is a signal to the higher layers that **[EOF](eof.htm)** has been reached on the channel. To signal that the channel is out of data right now, but has not yet reached **[EOF](eof.htm)**, it is necessary to throw the error "EAGAIN", i.e. to either 



```
return -code error EAGAIN
```
 or 
```
error EAGAIN
```
  For extensibility any error whose value is a negative integer number will cause the higher layers to set the C-level variable "**errno**" to the absolute value of this number, signaling a system error. However, note that the exact mapping between these error numbers and their meanings is operating system dependent. 


 For example, while on Linux both 



```
return -code error -11
```
 and 
```
error -11
```
  are equivalent to the examples above, using the more readable string "EAGAIN", this is not true for BSD, where the equivalent number is -35. 


 The symbolic string however is the same across systems, and internally translated to the correct number. No other error value has such a mapping to a symbolic string. 


If the subcommand throws any other error, the command which caused its invocation (usually **[gets](gets.htm)**, or **[read](read.htm)**) will appear to have thrown this error. Any exception beyond **[error](error.htm)**, (e.g., **[break](break.htm)**, etc.) is treated as and converted to an error. 




*cmdPrefix* **write** *channelId data*

 This *optional* subcommand is called when the user writes data to the channel *channelId*. The *data* argument contains *bytes*, not characters. Any type of transformation (EOL, encoding) configured for the channel has already been applied at this point. If this subcommand is not supported then it is not possible to write to the channel handled by the command.  The return value of the subcommand is taken as the number of bytes written by the channel. Anything non-numeric will cause an error to be signaled and later thrown by the command which performed the write. A negative value implies that the write failed. Returning a value greater than the number of bytes given to the handler, or zero, is forbidden and will cause the Tcl core to throw an error. 


 To signal that the channel is not able to accept data for writing right now, it is necessary to throw the error "EAGAIN", i.e. to either 



```
return -code error EAGAIN
```
 or 
```
error EAGAIN
```
  For extensibility any error whose value is a negative integer number will cause the higher layers to set the C-level variable "**errno**" to the absolute value of this number, signaling a system error. However, note that the exact mapping between these error numbers and their meanings is operating system dependent. 


 For example, while on Linux both 



```
return -code error -11
```
 and 
```
error -11
```
  are equivalent to the examples above, using the more readable string "EAGAIN", this is not true for BSD, where the equivalent number is -35. 


 The symbolic string however is the same across systems, and internally translated to the correct number. No other error value has such a mapping to a symbolic string. 


If the subcommand throws any other error the command which caused its invocation (usually **[puts](puts.htm)**) will appear to have thrown this error. Any exception beyond **[error](error.htm)** (e.g., **[break](break.htm)**, etc.) is treated as and converted to an error. 




*cmdPrefix* **seek** *channelId offset base*

 This *optional* subcommand is responsible for the handling of **[chan seek](chan.htm)** and **[chan tell](chan.htm)** requests on the channel *channelId*. If it is not supported then seeking will not be possible for the channel.  The *base* argument is the same as the equivalent argument of the builtin **[chan seek](chan.htm)**, namely: 


 **start**
 Seeking is relative to the beginning of the channel. 

**current**
 Seeking is relative to the current seek position. 

**end**
 Seeking is relative to the end of the channel. 

  The *offset* is an integer number specifying the amount of **bytes** to seek forward or backward. A positive number should seek forward, and a negative number should seek backward. A channel may provide only limited seeking. For example sockets can seek forward, but not backward. 


 The return value of the subcommand is taken as the (new) location of the channel, counted from the start. This has to be an integer number greater than or equal to zero. If the subcommand throws an error the command which caused its invocation (usually **[chan seek](chan.htm)**, or **[chan tell](chan.htm)**) will appear to have thrown this error. Any exception beyond **[error](error.htm)** (e.g., **[break](break.htm)**, etc.) is treated as and converted to an error. 


The offset/base combination of 0/**current** signals a **[chan tell](chan.htm)** request, i.e., seek nothing relative to the current location, making the new location identical to the current one, which is then returned. 




*cmdPrefix* **configure** *channelId option value*

 This *optional* subcommand is for setting the type-specific options of channel *channelId*. The *option* argument indicates the option to be written, and the *value* argument indicates the value to set the option to.  This subcommand will never try to update more than one option at a time; that is behavior implemented in the Tcl channel core. 


 The return value of the subcommand is ignored. 


If the subcommand throws an error the command which performed the (re)configuration or query (usually **[fconfigure](fconfigure.htm)** or **[chan configure](chan.htm)**) will appear to have thrown this error. Any exception beyond **[error](error.htm)** (e.g., **[break](break.htm)**, etc.) is treated as and converted to an error. 




*cmdPrefix* **cget** *channelId option*

 This *optional* subcommand is used when reading a single type-specific option of channel *channelId*. If this subcommand is supported then the subcommand **cgetall** must be supported as well.  The subcommand should return the value of the specified *option*. 


If the subcommand throws an error, the command which performed the (re)configuration or query (usually **[fconfigure](fconfigure.htm)** or **[chan configure](chan.htm)**) will appear to have thrown this error. Any exception beyond *error* (e.g., **[break](break.htm)**, etc.) is treated as and converted to an error. 




*cmdPrefix* **cgetall** *channelId*

 This *optional* subcommand is used for reading all type-specific options of channel *channelId*. If this subcommand is supported then the subcommand **cget** has to be supported as well.  The subcommand should return a list of all options and their values. This list must have an even number of elements. 


If the subcommand throws an error the command which performed the (re)configuration or query (usually **[fconfigure](fconfigure.htm)** or **[chan configure](chan.htm)**) will appear to have thrown this error. Any exception beyond **[error](error.htm)** (e.g., **[break](break.htm)**, etc.) is treated as and converted to an error. 




*cmdPrefix* **blocking** *channelId mode*

 This *optional* subcommand handles changes to the blocking mode of the channel *channelId*. The *mode* is a boolean flag. A true value means that the channel has to be set to blocking, and a false value means that the channel should be non-blocking.  The return value of the subcommand is ignored. 


If the subcommand throws an error the command which caused its invocation (usually **[fconfigure](fconfigure.htm)** or **[chan configure](chan.htm)**) will appear to have thrown this error. Any exception beyond **[error](error.htm)** (e.g., **[break](break.htm)**, etc.) is treated as and converted to an error. 



 Notes
-----

 Some of the functions supported in channels defined in Tcl's C interface are not available to channels reflected to the Tcl level.  The function **Tcl\_DriverGetHandleProc** is not supported; i.e., reflected channels do not have OS specific handles. 


 The function **Tcl\_DriverHandlerProc** is not supported. This driver function is relevant only for stacked channels, i.e., transformations. Reflected channels are always base channels, not transformations. 


 The function **Tcl\_DriverFlushProc** is not supported. This is because the current generic I/O layer of Tcl does not use this function anywhere at all. Therefore support at the Tcl level makes no sense either. This may be altered in the future (through extending the API defined here and changing its version number) should the function be used at some time in the future. 


Example
-------

 This demonstrates how to make a channel that reads from a string. 

```
oo::class create stringchan {
    variable data pos
    constructor {string {encoding {}}} {
        if {$encoding eq ""} {set encoding [encoding system]}
        set data [encoding convertto $encoding $string]
        set pos 0
    }

    method **initialize** {ch mode} {
        return "initialize finalize watch read seek"
    }
    method **finalize** {ch} {
        my destroy
    }
    method **watch** {ch events} {
        # Must be present but we ignore it because we do not
        # post any events
    }

    # Must be present on a readable channel
    method **[read](read.htm)** {ch count} {
        set d [string range $data $pos [expr {$pos+$count-1}]]
        incr pos [string length $d]
        return $d
    }

    # This method is optional, but useful for the example below
    method **[seek](seek.htm)** {ch offset base} {
        switch $base {
            start {
                set pos $offset
            }
            current {
                incr pos $offset
            }
            end {
                set pos [string length $data]
                incr pos $offset
            }
        }
        if {$pos < 0} {
            set pos 0
        } elseif {$pos > [string length $data]} {
            set pos [string length $data]
        }
        return $pos
    }
}

# Now we create an instance...
set string "The quick brown fox jumps over the lazy dog.\n"
set ch [**[chan create](chan.htm)** read [stringchan new $string]]

puts [gets $ch];   # Prints the whole string

seek $ch -5 end;
puts [read $ch];   # Prints just the last word
```
 See also
--------

 **[chan](chan.htm)**, **[transchan](transchan.htm)** Copyright © 2006 Andreas Kupries <andreas\_kupries(at)users.sourceforge.net> 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/refchan.htm>

regexp
======

  
[NAME](regexp.htm#M2) regexp — Match a regular expression against a string 
[SYNOPSIS](regexp.htm#M3) 
[DESCRIPTION](regexp.htm#M4)  
[**-about**](regexp.htm#M5) 
[**-expanded**](regexp.htm#M6) 
[**-indices**](regexp.htm#M7) 
[**-line**](regexp.htm#M8) 
[**-linestop**](regexp.htm#M9) 
[**-lineanchor**](regexp.htm#M10) 
[**-nocase**](regexp.htm#M11) 
[**-all**](regexp.htm#M12) 
[**-inline**](regexp.htm#M13) 
[**-start** *index*](regexp.htm#M14) 
[**--**](regexp.htm#M15) 










 
[EXAMPLES](regexp.htm#M16) 
[SEE ALSO](regexp.htm#M17) 
[KEYWORDS](regexp.htm#M18) 





 Name
----

 regexp — Match a regular expression against a string Synopsis
--------

 **regexp** ?*switches*? *exp string* ?*matchVar*? ?*subMatchVar subMatchVar ...*?  
 Description
-----------

 Determines whether the regular expression *exp* matches part or all of *string* and returns 1 if it does, 0 if it does not, unless **-inline** is specified (see below). (Regular expression matching is described in the **[re\_syntax](re_syntax.htm)** reference page.)  If additional arguments are specified after *string* then they are treated as the names of variables in which to return information about which part(s) of *string* matched *exp*. *MatchVar* will be set to the range of *string* that matched all of *exp*. The first *subMatchVar* will contain the characters in *string* that matched the leftmost parenthesized subexpression within *exp*, the next *subMatchVar* will contain the characters that matched the next parenthesized subexpression to the right in *exp*, and so on. 


 If the initial arguments to **regexp** start with **-** then they are treated as switches. The following switches are currently supported: 


 **-about**
 Instead of attempting to match the regular expression, returns a list containing information about the regular expression. The first element of the list is a subexpression count. The second element is a list of property names that describe various attributes of the regular expression. This switch is primarily intended for debugging purposes. 

**-expanded**
 Enables use of the expanded regular expression syntax where whitespace and comments are ignored. This is the same as specifying the **(?x)** embedded option (see the **[re\_syntax](re_syntax.htm)** manual page). 

**-indices**
 Changes what is stored in the *matchVar* and *subMatchVar*s. Instead of storing the matching characters from *string*, each variable will contain a list of two decimal strings giving the indices in *string* of the first and last characters in the matching range of characters. 

**-line**
 Enables newline-sensitive matching. By default, newline is a completely ordinary character with no special meaning. With this flag, “[^” bracket expressions and “.” never match newline, “^” matches an empty string after any newline in addition to its normal function, and “$” matches an empty string before any newline in addition to its normal function. This flag is equivalent to specifying both **-linestop** and **-lineanchor**, or the **(?n)** embedded option (see the **[re\_syntax](re_syntax.htm)** manual page). 

**-linestop**
 Changes the behavior of “[^” bracket expressions and “.” so that they stop at newlines. This is the same as specifying the **(?p)** embedded option (see the **[re\_syntax](re_syntax.htm)** manual page). 

**-lineanchor**
 Changes the behavior of “^” and “$” (the “anchors”) so they match the beginning and end of a line respectively. This is the same as specifying the **(?w)** embedded option (see the **[re\_syntax](re_syntax.htm)** manual page). 

**-nocase**
 Causes upper-case characters in *string* to be treated as lower case during the matching process. 

**-all**
 Causes the regular expression to be matched as many times as possible in the string, returning the total number of matches found. If this is specified with match variables, they will contain information for the last match only. 

**-inline**
 Causes the command to return, as a list, the data that would otherwise be placed in match variables. When using **-inline**, match variables may not be specified. If used with **-all**, the list will be concatenated at each iteration, such that a flat list is always returned. For each match iteration, the command will append the overall match data, plus one element for each subexpression in the regular expression. Examples are: 

```
**regexp** -inline -- {\w(\w)} " inlined "
      *→ in n*
**regexp** -all -inline -- {\w(\w)} " inlined "
      *→ in n li i ne e*
```



**-start** *index*

 Specifies a character index offset into the string to start matching the regular expression at. The *index* value is interpreted in the same manner as the *index* argument to **[string index](string.htm)**. When using this switch, “^” will not match the beginning of the line, and \A will still match the start of the string at *index*. If **-indices** is specified, the indices will be indexed starting from the absolute beginning of the input string. *index* will be constrained to the bounds of the input string. 

**--**
 Marks the end of switches. The argument following this one will be treated as *exp* even if it starts with a **-**. 

  If there are more *subMatchVar*s than parenthesized subexpressions within *exp*, or if a particular subexpression in *exp* does not match the string (e.g. because it was in a portion of the expression that was not matched), then the corresponding *subMatchVar* will be set to “**-1 -1**” if **-indices** has been specified or to an empty string otherwise. 


Examples
--------

 Find the first occurrence of a word starting with **foo** in a string that is not actually an instance of **foobar**, and get the letters following it up to the end of the word into a variable: 

```
**regexp** {\mfoo(?!bar\M)(\w*)} $string -> restOfWord
```
  Note that the whole matched substring has been placed in the variable “**->**”, which is a name chosen to look nice given that we are not actually interested in its contents. 


 Find the index of the word **badger** (in any case) within a string and store that in the variable **location**: 



```
**regexp** -indices {(?i)\mbadger\M} $string location
```
  This could also be written as a *basic* regular expression (as opposed to using the default syntax of *advanced* regular expressions) match by prefixing the expression with a suitable flag: 



```
**regexp** -indices {(?ib)\<badger\>} $string location
```
  This counts the number of octal digits in a string: 



```
**regexp** -all {[0-7]} $string
```
  This lists all words (consisting of all sequences of non-whitespace characters) in a string, and is useful as a more powerful version of the **[split](split.htm)** command: 



```
**regexp** -all -inline {\S+} $string
```
 See also
--------

 **[re\_syntax](re_syntax.htm)**, **[regsub](regsub.htm)**, **[string](string.htm)** Copyright © 1998 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/regexp.htm>

registry
========

  
[NAME](registry.htm#M2) registry — Manipulate the Windows registry 
[SYNOPSIS](registry.htm#M3) 
[DESCRIPTION](registry.htm#M4)  
[**registry broadcast** *keyName* ?**-timeout** *milliseconds*?](registry.htm#M5) 
[**registry delete** *keyName* ?*valueName*?](registry.htm#M6) 
[**registry get** *keyName valueName*](registry.htm#M7) 
[**registry keys** *keyName* ?*pattern*?](registry.htm#M8) 
[**registry set** *keyName* ?*valueName data* ?*type*??](registry.htm#M9) 
[**registry type** *keyName valueName*](registry.htm#M10) 
[**registry values** *keyName* ?*pattern*?](registry.htm#M11) 






 
[SUPPORTED TYPES](registry.htm#M12)  
[**binary**](registry.htm#M13) 
[**none**](registry.htm#M14) 
[**sz**](registry.htm#M15) 
[**expand\_sz**](registry.htm#M16) 
[**dword**](registry.htm#M17) 
[**dword\_big\_endian**](registry.htm#M18) 
[**link**](registry.htm#M19) 
[**multi\_sz**](registry.htm#M20) 
[**resource\_list**](registry.htm#M21) 








 
[PORTABILITY ISSUES](registry.htm#M22) 
[EXAMPLE](registry.htm#M23) 
[KEYWORDS](registry.htm#M24) 






 Name
----

 registry — Manipulate the Windows registry Synopsis
--------

 **package require registry 1.3**  
 **registry** ?*-mode*? *option* *keyName* ?*arg arg ...*?  
 Description
-----------

 The **registry** package provides a general set of operations for manipulating the Windows registry. The package implements the **registry** Tcl command. This command is only supported on the Windows platform. Warning: this command should be used with caution as a corrupted registry can leave your system in an unusable state.  *KeyName* is the name of a registry key. Registry keys must be one of the following forms: 


  **\\***hostname***\***rootname***\***keypath* 


 *rootname***\***keypath* 


 *rootname* 


  *Hostname* specifies the name of any valid Windows host that exports its registry. The *rootname* component must be one of **HKEY\_LOCAL\_MACHINE**, **HKEY\_USERS**, **HKEY\_CLASSES\_ROOT**, **HKEY\_CURRENT\_USER**, **HKEY\_CURRENT\_CONFIG**, **HKEY\_PERFORMANCE\_DATA**, or **HKEY\_DYN\_DATA**. The *keypath* can be one or more registry key names separated by backslash (**\**) characters. 


 The optional *-mode* argument indicates which registry to work with; when it is **-32bit** the 32-bit registry will be used, and when it is **-64bit** the 64-bit registry will be used. If this argument is omitted, the system's default registry will be the subject of the requested operation. 


 *Option* indicates what to do with the registry key name. Any unique abbreviation for *option* is acceptable. The valid options are: 


 
**registry broadcast** *keyName* ?**-timeout** *milliseconds*?
 Sends a broadcast message to the system and running programs to notify them of certain updates. This is necessary to propagate changes to key registry keys like Environment. The timeout specifies the amount of time, in milliseconds, to wait for applications to respond to the broadcast message. It defaults to 3000. The following example demonstrates how to add a path to the global Environment and notify applications of the change without requiring a logoff/logon step (assumes admin privileges): 

```
set regPath [join {
    HKEY_LOCAL_MACHINE
    SYSTEM
    CurrentControlSet
    Control
    {Session Manager}
    Environment
} "\\"]
set curPath [**registry get** $regPath "Path"]
**registry set** $regPath "Path" "$curPath;$addPath"
**registry broadcast** "Environment"
```



**registry delete** *keyName* ?*valueName*?
 If the optional *valueName* argument is present, the specified value under *keyName* will be deleted from the registry. If the optional *valueName* is omitted, the specified key and any subkeys or values beneath it in the registry hierarchy will be deleted. If the key could not be deleted then an error is generated. If the key did not exist, the command has no effect. 


**registry get** *keyName valueName*

 Returns the data associated with the value *valueName* under the key *keyName*. If either the key or the value does not exist, then an error is generated. For more details on the format of the returned data, see **[SUPPORTED TYPES](#M12)**, below. 


**registry keys** *keyName* ?*pattern*?
 If *pattern* is not specified, returns a list of names of all the subkeys of *keyName*. If *pattern* is specified, only those names matching *pattern* are returned. Matching is determined using the same rules as for **[string match](string.htm)**. If the specified *keyName* does not exist, then an error is generated. 


**registry set** *keyName* ?*valueName data* ?*type*??
 If *valueName* is not specified, creates the key *keyName* if it does not already exist. If *valueName* is specified, creates the key *keyName* and value *valueName* if necessary. The contents of *valueName* are set to *data* with the type indicated by *type*. If *type* is not specified, the type **sz** is assumed. For more details on the data and type arguments, see **[SUPPORTED TYPES](#M12)** below. 


**registry type** *keyName valueName*

 Returns the type of the value *valueName* in the key *keyName*. For more information on the possible types, see **[SUPPORTED TYPES](#M12)**, below. 


**registry values** *keyName* ?*pattern*?
 If *pattern* is not specified, returns a list of names of all the values of *keyName*. If *pattern* is specified, only those names matching *pattern* are returned. Matching is determined using the same rules as for **[string match](string.htm)**. 

 Supported types
---------------

 Each value under a key in the registry contains some data of a particular type in a type-specific representation. The **registry** command converts between this internal representation and one that can be manipulated by Tcl scripts. In most cases, the data is simply returned as a Tcl string. The type indicates the intended use for the data, but does not actually change the representation. For some types, the **registry** command returns the data in a different form to make it easier to manipulate. The following types are recognized by the registry command: 
 **binary**
 The registry value contains arbitrary binary data. The data is represented exactly in Tcl, including any embedded nulls. 

**none**
 The registry value contains arbitrary binary data with no defined type. The data is represented exactly in Tcl, including any embedded nulls. 

**sz**
 The registry value contains a null-terminated string. The data is represented in Tcl as a string. 

**expand\_sz**
 The registry value contains a null-terminated string that contains unexpanded references to environment variables in the normal Windows style (for example, “%PATH%”). The data is represented in Tcl as a string. 

**dword**
 The registry value contains a little-endian 32-bit number. The data is represented in Tcl as a decimal string. 

**dword\_big\_endian**
 The registry value contains a big-endian 32-bit number. The data is represented in Tcl as a decimal string. 

**link**
 The registry value contains a symbolic link. The data is represented exactly in Tcl, including any embedded nulls. 

**multi\_sz**
 The registry value contains an array of null-terminated strings. The data is represented in Tcl as a list of strings. 

**resource\_list**
 The registry value contains a device-driver resource list. The data is represented exactly in Tcl, including any embedded nulls. 

  In addition to the symbolically named types listed above, unknown types are identified using a 32-bit integer that corresponds to the type code returned by the system interfaces. In this case, the data is represented exactly in Tcl, including any embedded nulls. 


Portability issues
------------------

 The registry command is only available on Windows. Example
-------

 Print out how double-clicking on a Tcl script file will invoke a Tcl interpreter: 

```
package require registry
set ext .tcl

# Read the type name
set type [**registry get** HKEY_CLASSES_ROOT\\$ext {}]
# Work out where to look for the command
set path HKEY_CLASSES_ROOT\\$type\\Shell\\Open\\command
# Read the command!
set command [**registry get** $path {}]

puts "$ext opens with $command"
```
 Copyright © 1997 Sun Microsystems, Inc.  
 Copyright © 2002 ActiveState Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/registry.htm>

fblocked
========

 Name
----

 fblocked — Test whether the last input operation exhausted all available input Synopsis
--------

 **fblocked** *channelId*  
 Description
-----------

 The **fblocked** command returns 1 if the most recent input operation on *channelId* returned less information than requested because all available input was exhausted. For example, if **[gets](gets.htm)** is invoked when there are only three characters available for input and no end-of-line sequence, **[gets](gets.htm)** returns an empty string and a subsequent call to **fblocked** will return 1.  *ChannelId* must be an identifier for an open channel such as a Tcl standard channel (**[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, or **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**), the return value from an invocation of **[open](open.htm)** or **[socket](socket.htm)**, or the result of a channel creation command provided by a Tcl extension. 


Example
-------

 The **fblocked** command is particularly useful when writing network servers, as it allows you to write your code in a line-by-line style without preventing the servicing of other connections. This can be seen in this simple echo-service: 

```
# This is called whenever a new client connects to the server
proc connect {chan host port} {
    set clientName [format <%s:%d> $host $port]
    puts "connection from $clientName"
    fconfigure $chan -blocking 0 -buffering line
    fileevent $chan readable [list echoLine $chan $clientName]
}

# This is called whenever either at least one byte of input
# data is available, or the channel was closed by the client.
proc echoLine {chan clientName} {
    gets $chan line
    if {[eof $chan]} {
        puts "finishing connection from $clientName"
        close $chan
    } elseif {![**fblocked** $chan]} {
        # Didn't block waiting for end-of-line
        puts "$clientName - $line"
        puts $chan $line
    }
}

# Create the server socket and enter the event-loop to wait
# for incoming connections...
socket -server connect 12345
vwait forever
```
 See also
--------

 **[gets](gets.htm)**, **[open](open.htm)**, **[read](read.htm)**, **[socket](socket.htm)**, **[Tcl\_StandardChannels](https://www.tcl.tk/man/tcl/TclLib/StdChannels.htm)** Copyright © 1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/fblocked.htm>

lset
====

 Name
----

 lset — Change an element in a list Synopsis
--------

 **lset** *varName ?index ...? newValue*  
 Description
-----------

 The **lset** command accepts a parameter, *varName*, which it interprets as the name of a variable containing a Tcl list. It also accepts zero or more *indices* into the list. The indices may be presented either consecutively on the command line, or grouped in a Tcl list and presented as a single argument. Finally, it accepts a new value for an element of *varName*.  If no indices are presented, the command takes the form: 



```
**lset** varName newValue
```
  or 



```
**lset** varName {} newValue
```
  In this case, *newValue* replaces the old value of the variable *varName*. 


 When presented with a single index, the **lset** command treats the content of the *varName* variable as a Tcl list. It addresses the *index*'th element in it (0 refers to the first element of the list). When interpreting the list, **lset** observes the same rules concerning braces and quotes and backslashes as the Tcl command interpreter; however, variable substitution and command substitution do not occur. The command constructs a new list in which the designated element is replaced with *newValue*. This new list is stored in the variable *varName*, and is also the return value from the **lset** command. 


 If *index* is negative or greater than the number of elements in *$varName*, then an error occurs. 


 If *index* is equal to the number of elements in *$varName*, then the given element is appended to the list. 


 The interpretation of each simple *index* value is the same as for the command **[string index](string.htm)**, supporting simple index arithmetic and indices relative to the end of the list. 


 If additional *index* arguments are supplied, then each argument is used in turn to address an element within a sublist designated by the previous indexing operation, allowing the script to alter elements in sublists (or append elements to sublists). The command, 



```
**lset** a 1 2 newValue
```
  or 



```
**lset** a {1 2} newValue
```
  replaces element 2 of sublist 1 with *newValue*. 


 The integer appearing in each *index* argument must be greater than or equal to zero. The integer appearing in each *index* argument must be less than or equal to the length of the corresponding list. In other words, the **lset** command can change the size of a list only by appending an element (setting the one after the current end). If an index is outside the permitted range, an error is reported. 


Examples
--------

 In each of these examples, the initial value of *x* is: 

```
set x [list [list a b c] [list d e f] [list g h i]]
      *→ {a b c} {d e f} {g h i}*
```
  The indicated return value also becomes the new value of *x* (except in the last case, which is an error which leaves the value of *x* unchanged.) 



```
**lset** x {j k l}
      *→ j k l*
**lset** x {} {j k l}
      *→ j k l*
**lset** x 0 j
      *→ j {d e f} {g h i}*
**lset** x 2 j
      *→ {a b c} {d e f} j*
**lset** x end j
      *→ {a b c} {d e f} j*
**lset** x end-1 j
      *→ {a b c} j {g h i}*
**lset** x 2 1 j
      *→ {a b c} {d e f} {g j i}*
**lset** x {2 1} j
      *→ {a b c} {d e f} {g j i}*
**lset** x {2 3} j
      *→ list index out of range*
```
  In the following examples, the initial value of *x* is: 



```
set x [list [list [list a b] [list c d]] \
            [list [list e f] [list g h]]]
      *→ {{a b} {c d}} {{e f} {g h}}*
```
  The indicated return value also becomes the new value of *x*. 



```
**lset** x 1 1 0 j
      *→ {{a b} {c d}} {{e f} {j h}}*
**lset** x {1 1 0} j
      *→ {{a b} {c d}} {{e f} {j h}}*
```
 See also
--------

 **[list](list.htm)**, **[lappend](lappend.htm)**, **[lindex](lindex.htm)**, **[linsert](linsert.htm)**, **[llength](llength.htm)**, **[lsearch](lsearch.htm)**, **[lsort](lsort.htm)**, **[lrange](lrange.htm)**, **[lreplace](lreplace.htm)**, **[string](string.htm)** Copyright © 2001 by Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/lset.htm>

colors
======

 Name
----

 colors — symbolic color names recognized by Tk Description
-----------

 Tk recognizes many symbolic color names (e.g., **red**) when specifying colors. The symbolic names recognized by Tk and their 8-bit-per-channel RGB values are: 

|  |  |  |  |
| --- | --- | --- | --- |
| **Name** | **Red** | **Green** | **Blue** |
| alice blue | 240 | 248  | 255 |
| AliceBlue | 240 | 248  | 255 |
| antique white | 250 | 235  | 215 |
| AntiqueWhite | 250 | 235  | 215 |
| AntiqueWhite1 | 255 | 239  | 219 |
| AntiqueWhite2 | 238 | 223  | 204 |
| AntiqueWhite3 | 205 | 192  | 176 |
| AntiqueWhite4 | 139 | 131  | 120 |
| agua | 0 | 255 | 255 |
| aquamarine | 127 | 255  | 212 |
| aquamarine1 | 127 | 255  | 212 |
| aquamarine2 | 118 | 238  | 198 |
| aquamarine3 | 102 | 205  | 170 |
| aquamarine4 | 69 | 139  | 116 |
| azure | 240 | 255  | 255 |
| azure1 | 240 | 255  | 255 |
| azure2 | 224 | 238  | 238 |
| azure3 | 193 | 205  | 205 |
| azure4 | 131 | 139  | 139 |
| beige | 245 | 245  | 220 |
| bisque | 255 | 228  | 196 |
| bisque1 | 255 | 228  | 196 |
| bisque2 | 238 | 213  | 183 |
| bisque3 | 205 | 183  | 158 |
| bisque4 | 139 | 125  | 107 |
| black | 0 | 0  | 0 |
| blanched almond | 255 | 235  | 205 |
| BlanchedAlmond | 255 | 235  | 205 |
| blue | 0 | 0  | 255 |
| blue violet | 138 | 43  | 226 |
| blue1 | 0 | 0  | 255 |
| blue2 | 0 | 0  | 238 |
| blue3 | 0 | 0  | 205 |
| blue4 | 0 | 0  | 139 |
| BlueViolet | 138 | 43  | 226 |
| brown | 165 | 42  | 42 |
| brown1 | 255 | 64  | 64 |
| brown2 | 238 | 59  | 59 |
| brown3 | 205 | 51  | 51 |
| brown4 | 139 | 35  | 35 |
| burlywood | 222 | 184  | 135 |
| burlywood1 | 255 | 211  | 155 |
| burlywood2 | 238 | 197  | 145 |
| burlywood3 | 205 | 170  | 125 |
| burlywood4 | 139 | 115  | 85 |
| cadet blue | 95 | 158  | 160 |
| CadetBlue | 95 | 158  | 160 |
| CadetBlue1 | 152 | 245  | 255 |
| CadetBlue2 | 142 | 229  | 238 |
| CadetBlue3 | 122 | 197  | 205 |
| CadetBlue4 | 83 | 134  | 139 |
| chartreuse | 127 | 255  | 0 |
| chartreuse1 | 127 | 255  | 0 |
| chartreuse2 | 118 | 238  | 0 |
| chartreuse3 | 102 | 205  | 0 |
| chartreuse4 | 69 | 139  | 0 |
| chocolate | 210 | 105  | 30 |
| chocolate1 | 255 | 127  | 36 |
| chocolate2 | 238 | 118  | 33 |
| chocolate3 | 205 | 102  | 29 |
| chocolate4 | 139 | 69  | 19 |
| coral | 255 | 127  | 80 |
| coral1 | 255 | 114  | 86 |
| coral2 | 238 | 106  | 80 |
| coral3 | 205 | 91  | 69 |
| coral4 | 139 | 62  | 47 |
| cornflower blue | 100 | 149  | 237 |
| CornflowerBlue | 100 | 149  | 237 |
| cornsilk | 255 | 248  | 220 |
| cornsilk1 | 255 | 248  | 220 |
| cornsilk2 | 238 | 232  | 205 |
| cornsilk3 | 205 | 200  | 177 |
| cornsilk4 | 139 | 136  | 120 |
| crymson | 220 | 20 | 60 |
| cyan | 0 | 255  | 255 |
| cyan1 | 0 | 255  | 255 |
| cyan2 | 0 | 238  | 238 |
| cyan3 | 0 | 205  | 205 |
| cyan4 | 0 | 139  | 139 |
| dark blue | 0 | 0  | 139 |
| dark cyan | 0 | 139  | 139 |
| dark goldenrod | 184 | 134  | 11 |
| dark gray | 169 | 169  | 169 |
| dark green | 0 | 100  | 0 |
| dark grey | 169 | 169  | 169 |
| dark khaki | 189 | 183  | 107 |
| dark magenta | 139 | 0  | 139 |
| dark olive green | 85 | 107  | 47 |
| dark orange | 255 | 140  | 0 |
| dark orchid | 153 | 50  | 204 |
| dark red | 139 | 0  | 0 |
| dark salmon | 233 | 150  | 122 |
| dark sea green | 143 | 188  | 143 |
| dark slate blue | 72 | 61  | 139 |
| dark slate gray | 47 | 79  | 79 |
| dark slate grey | 47 | 79  | 79 |
| dark turquoise | 0 | 206  | 209 |
| dark violet | 148 | 0  | 211 |
| DarkBlue | 0 | 0  | 139 |
| DarkCyan | 0 | 139  | 139 |
| DarkGoldenrod | 184 | 134  | 11 |
| DarkGoldenrod1 | 255 | 185  | 15 |
| DarkGoldenrod2 | 238 | 173  | 14 |
| DarkGoldenrod3 | 205 | 149  | 12 |
| DarkGoldenrod4 | 139 | 101  | 8 |
| DarkGray | 169 | 169  | 169 |
| DarkGreen | 0 | 100  | 0 |
| DarkGrey | 169 | 169  | 169 |
| DarkKhaki | 189 | 183  | 107 |
| DarkMagenta | 139 | 0  | 139 |
| DarkOliveGreen | 85 | 107  | 47 |
| DarkOliveGreen1 | 202 | 255  | 112 |
| DarkOliveGreen2 | 188 | 238  | 104 |
| DarkOliveGreen3 | 162 | 205  | 90 |
| DarkOliveGreen4 | 110 | 139  | 61 |
| DarkOrange | 255 | 140  | 0 |
| DarkOrange1 | 255 | 127  | 0 |
| DarkOrange2 | 238 | 118  | 0 |
| DarkOrange3 | 205 | 102  | 0 |
| DarkOrange4 | 139 | 69  | 0 |
| DarkOrchid | 153 | 50  | 204 |
| DarkOrchid1 | 191 | 62  | 255 |
| DarkOrchid2 | 178 | 58  | 238 |
| DarkOrchid3 | 154 | 50  | 205 |
| DarkOrchid4 | 104 | 34  | 139 |
| DarkRed | 139 | 0  | 0 |
| DarkSalmon | 233 | 150  | 122 |
| DarkSeaGreen | 143 | 188  | 143 |
| DarkSeaGreen1 | 193 | 255  | 193 |
| DarkSeaGreen2 | 180 | 238  | 180 |
| DarkSeaGreen3 | 155 | 205  | 155 |
| DarkSeaGreen4 | 105 | 139  | 105 |
| DarkSlateBlue | 72 | 61  | 139 |
| DarkSlateGray | 47 | 79  | 79 |
| DarkSlateGray1 | 151 | 255  | 255 |
| DarkSlateGray2 | 141 | 238  | 238 |
| DarkSlateGray3 | 121 | 205  | 205 |
| DarkSlateGray4 | 82 | 139  | 139 |
| DarkSlateGrey | 47 | 79  | 79 |
| DarkTurquoise | 0 | 206  | 209 |
| DarkViolet | 148 | 0  | 211 |
| deep pink | 255 | 20  | 147 |
| deep sky blue | 0 | 191  | 255 |
| DeepPink | 255 | 20  | 147 |
| DeepPink1 | 255 | 20  | 147 |
| DeepPink2 | 238 | 18  | 137 |
| DeepPink3 | 205 | 16  | 118 |
| DeepPink4 | 139 | 10  | 80 |
| DeepSkyBlue | 0 | 191  | 255 |
| DeepSkyBlue1 | 0 | 191  | 255 |
| DeepSkyBlue2 | 0 | 178  | 238 |
| DeepSkyBlue3 | 0 | 154  | 205 |
| DeepSkyBlue4 | 0 | 104  | 139 |
| dim gray | 105 | 105  | 105 |
| dim grey | 105 | 105  | 105 |
| DimGray | 105 | 105  | 105 |
| DimGrey | 105 | 105  | 105 |
| dodger blue | 30 | 144  | 255 |
| DodgerBlue | 30 | 144  | 255 |
| DodgerBlue1 | 30 | 144  | 255 |
| DodgerBlue2 | 28 | 134  | 238 |
| DodgerBlue3 | 24 | 116  | 205 |
| DodgerBlue4 | 16 | 78  | 139 |
| firebrick | 178 | 34  | 34 |
| firebrick1 | 255 | 48  | 48 |
| firebrick2 | 238 | 44  | 44 |
| firebrick3 | 205 | 38  | 38 |
| firebrick4 | 139 | 26  | 26 |
| floral white | 255 | 250  | 240 |
| FloralWhite | 255 | 250  | 240 |
| forest green | 34 | 139  | 34 |
| ForestGreen | 34 | 139  | 34 |
| fuchsia | 255 | 0 | 255 |
| gainsboro | 220 | 220  | 220 |
| ghost white | 248 | 248  | 255 |
| GhostWhite | 248 | 248  | 255 |
| gold | 255 | 215  | 0 |
| gold1 | 255 | 215  | 0 |
| gold2 | 238 | 201  | 0 |
| gold3 | 205 | 173  | 0 |
| gold4 | 139 | 117  | 0 |
| goldenrod | 218 | 165  | 32 |
| goldenrod1 | 255 | 193  | 37 |
| goldenrod2 | 238 | 180  | 34 |
| goldenrod3 | 205 | 155  | 29 |
| goldenrod4 | 139 | 105  | 20 |
| gray | 128 | 128 | 128 |
| gray0 | 0 | 0  | 0 |
| gray1 | 3 | 3  | 3 |
| gray2 | 5 | 5  | 5 |
| gray3 | 8 | 8  | 8 |
| gray4 | 10 | 10  | 10 |
| gray5 | 13 | 13  | 13 |
| gray6 | 15 | 15  | 15 |
| gray7 | 18 | 18  | 18 |
| gray8 | 20 | 20  | 20 |
| gray9 | 23 | 23  | 23 |
| gray10 | 26 | 26  | 26 |
| gray11 | 28 | 28  | 28 |
| gray12 | 31 | 31  | 31 |
| gray13 | 33 | 33  | 33 |
| gray14 | 36 | 36  | 36 |
| gray15 | 38 | 38  | 38 |
| gray16 | 41 | 41  | 41 |
| gray17 | 43 | 43  | 43 |
| gray18 | 46 | 46  | 46 |
| gray19 | 48 | 48  | 48 |
| gray20 | 51 | 51  | 51 |
| gray21 | 54 | 54  | 54 |
| gray22 | 56 | 56  | 56 |
| gray23 | 59 | 59  | 59 |
| gray24 | 61 | 61  | 61 |
| gray25 | 64 | 64  | 64 |
| gray26 | 66 | 66  | 66 |
| gray27 | 69 | 69  | 69 |
| gray28 | 71 | 71  | 71 |
| gray29 | 74 | 74  | 74 |
| gray30 | 77 | 77  | 77 |
| gray31 | 79 | 79  | 79 |
| gray32 | 82 | 82  | 82 |
| gray33 | 84 | 84  | 84 |
| gray34 | 87 | 87  | 87 |
| gray35 | 89 | 89  | 89 |
| gray36 | 92 | 92  | 92 |
| gray37 | 94 | 94  | 94 |
| gray38 | 97 | 97  | 97 |
| gray39 | 99 | 99  | 99 |
| gray40 | 102 | 102  | 102 |
| gray41 | 105 | 105  | 105 |
| gray42 | 107 | 107  | 107 |
| gray43 | 110 | 110  | 110 |
| gray44 | 112 | 112  | 112 |
| gray45 | 115 | 115  | 115 |
| gray46 | 117 | 117  | 117 |
| gray47 | 120 | 120  | 120 |
| gray48 | 122 | 122  | 122 |
| gray49 | 125 | 125  | 125 |
| gray50 | 127 | 127  | 127 |
| gray51 | 130 | 130  | 130 |
| gray52 | 133 | 133  | 133 |
| gray53 | 135 | 135  | 135 |
| gray54 | 138 | 138  | 138 |
| gray55 | 140 | 140  | 140 |
| gray56 | 143 | 143  | 143 |
| gray57 | 145 | 145  | 145 |
| gray58 | 148 | 148  | 148 |
| gray59 | 150 | 150  | 150 |
| gray60 | 153 | 153  | 153 |
| gray61 | 156 | 156  | 156 |
| gray62 | 158 | 158  | 158 |
| gray63 | 161 | 161  | 161 |
| gray64 | 163 | 163  | 163 |
| gray65 | 166 | 166  | 166 |
| gray66 | 168 | 168  | 168 |
| gray67 | 171 | 171  | 171 |
| gray68 | 173 | 173  | 173 |
| gray69 | 176 | 176  | 176 |
| gray70 | 179 | 179  | 179 |
| gray71 | 181 | 181  | 181 |
| gray72 | 184 | 184  | 184 |
| gray73 | 186 | 186  | 186 |
| gray74 | 189 | 189  | 189 |
| gray75 | 191 | 191  | 191 |
| gray76 | 194 | 194  | 194 |
| gray77 | 196 | 196  | 196 |
| gray78 | 199 | 199  | 199 |
| gray79 | 201 | 201  | 201 |
| gray80 | 204 | 204  | 204 |
| gray81 | 207 | 207  | 207 |
| gray82 | 209 | 209  | 209 |
| gray83 | 212 | 212  | 212 |
| gray84 | 214 | 214  | 214 |
| gray85 | 217 | 217  | 217 |
| gray86 | 219 | 219  | 219 |
| gray87 | 222 | 222  | 222 |
| gray88 | 224 | 224  | 224 |
| gray89 | 227 | 227  | 227 |
| gray90 | 229 | 229  | 229 |
| gray91 | 232 | 232  | 232 |
| gray92 | 235 | 235  | 235 |
| gray93 | 237 | 237  | 237 |
| gray94 | 240 | 240  | 240 |
| gray95 | 242 | 242  | 242 |
| gray96 | 245 | 245  | 245 |
| gray97 | 247 | 247  | 247 |
| gray98 | 250 | 250  | 250 |
| gray99 | 252 | 252  | 252 |
| gray100 | 255 | 255  | 255 |
| green | 0 | 128  | 0 |
| green yellow | 173 | 255  | 47 |
| green1 | 0 | 255  | 0 |
| green2 | 0 | 238  | 0 |
| green3 | 0 | 205  | 0 |
| green4 | 0 | 139  | 0 |
| GreenYellow | 173 | 255  | 47 |
| grey | 128 | 128 | 128 |
| grey0 | 0 | 0  | 0 |
| grey1 | 3 | 3  | 3 |
| grey2 | 5 | 5  | 5 |
| grey3 | 8 | 8  | 8 |
| grey4 | 10 | 10  | 10 |
| grey5 | 13 | 13  | 13 |
| grey6 | 15 | 15  | 15 |
| grey7 | 18 | 18  | 18 |
| grey8 | 20 | 20  | 20 |
| grey9 | 23 | 23  | 23 |
| grey10 | 26 | 26  | 26 |
| grey11 | 28 | 28  | 28 |
| grey12 | 31 | 31  | 31 |
| grey13 | 33 | 33  | 33 |
| grey14 | 36 | 36  | 36 |
| grey15 | 38 | 38  | 38 |
| grey16 | 41 | 41  | 41 |
| grey17 | 43 | 43  | 43 |
| grey18 | 46 | 46  | 46 |
| grey19 | 48 | 48  | 48 |
| grey20 | 51 | 51  | 51 |
| grey21 | 54 | 54  | 54 |
| grey22 | 56 | 56  | 56 |
| grey23 | 59 | 59  | 59 |
| grey24 | 61 | 61  | 61 |
| grey25 | 64 | 64  | 64 |
| grey26 | 66 | 66  | 66 |
| grey27 | 69 | 69  | 69 |
| grey28 | 71 | 71  | 71 |
| grey29 | 74 | 74  | 74 |
| grey30 | 77 | 77  | 77 |
| grey31 | 79 | 79  | 79 |
| grey32 | 82 | 82  | 82 |
| grey33 | 84 | 84  | 84 |
| grey34 | 87 | 87  | 87 |
| grey35 | 89 | 89  | 89 |
| grey36 | 92 | 92  | 92 |
| grey37 | 94 | 94  | 94 |
| grey38 | 97 | 97  | 97 |
| grey39 | 99 | 99  | 99 |
| grey40 | 102 | 102  | 102 |
| grey41 | 105 | 105  | 105 |
| grey42 | 107 | 107  | 107 |
| grey43 | 110 | 110  | 110 |
| grey44 | 112 | 112  | 112 |
| grey45 | 115 | 115  | 115 |
| grey46 | 117 | 117  | 117 |
| grey47 | 120 | 120  | 120 |
| grey48 | 122 | 122  | 122 |
| grey49 | 125 | 125  | 125 |
| grey50 | 127 | 127  | 127 |
| grey51 | 130 | 130  | 130 |
| grey52 | 133 | 133  | 133 |
| grey53 | 135 | 135  | 135 |
| grey54 | 138 | 138  | 138 |
| grey55 | 140 | 140  | 140 |
| grey56 | 143 | 143  | 143 |
| grey57 | 145 | 145  | 145 |
| grey58 | 148 | 148  | 148 |
| grey59 | 150 | 150  | 150 |
| grey60 | 153 | 153  | 153 |
| grey61 | 156 | 156  | 156 |
| grey62 | 158 | 158  | 158 |
| grey63 | 161 | 161  | 161 |
| grey64 | 163 | 163  | 163 |
| grey65 | 166 | 166  | 166 |
| grey66 | 168 | 168  | 168 |
| grey67 | 171 | 171  | 171 |
| grey68 | 173 | 173  | 173 |
| grey69 | 176 | 176  | 176 |
| grey70 | 179 | 179  | 179 |
| grey71 | 181 | 181  | 181 |
| grey72 | 184 | 184  | 184 |
| grey73 | 186 | 186  | 186 |
| grey74 | 189 | 189  | 189 |
| grey75 | 191 | 191  | 191 |
| grey76 | 194 | 194  | 194 |
| grey77 | 196 | 196  | 196 |
| grey78 | 199 | 199  | 199 |
| grey79 | 201 | 201  | 201 |
| grey80 | 204 | 204  | 204 |
| grey81 | 207 | 207  | 207 |
| grey82 | 209 | 209  | 209 |
| grey83 | 212 | 212  | 212 |
| grey84 | 214 | 214  | 214 |
| grey85 | 217 | 217  | 217 |
| grey86 | 219 | 219  | 219 |
| grey87 | 222 | 222  | 222 |
| grey88 | 224 | 224  | 224 |
| grey89 | 227 | 227  | 227 |
| grey90 | 229 | 229  | 229 |
| grey91 | 232 | 232  | 232 |
| grey92 | 235 | 235  | 235 |
| grey93 | 237 | 237  | 237 |
| grey94 | 240 | 240  | 240 |
| grey95 | 242 | 242  | 242 |
| grey96 | 245 | 245  | 245 |
| grey97 | 247 | 247  | 247 |
| grey98 | 250 | 250  | 250 |
| grey99 | 252 | 252  | 252 |
| grey100 | 255 | 255  | 255 |
| honeydew | 240 | 255  | 240 |
| honeydew1 | 240 | 255  | 240 |
| honeydew2 | 224 | 238  | 224 |
| honeydew3 | 193 | 205  | 193 |
| honeydew4 | 131 | 139  | 131 |
| hot pink | 255 | 105  | 180 |
| HotPink | 255 | 105  | 180 |
| HotPink1 | 255 | 110  | 180 |
| HotPink2 | 238 | 106  | 167 |
| HotPink3 | 205 | 96  | 144 |
| HotPink4 | 139 | 58  | 98 |
| indian red | 205 | 92  | 92 |
| IndianRed | 205 | 92  | 92 |
| IndianRed1 | 255 | 106  | 106 |
| IndianRed2 | 238 | 99  | 99 |
| IndianRed3 | 205 | 85  | 85 |
| IndianRed4 | 139 | 58  | 58 |
| indigo | 75 | 0 | 130 |
| ivory | 255 | 255  | 240 |
| ivory1 | 255 | 255  | 240 |
| ivory2 | 238 | 238  | 224 |
| ivory3 | 205 | 205  | 193 |
| ivory4 | 139 | 139  | 131 |
| khaki | 240 | 230  | 140 |
| khaki1 | 255 | 246  | 143 |
| khaki2 | 238 | 230  | 133 |
| khaki3 | 205 | 198  | 115 |
| khaki4 | 139 | 134  | 78 |
| lavender | 230 | 230  | 250 |
| lavender blush | 255 | 240  | 245 |
| LavenderBlush | 255 | 240  | 245 |
| LavenderBlush1 | 255 | 240  | 245 |
| LavenderBlush2 | 238 | 224  | 229 |
| LavenderBlush3 | 205 | 193  | 197 |
| LavenderBlush4 | 139 | 131  | 134 |
| lawn green | 124 | 252  | 0 |
| LawnGreen | 124 | 252  | 0 |
| lemon chiffon | 255 | 250  | 205 |
| LemonChiffon | 255 | 250  | 205 |
| LemonChiffon1 | 255 | 250  | 205 |
| LemonChiffon2 | 238 | 233  | 191 |
| LemonChiffon3 | 205 | 201  | 165 |
| LemonChiffon4 | 139 | 137  | 112 |
| light blue | 173 | 216  | 230 |
| light coral | 240 | 128  | 128 |
| light cyan | 224 | 255  | 255 |
| light goldenrod | 238 | 221  | 130 |
| light goldenrod yellow | 250 | 250  | 210 |
| light gray | 211 | 211  | 211 |
| light green | 144 | 238  | 144 |
| light grey | 211 | 211  | 211 |
| light pink | 255 | 182  | 193 |
| light salmon | 255 | 160  | 122 |
| light sea green | 32 | 178  | 170 |
| light sky blue | 135 | 206  | 250 |
| light slate blue | 132 | 112  | 255 |
| light slate gray | 119 | 136  | 153 |
| light slate grey | 119 | 136  | 153 |
| light steel blue | 176 | 196  | 222 |
| light yellow | 255 | 255  | 224 |
| LightBlue | 173 | 216  | 230 |
| LightBlue1 | 191 | 239  | 255 |
| LightBlue2 | 178 | 223  | 238 |
| LightBlue3 | 154 | 192  | 205 |
| LightBlue4 | 104 | 131  | 139 |
| LightCoral | 240 | 128  | 128 |
| LightCyan | 224 | 255  | 255 |
| LightCyan1 | 224 | 255  | 255 |
| LightCyan2 | 209 | 238  | 238 |
| LightCyan3 | 180 | 205  | 205 |
| LightCyan4 | 122 | 139  | 139 |
| LightGoldenrod | 238 | 221  | 130 |
| LightGoldenrod1 | 255 | 236  | 139 |
| LightGoldenrod2 | 238 | 220  | 130 |
| LightGoldenrod3 | 205 | 190  | 112 |
| LightGoldenrod4 | 139 | 129  | 76 |
| LightGoldenrodYellow | 250 | 250  | 210 |
| LightGray | 211 | 211  | 211 |
| LightGreen | 144 | 238  | 144 |
| LightGrey | 211 | 211  | 211 |
| LightPink | 255 | 182  | 193 |
| LightPink1 | 255 | 174  | 185 |
| LightPink2 | 238 | 162  | 173 |
| LightPink3 | 205 | 140  | 149 |
| LightPink4 | 139 | 95  | 101 |
| LightSalmon | 255 | 160  | 122 |
| LightSalmon1 | 255 | 160  | 122 |
| LightSalmon2 | 238 | 149  | 114 |
| LightSalmon3 | 205 | 129  | 98 |
| LightSalmon4 | 139 | 87  | 66 |
| LightSeaGreen | 32 | 178  | 170 |
| LightSkyBlue | 135 | 206  | 250 |
| LightSkyBlue1 | 176 | 226  | 255 |
| LightSkyBlue2 | 164 | 211  | 238 |
| LightSkyBlue3 | 141 | 182  | 205 |
| LightSkyBlue4 | 96 | 123  | 139 |
| LightSlateBlue | 132 | 112  | 255 |
| LightSlateGray | 119 | 136  | 153 |
| LightSlateGrey | 119 | 136  | 153 |
| LightSteelBlue | 176 | 196  | 222 |
| LightSteelBlue1 | 202 | 225  | 255 |
| LightSteelBlue2 | 188 | 210  | 238 |
| LightSteelBlue3 | 162 | 181  | 205 |
| LightSteelBlue4 | 110 | 123  | 139 |
| LightYellow | 255 | 255  | 224 |
| LightYellow1 | 255 | 255  | 224 |
| LightYellow2 | 238 | 238  | 209 |
| LightYellow3 | 205 | 205  | 180 |
| LightYellow4 | 139 | 139  | 122 |
| lime | 0 | 255 | 0 |
| lime green | 50 | 205  | 50 |
| LimeGreen | 50 | 205  | 50 |
| linen | 250 | 240  | 230 |
| magenta | 255 | 0  | 255 |
| magenta1 | 255 | 0  | 255 |
| magenta2 | 238 | 0  | 238 |
| magenta3 | 205 | 0  | 205 |
| magenta4 | 139 | 0  | 139 |
| maroon | 128 | 0  | 0 |
| maroon1 | 255 | 52  | 179 |
| maroon2 | 238 | 48  | 167 |
| maroon3 | 205 | 41  | 144 |
| maroon4 | 139 | 28  | 98 |
| medium aquamarine | 102 | 205  | 170 |
| medium blue | 0 | 0  | 205 |
| medium orchid | 186 | 85  | 211 |
| medium purple | 147 | 112  | 219 |
| medium sea green | 60 | 179  | 113 |
| medium slate blue | 123 | 104  | 238 |
| medium spring green | 0 | 250  | 154 |
| medium turquoise | 72 | 209  | 204 |
| medium violet red | 199 | 21  | 133 |
| MediumAquamarine | 102 | 205  | 170 |
| MediumBlue | 0 | 0  | 205 |
| MediumOrchid | 186 | 85  | 211 |
| MediumOrchid1 | 224 | 102  | 255 |
| MediumOrchid2 | 209 | 95  | 238 |
| MediumOrchid3 | 180 | 82  | 205 |
| MediumOrchid4 | 122 | 55  | 139 |
| MediumPurple | 147 | 112  | 219 |
| MediumPurple1 | 171 | 130  | 255 |
| MediumPurple2 | 159 | 121  | 238 |
| MediumPurple3 | 137 | 104  | 205 |
| MediumPurple4 | 93 | 71  | 139 |
| MediumSeaGreen | 60 | 179  | 113 |
| MediumSlateBlue | 123 | 104  | 238 |
| MediumSpringGreen | 0 | 250  | 154 |
| MediumTurquoise | 72 | 209  | 204 |
| MediumVioletRed | 199 | 21  | 133 |
| midnight blue | 25 | 25  | 112 |
| MidnightBlue | 25 | 25  | 112 |
| mint cream | 245 | 255  | 250 |
| MintCream | 245 | 255  | 250 |
| misty rose | 255 | 228  | 225 |
| MistyRose | 255 | 228  | 225 |
| MistyRose1 | 255 | 228  | 225 |
| MistyRose2 | 238 | 213  | 210 |
| MistyRose3 | 205 | 183  | 181 |
| MistyRose4 | 139 | 125  | 123 |
| moccasin | 255 | 228  | 181 |
| navajo white | 255 | 222  | 173 |
| NavajoWhite | 255 | 222  | 173 |
| NavajoWhite1 | 255 | 222  | 173 |
| NavajoWhite2 | 238 | 207  | 161 |
| NavajoWhite3 | 205 | 179  | 139 |
| NavajoWhite4 | 139 | 121  | 94 |
| navy | 0 | 0  | 128 |
| navy blue | 0 | 0  | 128 |
| NavyBlue | 0 | 0  | 128 |
| old lace | 253 | 245  | 230 |
| OldLace | 253 | 245  | 230 |
| olive | 128 | 128 | 0 |
| olive drab | 107 | 142  | 35 |
| OliveDrab | 107 | 142  | 35 |
| OliveDrab1 | 192 | 255  | 62 |
| OliveDrab2 | 179 | 238  | 58 |
| OliveDrab3 | 154 | 205  | 50 |
| OliveDrab4 | 105 | 139  | 34 |
| orange | 255 | 165  | 0 |
| orange red | 255 | 69  | 0 |
| orange1 | 255 | 165  | 0 |
| orange2 | 238 | 154  | 0 |
| orange3 | 205 | 133  | 0 |
| orange4 | 139 | 90  | 0 |
| OrangeRed | 255 | 69  | 0 |
| OrangeRed1 | 255 | 69  | 0 |
| OrangeRed2 | 238 | 64  | 0 |
| OrangeRed3 | 205 | 55  | 0 |
| OrangeRed4 | 139 | 37  | 0 |
| orchid | 218 | 112  | 214 |
| orchid1 | 255 | 131  | 250 |
| orchid2 | 238 | 122  | 233 |
| orchid3 | 205 | 105  | 201 |
| orchid4 | 139 | 71  | 137 |
| pale goldenrod | 238 | 232  | 170 |
| pale green | 152 | 251  | 152 |
| pale turquoise | 175 | 238  | 238 |
| pale violet red | 219 | 112  | 147 |
| PaleGoldenrod | 238 | 232  | 170 |
| PaleGreen | 152 | 251  | 152 |
| PaleGreen1 | 154 | 255  | 154 |
| PaleGreen2 | 144 | 238  | 144 |
| PaleGreen3 | 124 | 205  | 124 |
| PaleGreen4 | 84 | 139  | 84 |
| PaleTurquoise | 175 | 238  | 238 |
| PaleTurquoise1 | 187 | 255  | 255 |
| PaleTurquoise2 | 174 | 238  | 238 |
| PaleTurquoise3 | 150 | 205  | 205 |
| PaleTurquoise4 | 102 | 139  | 139 |
| PaleVioletRed | 219 | 112  | 147 |
| PaleVioletRed1 | 255 | 130  | 171 |
| PaleVioletRed2 | 238 | 121  | 159 |
| PaleVioletRed3 | 205 | 104  | 127 |
| PaleVioletRed4 | 139 | 71  | 93 |
| papaya whip | 255 | 239  | 213 |
| PapayaWhip | 255 | 239  | 213 |
| peach puff | 255 | 218  | 185 |
| PeachPuff | 255 | 218  | 185 |
| PeachPuff1 | 255 | 218  | 185 |
| PeachPuff2 | 238 | 203  | 173 |
| PeachPuff3 | 205 | 175  | 149 |
| PeachPuff4 | 139 | 119  | 101 |
| peru | 205 | 133  | 63 |
| pink | 255 | 192  | 203 |
| pink1 | 255 | 181  | 197 |
| pink2 | 238 | 169  | 184 |
| pink3 | 205 | 145  | 158 |
| pink4 | 139 | 99  | 108 |
| plum | 221 | 160  | 221 |
| plum1 | 255 | 187  | 255 |
| plum2 | 238 | 174  | 238 |
| plum3 | 205 | 150  | 205 |
| plum4 | 139 | 102  | 139 |
| powder blue | 176 | 224  | 230 |
| PowderBlue | 176 | 224  | 230 |
| purple | 128 | 0  | 128 |
| purple1 | 155 | 48  | 255 |
| purple2 | 145 | 44  | 238 |
| purple3 | 125 | 38  | 205 |
| purple4 | 85 | 26  | 139 |
| red | 255 | 0  | 0 |
| red1 | 255 | 0  | 0 |
| red2 | 238 | 0  | 0 |
| red3 | 205 | 0  | 0 |
| red4 | 139 | 0  | 0 |
| rosy brown | 188 | 143  | 143 |
| RosyBrown | 188 | 143  | 143 |
| RosyBrown1 | 255 | 193  | 193 |
| RosyBrown2 | 238 | 180  | 180 |
| RosyBrown3 | 205 | 155  | 155 |
| RosyBrown4 | 139 | 105  | 105 |
| royal blue | 65 | 105  | 225 |
| RoyalBlue | 65 | 105  | 225 |
| RoyalBlue1 | 72 | 118  | 255 |
| RoyalBlue2 | 67 | 110  | 238 |
| RoyalBlue3 | 58 | 95  | 205 |
| RoyalBlue4 | 39 | 64  | 139 |
| saddle brown | 139 | 69  | 19 |
| SaddleBrown | 139 | 69  | 19 |
| salmon | 250 | 128  | 114 |
| salmon1 | 255 | 140  | 105 |
| salmon2 | 238 | 130  | 98 |
| salmon3 | 205 | 112  | 84 |
| salmon4 | 139 | 76  | 57 |
| sandy brown | 244 | 164  | 96 |
| SandyBrown | 244 | 164  | 96 |
| sea green | 46 | 139  | 87 |
| SeaGreen | 46 | 139  | 87 |
| SeaGreen1 | 84 | 255  | 159 |
| SeaGreen2 | 78 | 238  | 148 |
| SeaGreen3 | 67 | 205  | 128 |
| SeaGreen4 | 46 | 139  | 87 |
| seashell | 255 | 245  | 238 |
| seashell1 | 255 | 245  | 238 |
| seashell2 | 238 | 229  | 222 |
| seashell3 | 205 | 197  | 191 |
| seashell4 | 139 | 134  | 130 |
| sienna | 160 | 82  | 45 |
| sienna1 | 255 | 130  | 71 |
| sienna2 | 238 | 121  | 66 |
| sienna3 | 205 | 104  | 57 |
| sienna4 | 139 | 71  | 38 |
| silver | 192 | 192 | 192 |
| sky blue | 135 | 206  | 235 |
| SkyBlue | 135 | 206  | 235 |
| SkyBlue1 | 135 | 206  | 255 |
| SkyBlue2 | 126 | 192  | 238 |
| SkyBlue3 | 108 | 166  | 205 |
| SkyBlue4 | 74 | 112  | 139 |
| slate blue | 106 | 90  | 205 |
| slate gray | 112 | 128  | 144 |
| slate grey | 112 | 128  | 144 |
| SlateBlue | 106 | 90  | 205 |
| SlateBlue1 | 131 | 111  | 255 |
| SlateBlue2 | 122 | 103  | 238 |
| SlateBlue3 | 105 | 89  | 205 |
| SlateBlue4 | 71 | 60  | 139 |
| SlateGray | 112 | 128  | 144 |
| SlateGray1 | 198 | 226  | 255 |
| SlateGray2 | 185 | 211  | 238 |
| SlateGray3 | 159 | 182  | 205 |
| SlateGray4 | 108 | 123  | 139 |
| SlateGrey | 112 | 128  | 144 |
| snow | 255 | 250  | 250 |
| snow1 | 255 | 250  | 250 |
| snow2 | 238 | 233  | 233 |
| snow3 | 205 | 201  | 201 |
| snow4 | 139 | 137  | 137 |
| spring green | 0 | 255  | 127 |
| SpringGreen | 0 | 255  | 127 |
| SpringGreen1 | 0 | 255  | 127 |
| SpringGreen2 | 0 | 238  | 118 |
| SpringGreen3 | 0 | 205  | 102 |
| SpringGreen4 | 0 | 139  | 69 |
| steel blue | 70 | 130  | 180 |
| SteelBlue | 70 | 130  | 180 |
| SteelBlue1 | 99 | 184  | 255 |
| SteelBlue2 | 92 | 172  | 238 |
| SteelBlue3 | 79 | 148  | 205 |
| SteelBlue4 | 54 | 100  | 139 |
| tan | 210 | 180  | 140 |
| tan1 | 255 | 165  | 79 |
| tan2 | 238 | 154  | 73 |
| tan3 | 205 | 133  | 63 |
| tan4 | 139 | 90  | 43 |
| teal | 0 | 128 | 128 |
| thistle | 216 | 191  | 216 |
| thistle1 | 255 | 225  | 255 |
| thistle2 | 238 | 210  | 238 |
| thistle3 | 205 | 181  | 205 |
| thistle4 | 139 | 123  | 139 |
| tomato | 255 | 99  | 71 |
| tomato1 | 255 | 99  | 71 |
| tomato2 | 238 | 92  | 66 |
| tomato3 | 205 | 79  | 57 |
| tomato4 | 139 | 54  | 38 |
| turquoise | 64 | 224  | 208 |
| turquoise1 | 0 | 245  | 255 |
| turquoise2 | 0 | 229  | 238 |
| turquoise3 | 0 | 197  | 205 |
| turquoise4 | 0 | 134  | 139 |
| violet | 238 | 130  | 238 |
| violet red | 208 | 32  | 144 |
| VioletRed | 208 | 32  | 144 |
| VioletRed1 | 255 | 62  | 150 |
| VioletRed2 | 238 | 58  | 140 |
| VioletRed3 | 205 | 50  | 120 |
| VioletRed4 | 139 | 34  | 82 |
| wheat | 245 | 222  | 179 |
| wheat1 | 255 | 231  | 186 |
| wheat2 | 238 | 216  | 174 |
| wheat3 | 205 | 186  | 150 |
| wheat4 | 139 | 126  | 102 |
| white | 255 | 255  | 255 |
| white smoke | 245 | 245  | 245 |
| WhiteSmoke | 245 | 245  | 245 |
| yellow | 255 | 255  | 0 |
| yellow green | 154 | 205  | 50 |
| yellow1 | 255 | 255  | 0 |
| yellow2 | 238 | 238  | 0 |
| yellow3 | 205 | 205  | 0 |
| yellow4 | 139 | 139  | 0 |
| YellowGreen | 154 | 205  | 50 |

 Portability issues
------------------

  **Mac OS X**
 On Mac OS X, the following additional system colors are available (note that the actual color values depend on the currently active OS theme, and typically many of these will in fact be patterns rather than pure colors): 

|  |
| --- |
| systemActiveAreaFill |
| systemAlertActiveText |
| systemAlertBackgroundActive |
| systemAlertBackgroundInactive |
| systemAlertInactiveText |
| systemAlternatePrimaryHighlightColor |
| systemAppleGuideCoachmark |
| systemBevelActiveDark |
| systemBevelActiveLight |
| systemBevelButtonActiveText |
| systemBevelButtonInactiveText |
| systemBevelButtonPressedText |
| systemBevelButtonStickyActiveText |
| systemBevelButtonStickyInactiveText |
| systemBevelInactiveDark |
| systemBevelInactiveLight |
| systemBlack |
| systemBlackText |
| systemButtonActiveDarkHighlight |
| systemButtonActiveDarkShadow |
| systemButtonActiveLightHighlight |
| systemButtonActiveLightShadow |
| systemButtonFace |
| systemButtonFaceActive |
| systemButtonFaceInactive |
| systemButtonFacePressed |
| systemButtonFrame |
| systemButtonFrameActive |
| systemButtonFrameInactive |
| systemButtonInactiveDarkHighlight |
| systemButtonInactiveDarkShadow |
| systemButtonInactiveLightHighlight |
| systemButtonInactiveLightShadow |
| systemButtonPressedDarkHighlight |
| systemButtonPressedDarkShadow |
| systemButtonPressedLightHighlight |
| systemButtonPressedLightShadow |
| systemButtonText |
| systemChasingArrows |
| systemDialogActiveText |
| systemDialogBackgroundActive |
| systemDialogBackgroundInactive |
| systemDialogInactiveText |
| systemDocumentWindowBackground |
| systemDocumentWindowTitleActiveText |
| systemDocumentWindowTitleInactiveText |
| systemDragHilite |
| systemDrawerBackground |
| systemFinderWindowBackground |
| systemFocusHighlight |
| systemHighlight |
| systemHighlightAlternate |
| systemHighlightSecondary |
| systemHighlightText |
| systemIconLabelBackground |
| systemIconLabelBackgroundSelected |
| systemIconLabelSelectedText |
| systemIconLabelText |
| systemListViewBackground |
| systemListViewColumnDivider |
| systemListViewEvenRowBackground |
| systemListViewOddRowBackground |
| systemListViewSeparator |
| systemListViewSortColumnBackground |
| systemListViewText |
| systemListViewWindowHeaderBackground |
| systemMenu |
| systemMenuActive |
| systemMenuActiveText |
| systemMenuBackground |
| systemMenuBackgroundSelected |
| systemMenuDisabled |
| systemMenuItemActiveText |
| systemMenuItemDisabledText |
| systemMenuItemSelectedText |
| systemMenuText |
| systemMetalBackground |
| systemModelessDialogActiveText |
| systemModelessDialogBackgroundActive |
| systemModelessDialogBackgroundInactive |
| systemModelessDialogInactiveText |
| systemMovableModalBackground |
| systemMovableModalWindowTitleActiveText |
| systemMovableModalWindowTitleInactiveText |
| systemNotificationText |
| systemNotificationWindowBackground |
| systemPlacardActiveText |
| systemPlacardBackground |
| systemPlacardInactiveText |
| systemPlacardPressedText |
| systemPopupArrowActive |
| systemPopupArrowInactive |
| systemPopupArrowPressed |
| systemPopupButtonActiveText |
| systemPopupButtonInactiveText |
| systemPopupButtonPressedText |
| systemPopupLabelActiveText |
| systemPopupLabelInactiveText |
| systemPopupWindowTitleActiveText |
| systemPopupWindowTitleInactiveText |
| systemPrimaryHighlightColor |
| systemPushButtonActiveText |
| systemPushButtonInactiveText |
| systemPushButtonPressedText |
| systemRootMenuActiveText |
| systemRootMenuDisabledText |
| systemRootMenuSelectedText |
| systemScrollBarDelimiterActive |
| systemScrollBarDelimiterInactive |
| systemSecondaryGroupBoxBackground |
| systemSecondaryHighlightColor |
| systemSheetBackground |
| systemSheetBackgroundOpaque |
| systemSheetBackgroundTransparent |
| systemStaticAreaFill |
| systemSystemDetailText |
| systemTabFrontActiveText |
| systemTabFrontInactiveText |
| systemTabNonFrontActiveText |
| systemTabNonFrontInactiveText |
| systemTabNonFrontPressedText |
| systemTabPaneBackground |
| systemToolbarBackground |
| systemTransparent |
| systemUtilityWindowBackgroundActive |
| systemUtilityWindowBackgroundInactive |
| systemUtilityWindowTitleActiveText |
| systemUtilityWindowTitleInactiveText |
| systemWhite |
| systemWhiteText |
| systemWindowBody |
| systemWindowHeaderActiveText |
| systemWindowHeaderBackground |
| systemWindowHeaderInactiveText |



**Windows**
 On Windows, the following additional system colors are available (note that the actual color values depend on the currently active OS theme): 

|  |  |
| --- | --- |
| system3dDarkShadow | systemHighlight |
| system3dLight | systemHighlightText |
| systemActiveBorder | systemInactiveBorder |
| systemActiveCaption | systemInactiveCaption |
| systemAppWorkspace | systemInactiveCaptionText |
| systemBackground | systemInfoBackground |
| systemButtonFace | systemInfoText |
| systemButtonHighlight | systemMenu |
| systemButtonShadow | systemMenuText |
| systemButtonText | systemScrollbar |
| systemCaptionText | systemWindow |
| systemDisabledText | systemWindowFrame |
| systemGrayText | systemWindowText |



 See also
--------

 **[options](options.htm)**, **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)** Copyright © 1998-2000 by Scriptics Corporation.  
 Copyright © 2003 ActiveState Corporation.  
 Copyright © 2006-2007 Daniel A. Steffen <das(at)users.sourceforge.net>  
 Copyright © 2008 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/colors.htm>

expr
====

  
[NAME](expr.htm#M2) expr — Evaluate an expression 
[SYNOPSIS](expr.htm#M3) 
[DESCRIPTION](expr.htm#M4) 
[OPERANDS](expr.htm#M5) 
[OPERATORS](expr.htm#M6)  
[**- + ~ !**](expr.htm#M7) 
[**\*\***](expr.htm#M8) 
[**\* / %**](expr.htm#M9) 
[**+ -**](expr.htm#M10) 
[**<< >>**](expr.htm#M11) 
[**< > <= >=**](expr.htm#M12) 
[**== !=**](expr.htm#M13) 
[**eq ne**](expr.htm#M14) 
[**in ni**](expr.htm#M15) 
[**&**](expr.htm#M16) 
[**^**](expr.htm#M17) 
[**|**](expr.htm#M18) 
[**&&**](expr.htm#M19) 
[**||**](expr.htm#M20) 
[*x***?***y***:***z*](expr.htm#M21) 














 
[MATH FUNCTIONS](expr.htm#M22) 
[TYPES, OVERFLOW, AND PRECISION](expr.htm#M23) 
[STRING OPERATIONS](expr.htm#M24) 
[PERFORMANCE CONSIDERATIONS](expr.htm#M25) 
[EXAMPLES](expr.htm#M26) 
[SEE ALSO](expr.htm#M27) 
[KEYWORDS](expr.htm#M28) 
[COPYRIGHT](expr.htm#M29) 












 Name
----

 expr — Evaluate an expression Synopsis
--------

 **expr** *arg* ?*arg arg ...*?  
 Description
-----------

 Concatenates *arg*s (adding separator spaces between them), evaluates the result as a Tcl expression, and returns the value. The operators permitted in Tcl expressions include a subset of the operators permitted in C expressions. For those operators common to both Tcl and C, Tcl applies the same meaning and precedence as the corresponding C operators. Expressions almost always yield numeric results (integer or floating-point values). For example, the expression 

```
**expr** 8.2 + 6
```
  evaluates to 14.2. Tcl expressions differ from C expressions in the way that operands are specified. Also, Tcl expressions support non-numeric operands and string comparisons, as well as some additional operators not found in C. 


### Operands

 A Tcl expression consists of a combination of operands, operators, parentheses and commas. White space may be used between the operands and operators and parentheses (or commas); it is ignored by the expression's instructions. Where possible, operands are interpreted as integer values. Integer values may be specified in decimal (the normal case), in binary (if the first two characters of the operand are **0b**), in octal (if the first two characters of the operand are **0o**), or in hexadecimal (if the first two characters of the operand are **0x**). For compatibility with older Tcl releases, an octal integer value is also indicated simply when the first character of the operand is **0**, whether or not the second character is also **o**. If an operand does not have one of the integer formats given above, then it is treated as a floating-point number if that is possible. Floating-point numbers may be specified in any of several common formats making use of the decimal digits, the decimal point **.**, the characters **e** or **E** indicating scientific notation, and the sign characters **+** or **-**. For example, all of the following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. Also recognized as floating point values are the strings **Inf** and **NaN** making use of any case for each character. If no numeric interpretation is possible (note that all literal operands that are not numeric or boolean must be quoted with either braces or with double quotes), then an operand is left as a string (and only a limited set of operators may be applied to it).  Operands may be specified in any of the following ways: 


1. As a numeric value, either integer or floating-point.
2. As a boolean value, using any form understood by **[string is](string.htm)** **boolean**.
3. As a Tcl variable, using standard **$** notation. The variable's value will be used as the operand.
4. As a string enclosed in double-quotes. The expression parser will perform backslash, variable, and command substitutions on the information between the quotes, and use the resulting value as the operand
5. As a string enclosed in braces. The characters between the open brace and matching close brace will be used as the operand without any substitutions.
6. As a Tcl command enclosed in brackets. The command will be executed and its result will be used as the operand.
7. As a mathematical function whose arguments have any of the above forms for operands, such as **sin($x)**. See **[MATH FUNCTIONS](#M22)** below for a discussion of how mathematical functions are handled.

  Where the above substitutions occur (e.g. inside quoted strings), they are performed by the expression's instructions. However, the command parser may already have performed one round of substitution before the expression processor was called. As discussed below, it is usually best to enclose expressions in braces to prevent the command parser from performing substitutions on the contents. 


 For some examples of simple expressions, suppose the variable **a** has the value 3 and the variable **b** has the value 6. Then the command on the left side of each of the lines below will produce the value on the right side of the line: 



```
**expr** 3.1 + $a	*6.1*
**expr** 2 + "$a.$b"	*5.6*
**expr** 4*[llength "6 2"]	*8*
**expr** {{word one} < "word $a"}	*0*
```
 ### Operators

 The valid operators (most of which are also available as commands in the **tcl::mathop** namespace; see the **[mathop](mathop.htm)**(n) manual page for details) are listed below, grouped in decreasing order of precedence: 
 **- + ~ !**
 Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operators may be applied to string operands, and bit-wise NOT may be applied only to integers. 

**\*\***
 Exponentiation. Valid for any numeric operands. 

**\* / %**
 Multiply, divide, remainder. None of these operators may be applied to string operands, and remainder may be applied only to integers. The remainder will always have the same sign as the divisor and an absolute value smaller than the absolute value of the divisor.  When applied to integers, the division and remainder operators can be considered to partition the number line into a sequence of equal-sized adjacent non-overlapping pieces where each piece is the size of the divisor; the division result identifies which piece the divisor lay within, and the remainder result identifies where within that piece the divisor lay. A consequence of this is that the result of “-57 **/** 10” is always -6, and the result of “-57 **%** 10” is always 3. 



**+ -**
 Add and subtract. Valid for any numeric operands. 

**<< >>**
 Left and right shift. Valid for integer operands only. A right shift always propagates the sign bit. 

**< > <= >=**
 Boolean less, greater, less than or equal, and greater than or equal. Each operator produces 1 if the condition is true, 0 otherwise. These operators may be applied to strings as well as numeric operands, in which case string comparison is used. 

**== !=**
 Boolean equal and not equal. Each operator produces a zero/one result. Valid for all operand types. 

**eq ne**
 Boolean string equal and string not equal. Each operator produces a zero/one result. The operand types are interpreted only as strings. 

**in ni**
 List containment and negated list containment. Each operator produces a zero/one result and treats its first argument as a string and its second argument as a Tcl list. The **in** operator indicates whether the first argument is a member of the second argument list; the **ni** operator inverts the sense of the result. 

**&**
 Bit-wise AND. Valid for integer operands only. 

**^**
 Bit-wise exclusive OR. Valid for integer operands only. 

**|**
 Bit-wise OR. Valid for integer operands only. 

**&&**
 Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise. Valid for boolean and numeric (integers or floating-point) operands only. 

**||**
 Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. Valid for boolean and numeric (integers or floating-point) operands only. 


*x***?***y***:***z*

 If-then-else, as in C. If *x* evaluates to non-zero, then the result is the value of *y*. Otherwise the result is the value of *z*. The *x* operand must have a boolean or numeric value. 

  See the C manual for more details on the results produced by each operator. The exponentiation operator promotes types like the multiply and divide operators, and produces a result that is the same as the output of the **pow** function (after any type conversions.) All of the binary operators but exponentiation group left-to-right within the same precedence level; exponentiation groups right-to-left. For example, the command 



```
**expr** {4*2 < 7}
```
  returns 0, while 



```
**expr** {2**3**2}
```
  returns 512. 


 The **&&**, **||**, and **?:** operators have “lazy evaluation”, just as in C, which means that operands are not evaluated if they are not needed to determine the outcome. For example, in the command 



```
**expr** {$v ? [a] : [b]}
```
  only one of “**[a]**” or “**[b]**” will actually be evaluated, depending on the value of **$v**. Note, however, that this is only true if the entire expression is enclosed in braces; otherwise the Tcl parser will evaluate both “**[a]**” and “**[b]**” before invoking the **expr** command. 


### Math functions

 When the expression parser encounters a mathematical function such as **sin($x)**, it replaces it with a call to an ordinary Tcl function in the **tcl::mathfunc** namespace. The processing of an expression such as: 

```
**expr** {sin($x+$y)}
```
  is the same in every way as the processing of: 



```
**expr** {[tcl::mathfunc::sin [**expr** {$x+$y}]]}
```
  which in turn is the same as the processing of: 



```
tcl::mathfunc::sin [**expr** {$x+$y}]
```
  The executor will search for **tcl::mathfunc::sin** using the usual rules for resolving functions in namespaces. Either **::tcl::mathfunc::sin** or **[namespace current]::tcl::mathfunc::sin** will satisfy the request, and others may as well (depending on the current **[namespace path](namespace.htm)** setting). 


 Some mathematical functions have several arguments, separated by commas like in C. Thus: 



```
**expr** {hypot($x,$y)}
```
  ends up as 



```
tcl::mathfunc::hypot $x $y
```
  See the **[mathfunc](mathfunc.htm)**(n) manual page for the math functions that are available by default. 


### Types, overflow, and precision

 All internal computations involving integers are done calling on the LibTomMath multiple precision integer library as required so that all integer calculations are performed exactly. Note that in Tcl releases prior to 8.5, integer calculations were performed with one of the C types *long int* or *[Tcl\_WideInt](https://www.tcl.tk/man/tcl/TclLib/IntObj.htm)*, causing implicit range truncation in those calculations where values overflowed the range of those types. Any code that relied on these implicit truncations will need to explicitly add **[int()](mathfunc.htm)** or **[wide()](mathfunc.htm)** function calls to expressions at the points where such truncation is required to take place.  All internal computations involving floating-point are done with the C type *double*. When converting a string to floating-point, exponent overflow is detected and results in the *double* value of **Inf** or **-Inf** as appropriate. Floating-point overflow and underflow are detected to the degree supported by the hardware, which is generally pretty reliable. 


 Conversion among internal representations for integer, floating-point, and string operands is done automatically as needed. For arithmetic computations, integers are used until some floating-point number is introduced, after which floating-point is used. For example, 



```
**expr** {5 / 4}
```
  returns 1, while 



```
**expr** {5 / 4.0}
**expr** {5 / ( [string length "abcd"] + 0.0 )}
```
  both return 1.25. Floating-point values are always returned with a “**.**” or an “**e**” so that they will not look like integer values. For example, 



```
**expr** {20.0/5.0}
```
  returns **4.0**, not **4**. 


### String operations

 String values may be used as operands of the comparison operators, although the expression evaluator tries to do comparisons as integer or floating-point when it can, i.e., when all arguments to the operator allow numeric interpretations, except in the case of the **eq** and **ne** operators. If one of the operands of a comparison is a string and the other has a numeric value, a canonical string representation of the numeric operand value is generated to compare with the string operand. Canonical string representation for integer values is a decimal string format. Canonical string representation for floating-point values is that produced by the **%g** format specifier of Tcl's **[format](format.htm)** command. For example, the commands 

```
**expr** {"0x03" > "2"}
**expr** {"0y" > "0x12"}
```
  both return 1. The first comparison is done using integer comparison, and the second is done using string comparison. Because of Tcl's tendency to treat values as numbers whenever possible, it is not generally a good idea to use operators like **==** when you really want string comparison and the values of the operands could be arbitrary; it is better in these cases to use the **eq** or **ne** operators, or the **[string](string.htm)** command instead. 


Performance considerations
--------------------------

 Enclose expressions in braces for the best speed and the smallest storage requirements. This allows the Tcl bytecode compiler to generate the best code.  As mentioned above, expressions are substituted twice: once by the Tcl parser and once by the **expr** command. For example, the commands 



```
set a 3
set b {$a + 2}
**expr** $b*4
```
  return 11, not a multiple of 4. This is because the Tcl parser will first substitute **$a + 2** for the variable **b**, then the **expr** command will evaluate the expression **$a + 2\*4**. 


 Most expressions do not require a second round of substitutions. Either they are enclosed in braces or, if not, their variable and command substitutions yield numbers or strings that do not themselves require substitutions. However, because a few unbraced expressions need two rounds of substitutions, the bytecode compiler must emit additional instructions to handle this situation. The most expensive code is required for unbraced expressions that contain command substitutions. These expressions must be implemented by generating new code each time the expression is executed. When the expression is unbraced to allow the substitution of a function or operator, consider using the commands documented in the **[mathfunc](mathfunc.htm)**(n) or **[mathop](mathop.htm)**(n) manual pages directly instead. 


Examples
--------

 Define a procedure that computes an “interesting” mathematical function: 

```
proc tcl::mathfunc::calc {x y} {
    **expr** { ($x**2 - $y**2) / exp($x**2 + $y**2) }
}
```
  Convert polar coordinates into cartesian coordinates: 



```
# convert from ($radius,$angle)
set x [**expr** { $radius * cos($angle) }]
set y [**expr** { $radius * sin($angle) }]
```
  Convert cartesian coordinates into polar coordinates: 



```
# convert from ($x,$y)
set radius [**expr** { hypot($y, $x) }]
set angle  [**expr** { atan2($y, $x) }]
```
  Print a message describing the relationship of two string values to each other: 



```
puts "a and b are [**expr** {$a eq $b ? {equal} : {different}}]"
```
  Set a variable to whether an environment variable is both defined at all and also set to a true boolean value: 



```
set isTrue [**expr** {
    [info exists ::env(SOME_ENV_VAR)] &&
    [string is true -strict $::env(SOME_ENV_VAR)]
}]
```
  Generate a random integer in the range 0..99 inclusive: 



```
set randNum [**expr** { int(100 * rand()) }]
```
 See also
--------

 **[array](array.htm)**, **[for](for.htm)**, **[if](if.htm)**, **[mathfunc](mathfunc.htm)**, **[mathop](mathop.htm)**, **[namespace](namespace.htm)**, **[proc](proc.htm)**, **[string](string.htm)**, **[Tcl](tcl.htm)**, **[while](while.htm)** Copyright
---------

 Copyright (c) 1993 The Regents of the University of California.  
 Copyright (c) 1994-2000 Sun Microsystems Incorporated.  
 Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved.  
 Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-2000 Sun Microsystems, Inc.  
 Copyright © 2005 by Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/expr.htm>

regsub
======

  
[NAME](regsub.htm#M2) regsub — Perform substitutions based on regular expression pattern matching 
[SYNOPSIS](regsub.htm#M3) 
[DESCRIPTION](regsub.htm#M4)  
[**-all**](regsub.htm#M5) 
[**-expanded**](regsub.htm#M6) 
[**-line**](regsub.htm#M7) 
[**-linestop**](regsub.htm#M8) 
[**-lineanchor**](regsub.htm#M9) 
[**-nocase**](regsub.htm#M10) 
[**-start** *index*](regsub.htm#M11) 
[**--**](regsub.htm#M12) 







 
[EXAMPLES](regsub.htm#M13) 
[SEE ALSO](regsub.htm#M14) 
[KEYWORDS](regsub.htm#M15) 





 Name
----

 regsub — Perform substitutions based on regular expression pattern matching Synopsis
--------

 **regsub** ?*switches*? *exp string subSpec* ?*varName*?  
 Description
-----------

 This command matches the regular expression *exp* against *string*, and either copies *string* to the variable whose name is given by *varName* or returns *string* if *varName* is not present. (Regular expression matching is described in the **[re\_syntax](re_syntax.htm)** reference page.) If there is a match, then while copying *string* to *varName* (or to the result of this command if *varName* is not present) the portion of *string* that matched *exp* is replaced with *subSpec*. If *subSpec* contains a “&” or “\0”, then it is replaced in the substitution with the portion of *string* that matched *exp*. If *subSpec* contains a “\*n*”, where *n* is a digit between 1 and 9, then it is replaced in the substitution with the portion of *string* that matched the *n*'th parenthesized subexpression of *exp*. Additional backslashes may be used in *subSpec* to prevent special interpretation of “&”, “\0”, “\*n*” and backslashes. The use of backslashes in *subSpec* tends to interact badly with the Tcl parser's use of backslashes, so it is generally safest to enclose *subSpec* in braces if it includes backslashes.  If the initial arguments to **regsub** start with **-** then they are treated as switches. The following switches are currently supported: 


 **-all**
 All ranges in *string* that match *exp* are found and substitution is performed for each of these ranges. Without this switch only the first matching range is found and substituted. If **-all** is specified, then “&” and “\*n*” sequences are handled for each substitution using the information from the corresponding match. 

**-expanded**
 Enables use of the expanded regular expression syntax where whitespace and comments are ignored. This is the same as specifying the **(?x)** embedded option (see the **[re\_syntax](re_syntax.htm)** manual page). 

**-line**
 Enables newline-sensitive matching. By default, newline is a completely ordinary character with no special meaning. With this flag, “[^” bracket expressions and “.” never match newline, “^” matches an empty string after any newline in addition to its normal function, and “$” matches an empty string before any newline in addition to its normal function. This flag is equivalent to specifying both **-linestop** and **-lineanchor**, or the **(?n)** embedded option (see the **[re\_syntax](re_syntax.htm)** manual page). 

**-linestop**
 Changes the behavior of “[^” bracket expressions and “.” so that they stop at newlines. This is the same as specifying the **(?p)** embedded option (see the **[re\_syntax](re_syntax.htm)** manual page). 

**-lineanchor**
 Changes the behavior of “^” and “$” (the “anchors”) so they match the beginning and end of a line respectively. This is the same as specifying the **(?w)** embedded option (see the **[re\_syntax](re_syntax.htm)** manual page). 

**-nocase**
 Upper-case characters in *string* will be converted to lower-case before matching against *exp*; however, substitutions specified by *subSpec* use the original unconverted form of *string*. 


**-start** *index*

 Specifies a character index offset into the string to start matching the regular expression at. The *index* value is interpreted in the same manner as the *index* argument to **[string index](string.htm)**. When using this switch, “^” will not match the beginning of the line, and \A will still match the start of the string at *index*. *index* will be constrained to the bounds of the input string. 

**--**
 Marks the end of switches. The argument following this one will be treated as *exp* even if it starts with a **-**. 

  If *varName* is supplied, the command returns a count of the number of matching ranges that were found and replaced, otherwise the string after replacement is returned. See the manual entry for **[regexp](regexp.htm)** for details on the interpretation of regular expressions. 


Examples
--------

 Replace (in the string in variable *string*) every instance of **foo** which is a word by itself with **bar**: 

```
**regsub** -all {\mfoo\M} $string bar string
```
  or (using the “basic regular expression” syntax): 



```
**regsub** -all {(?b)\<foo\>} $string bar string
```
  Insert double-quotes around the first instance of the word **interesting**, however it is capitalized. 



```
**regsub** -nocase {\yinteresting\y} $string {"&"} string
```
  Convert all non-ASCII and Tcl-significant characters into \u escape sequences by using **regsub** and **[subst](subst.htm)** in combination: 



```
# This RE is just a character class for almost everything "bad"
set RE {[][{};#\\\$ \r\t\u0080-\uffff]}

# We will substitute with a fragment of Tcl script in brackets
set substitution {[format \\\\u%04x [scan "\\&" %c]]}

# Now we apply the substitution to get a subst-string that
# will perform the computational parts of the conversion. Note
# that newline is handled specially through **[string map](string.htm)** since
# backslash-newline is a special sequence.
set quoted [subst [string map {\n {\\u000a}} \
        [**regsub** -all $RE $string $substitution]]]
```
 See also
--------

 **[regexp](regexp.htm)**, **[re\_syntax](re_syntax.htm)**, **[subst](subst.htm)**, **[string](string.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2000 Scriptics Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/regsub.htm>

array
=====

  
[NAME](array.htm#M2) array — Manipulate array variables 
[SYNOPSIS](array.htm#M3) 
[DESCRIPTION](array.htm#M4)  
[**array anymore** *arrayName searchId*](array.htm#M5) 
[**array donesearch** *arrayName searchId*](array.htm#M6) 
[**array exists** *arrayName*](array.htm#M7) 
[**array get** *arrayName* ?*pattern*?](array.htm#M8) 
[**array names** *arrayName* ?*mode*? ?*pattern*?](array.htm#M9) 
[**array nextelement** *arrayName searchId*](array.htm#M10) 
[**array set** *arrayName list*](array.htm#M11) 
[**array size** *arrayName*](array.htm#M12) 
[**array startsearch** *arrayName*](array.htm#M13) 
[**array statistics** *arrayName*](array.htm#M14) 
[**array unset** *arrayName* ?*pattern*?](array.htm#M15) 










 
[EXAMPLES](array.htm#M16) 
[SEE ALSO](array.htm#M17) 
[KEYWORDS](array.htm#M18) 





 Name
----

 array — Manipulate array variables Synopsis
--------

 **array** *option arrayName* ?*arg arg ...*?  
 Description
-----------

 This command performs one of several operations on the variable given by *arrayName*. Unless otherwise specified for individual commands below, *arrayName* must be the name of an existing array variable. The *option* argument determines what action is carried out by the command. The legal *options* (which may be abbreviated) are: 
 
**array anymore** *arrayName searchId*

 Returns 1 if there are any more elements left to be processed in an array search, 0 if all elements have already been returned. *SearchId* indicates which search on *arrayName* to check, and must have been the return value from a previous invocation of **array startsearch**. This option is particularly useful if an array has an element with an empty name, since the return value from **array nextelement** will not indicate whether the search has been completed. 


**array donesearch** *arrayName searchId*

 This command terminates an array search and destroys all the state associated with that search. *SearchId* indicates which search on *arrayName* to destroy, and must have been the return value from a previous invocation of **array startsearch**. Returns an empty string. 


**array exists** *arrayName*

 Returns 1 if *arrayName* is an array variable, 0 if there is no variable by that name or if it is a scalar variable. 


**array get** *arrayName* ?*pattern*?
 Returns a list containing pairs of elements. The first element in each pair is the name of an element in *arrayName* and the second element of each pair is the value of the array element. The order of the pairs is undefined. If *pattern* is not specified, then all of the elements of the array are included in the result. If *pattern* is specified, then only those elements whose names match *pattern* (using the matching rules of **[string match](string.htm)**) are included. If *arrayName* is not the name of an array variable, or if the array contains no elements, then an empty list is returned. If traces on the array modify the list of elements, the elements returned are those that exist both before and after the call to **array get**. 


**array names** *arrayName* ?*mode*? ?*pattern*?
 Returns a list containing the names of all of the elements in the array that match *pattern*. *Mode* may be one of **-exact**, **-glob**, or **-regexp**. If specified, *mode* designates which matching rules to use to match *pattern* against the names of the elements in the array. If not specified, *mode* defaults to **-glob**. See the documentation for **[string match](string.htm)** for information on glob style matching, and the documentation for **[regexp](regexp.htm)** for information on regexp matching. If *pattern* is omitted then the command returns all of the element names in the array. If there are no (matching) elements in the array, or if *arrayName* is not the name of an array variable, then an empty string is returned. 


**array nextelement** *arrayName searchId*

 Returns the name of the next element in *arrayName*, or an empty string if all elements of *arrayName* have already been returned in this search. The *searchId* argument identifies the search, and must have been the return value of an **array startsearch** command. Warning: if elements are added to or deleted from the array, then all searches are automatically terminated just as if **array donesearch** had been invoked; this will cause **array nextelement** operations to fail for those searches. 


**array set** *arrayName list*

 Sets the values of one or more elements in *arrayName*. *list* must have a form like that returned by **array get**, consisting of an even number of elements. Each odd-numbered element in *list* is treated as an element name within *arrayName*, and the following element in *list* is used as a new value for that array element. If the variable *arrayName* does not already exist and *list* is empty, *arrayName* is created with an empty array value. 


**array size** *arrayName*

 Returns a decimal string giving the number of elements in the array. If *arrayName* is not the name of an array then 0 is returned. 


**array startsearch** *arrayName*

 This command initializes an element-by-element search through the array given by *arrayName*, such that invocations of the **array nextelement** command will return the names of the individual elements in the array. When the search has been completed, the **array donesearch** command should be invoked. The return value is a search identifier that must be used in **array nextelement** and **array donesearch** commands; it allows multiple searches to be underway simultaneously for the same array. It is currently more efficient and easier to use either the **array get** or **array names**, together with **[foreach](foreach.htm)**, to iterate over all but very large arrays. See the examples below for how to do this. 


**array statistics** *arrayName*

 Returns statistics about the distribution of data within the hashtable that represents the array. This information includes the number of entries in the table, the number of buckets, and the utilization of the buckets. 


**array unset** *arrayName* ?*pattern*?
 Unsets all of the elements in the array that match *pattern* (using the matching rules of **[string match](string.htm)**). If *arrayName* is not the name of an array variable or there are no matching elements in the array, no error will be raised. If *pattern* is omitted and *arrayName* is an array variable, then the command unsets the entire array. The command always returns an empty string. 

 Examples
--------

 
```
**array set** colorcount {
    red   1
    green 5
    blue  4
    white 9
}

foreach {color count} [**array get** colorcount] {
    puts "Color: $color Count: $count"
}
  **→** Color: blue Count: 4
    Color: white Count: 9
    Color: green Count: 5
    Color: red Count: 1

foreach color [**array names** colorcount] {
    puts "Color: $color Count: $colorcount($color)"
}
  **→** Color: blue Count: 4
    Color: white Count: 9
    Color: green Count: 5
    Color: red Count: 1

foreach color [lsort [**array names** colorcount]] {
    puts "Color: $color Count: $colorcount($color)"
}
  **→** Color: blue Count: 4
    Color: green Count: 5
    Color: red Count: 1
    Color: white Count: 9

**array statistics** colorcount
  **→** 4 entries in table, 4 buckets
    number of buckets with 0 entries: 1
    number of buckets with 1 entries: 2
    number of buckets with 2 entries: 1
    number of buckets with 3 entries: 0
    number of buckets with 4 entries: 0
    number of buckets with 5 entries: 0
    number of buckets with 6 entries: 0
    number of buckets with 7 entries: 0
    number of buckets with 8 entries: 0
    number of buckets with 9 entries: 0
    number of buckets with 10 or more entries: 0
    average search distance for entry: 1.2
```
 See also
--------

 **[list](list.htm)**, **[string](string.htm)**, **[variable](variable.htm)**, **[trace](trace.htm)**, **[foreach](foreach.htm)** Copyright © 1993-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/array.htm>

fcopy
=====

 Name
----

 fcopy — Copy data from one channel to another Synopsis
--------

 **fcopy** *inchan* *outchan* ?**-size** *size*? ?**-command** *callback*?  
 Description
-----------

 The **fcopy** command copies data from one I/O channel, *inchan* to another I/O channel, *outchan*. The **fcopy** command leverages the buffering in the Tcl I/O system to avoid extra copies and to avoid buffering too much data in main memory when copying large files to slow destinations like network sockets.  The **fcopy** command transfers data from *inchan* until end of file or *size* bytes or characters have been transferred; *size* is in bytes if the two channels are using the same encoding, and is in characters otherwise. If no **-size** argument is given, then the copy goes until end of file. All the data read from *inchan* is copied to *outchan*. Without the **-command** option, **fcopy** blocks until the copy is complete and returns the number of bytes or characters (using the same rules as for the **-size** option) written to *outchan*. 


 The **-command** argument makes **fcopy** work in the background. In this case it returns immediately and the *callback* is invoked later when the copy completes. The *callback* is called with one or two additional arguments that indicates how many bytes were written to *outchan*. If an error occurred during the background copy, the second argument is the error string associated with the error. With a background copy, it is not necessary to put *inchan* or *outchan* into non-blocking mode; the **fcopy** command takes care of that automatically. However, it is necessary to enter the event loop by using the **[vwait](vwait.htm)** command or by using Tk. 


 You are not allowed to do other input operations with *inchan*, or output operations with *outchan*, during a background **fcopy**. The converse is entirely legitimate, as exhibited by the bidirectional fcopy example below. 


 If either *inchan* or *outchan* get closed while the copy is in progress, the current copy is stopped and the command callback is *not* made. If *inchan* is closed, then all data already queued for *outchan* is written out. 


 Note that *inchan* can become readable during a background copy. You should turn off any **[fileevent](fileevent.htm)** handlers during a background copy so those handlers do not interfere with the copy. Any wrong-sided I/O attempted (by a **[fileevent](fileevent.htm)** handler or otherwise) will get a “channel busy” error. 


 **Fcopy** translates end-of-line sequences in *inchan* and *outchan* according to the **-translation** option for these channels. See the manual entry for **[fconfigure](fconfigure.htm)** for details on the **-translation** option. The translations mean that the number of bytes read from *inchan* can be different than the number of bytes written to *outchan*. Only the number of bytes written to *outchan* is reported, either as the return value of a synchronous **fcopy** or as the argument to the callback for an asynchronous **fcopy**. 


 **Fcopy** obeys the encodings and character translations configured for the channels. This means that the incoming characters are converted internally first UTF-8 and then into the encoding of the channel **fcopy** writes to. See the manual entry for **[fconfigure](fconfigure.htm)** for details on the **-encoding** and **-translation** options. No conversion is done if both channels are set to encoding “binary” and have matching translations. If only the output channel is set to encoding “binary” the system will write the internal UTF-8 representation of the incoming characters. If only the input channel is set to encoding “binary” the system will assume that the incoming bytes are valid UTF-8 characters and convert them according to the output encoding. The behaviour of the system for bytes which are not valid UTF-8 characters is undefined in this case. 


Examples
--------

 The first example transfers the contents of one channel exactly to another. Note that when copying one file to another, it is better to use **[file copy](file.htm)** which also copies file metadata (e.g. the file access permissions) where possible. 

```
fconfigure $in -translation binary
fconfigure $out -translation binary
**fcopy** $in $out
```
  This second example shows how the callback gets passed the number of bytes transferred. It also uses vwait to put the application into the event loop. Of course, this simplified example could be done without the command callback. 



```
proc Cleanup {in out bytes {error {}}} {
    global total
    set total $bytes
    close $in
    close $out
    if {[string length $error] != 0} {
        # error occurred during the copy
    }
}
set in [open $file1]
set out [socket $server $port]
**fcopy** $in $out -command [list Cleanup $in $out]
vwait total
```
  The third example copies in chunks and tests for end of file in the command callback. 



```
proc CopyMore {in out chunk bytes {error {}}} {
    global total done
    incr total $bytes
    if {([string length $error] != 0) || [eof $in]} {
        set done $total
        close $in
        close $out
    } else {
        **fcopy** $in $out -size $chunk \
                -command [list CopyMore $in $out $chunk]
    }
}
set in [open $file1]
set out [socket $server $port]
set chunk 1024
set total 0
**fcopy** $in $out -size $chunk \
        -command [list CopyMore $in $out $chunk]
vwait done
```
  The fourth example starts an asynchronous, bidirectional fcopy between two sockets. Those could also be pipes from two [open "|hal 9000" r+] (though their conversation would remain secret to the script, since all four fileevent slots are busy). 



```
set flows 2
proc Done {dir args} {
     global flows done
     puts "$dir is over."
     incr flows -1
     if {$flows<=0} {set done 1}
}
**fcopy** $sok1 $sok2 -command [list Done UP]
**fcopy** $sok2 $sok1 -command [list Done DOWN]
vwait done
```
 See also
--------

 **[eof](eof.htm)**, **[fblocked](fblocked.htm)**, **[fconfigure](fconfigure.htm)**, **[file](file.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/fcopy.htm>

lsort
=====

  
[NAME](lsort.htm#M2) lsort — Sort the elements of a list 
[SYNOPSIS](lsort.htm#M3) 
[DESCRIPTION](lsort.htm#M4)  
[**-ascii**](lsort.htm#M5) 
[**-dictionary**](lsort.htm#M6) 
[**-integer**](lsort.htm#M7) 
[**-real**](lsort.htm#M8) 
[**-command** *command*](lsort.htm#M9) 
[**-increasing**](lsort.htm#M10) 
[**-decreasing**](lsort.htm#M11) 
[**-indices**](lsort.htm#M12) 
[**-index** *indexList*](lsort.htm#M13) 
[**-stride** *strideLength*](lsort.htm#M14) 
[**-nocase**](lsort.htm#M15) 
[**-unique**](lsort.htm#M16) 











 
[NOTES](lsort.htm#M17) 
[EXAMPLES](lsort.htm#M18) 
[SEE ALSO](lsort.htm#M19) 
[KEYWORDS](lsort.htm#M20) 






 Name
----

 lsort — Sort the elements of a list Synopsis
--------

 **lsort** ?*options*? *list*  
 Description
-----------

 This command sorts the elements of *list*, returning a new list in sorted order. The implementation of the **lsort** command uses the merge-sort algorithm which is a stable sort that has O(n log n) performance characteristics.  By default ASCII sorting is used with the result returned in increasing order. However, any of the following options may be specified before *list* to control the sorting process (unique abbreviations are accepted): 


 **-ascii**
 Use string comparison with Unicode code-point collation order (the name is for backward-compatibility reasons.) This is the default. 

**-dictionary**
 Use dictionary-style comparison. This is the same as **-ascii** except (a) case is ignored except as a tie-breaker and (b) if two strings contain embedded numbers, the numbers compare as integers, not characters. For example, in **-dictionary** mode, **bigBoy** sorts between **bigbang** and **bigboy**, and **x10y** sorts between **x9y** and **x11y**. 

**-integer**
 Convert list elements to integers and use integer comparison. 

**-real**
 Convert list elements to floating-point values and use floating comparison. 


**-command** *command*

 Use *command* as a comparison command. To compare two elements, evaluate a Tcl script consisting of *command* with the two elements appended as additional arguments. The script should return an integer less than, equal to, or greater than zero if the first element is to be considered less than, equal to, or greater than the second, respectively. 

**-increasing**
 Sort the list in increasing order (“smallest”items first). This is the default. 

**-decreasing**
 Sort the list in decreasing order (“largest”items first). 

**-indices**
 Return a list of indices into *list* in sorted order instead of the values themselves. 


**-index** *indexList*

 If this option is specified, each of the elements of *list* must itself be a proper Tcl sublist (unless **-stride** is used). Instead of sorting based on whole sublists, **lsort** will extract the *indexList*'th element from each sublist (as if the overall element and the *indexList* were passed to **[lindex](lindex.htm)**) and sort based on the given element. For example, 

```
**lsort** -integer -index 1 \
      {{First 24} {Second 18} {Third 30}}
```
  returns **{Second 18} {First 24} {Third 30}**, 



```
**lsort** -index end-1 \
        {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}
```
  returns **{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}**, and 



```
**lsort** -index {0 1} {
    {{b i g} 12345}
    {{d e m o} 34512}
    {{c o d e} 54321}
}
```
 returns **{{d e m o} 34512} {{b i g} 12345} {{c o d e} 54321}** (because **e** sorts before **i** which sorts before **o**.) This option is much more efficient than using **-command** to achieve the same effect. 




**-stride** *strideLength*

 If this option is specified, the list is treated as consisting of groups of *strideLength* elements and the groups are sorted by either their first element or, if the **-index** option is used, by the element within each group given by the first index passed to **-index** (which is then ignored by **-index**). Elements always remain in the same position within their group.  The list length must be an integer multiple of *strideLength*, which in turn must be at least 2. 


 For example, 



```
**lsort** -stride 2 {carrot 10 apple 50 banana 25}
```
  returns “apple 50 banana 25 carrot 10”, and 



```
**lsort** -stride 2 -index 1 -integer {carrot 10 apple 50 banana 25}
```
 returns “carrot 10 banana 25 apple 50”. 



**-nocase**
 Causes comparisons to be handled in a case-insensitive manner. Has no effect if combined with the **-dictionary**, **-integer**, or **-real** options. 

**-unique**
 If this option is specified, then only the last set of duplicate elements found in the list will be retained. Note that duplicates are determined relative to the comparison used in the sort. Thus if **-index 0** is used, **{1 a}** and **{1 b}** would be considered duplicates and only the second element, **{1 b}**, would be retained. 

 Notes
-----

 The options to **lsort** only control what sort of comparison is used, and do not necessarily constrain what the values themselves actually are. This distinction is only noticeable when the list to be sorted has fewer than two elements.  The **lsort** command is reentrant, meaning it is safe to use as part of the implementation of a command used in the **-command** option. 


Examples
--------

 Sorting a list using ASCII sorting: 

```
*%* **lsort** {a10 B2 b1 a1 a2}
B2 a1 a10 a2 b1
```
  Sorting a list using Dictionary sorting: 



```
*%* **lsort** -dictionary {a10 B2 b1 a1 a2}
a1 a2 a10 b1 B2
```
  Sorting lists of integers: 



```
*%* **lsort** -integer {5 3 1 2 11 4}
1 2 3 4 5 11
*%* **lsort** -integer {1 2 0x5 7 0 4 -1}
-1 0 1 2 4 0x5 7
```
  Sorting lists of floating-point numbers: 



```
*%* **lsort** -real {5 3 1 2 11 4}
1 2 3 4 5 11
*%* **lsort** -real {.5 0.07e1 0.4 6e-1}
0.4 .5 6e-1 0.07e1
```
  Sorting using indices: 



```
*%* # Note the space character before the c
*%* **lsort** {{a 5} { c 3} {b 4} {e 1} {d 2}}
{ c 3} {a 5} {b 4} {d 2} {e 1}
*%* **lsort** -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}}
{a 5} {b 4} { c 3} {d 2} {e 1}
*%* **lsort** -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}}
{e 1} {d 2} { c 3} {b 4} {a 5}
```
  Sorting a dictionary: 



```
*%* set d [dict create c d a b h i f g c e]
c e a b h i f g
*%* **lsort** -stride 2 $d
a b c e f g h i
```
  Sorting using striding and multiple indices: 



```
*%* # Note the first index value is relative to the group
*%* **lsort** -stride 3 -index {0 1} \
     {{Bob Smith} 25 Audi {Jane Doe} 40 Ford}
{{Jane Doe} 40 Ford {Bob Smith} 25 Audi}
```
  Stripping duplicate values using sorting: 



```
*%* **lsort** -unique {a b c a b c a b c}
a b c
```
  More complex sorting using a comparison function: 



```
*%* proc compare {a b} {
    set a0 [lindex $a 0]
    set b0 [lindex $b 0]
    if {$a0 < $b0} {
        return -1
    } elseif {$a0 > $b0} {
        return 1
    }
    return [string compare [lindex $a 1] [lindex $b 1]]
}
*%* **lsort** -command compare \
        {{3 apple} {0x2 carrot} {1 dingo} {2 banana}}
{1 dingo} {2 banana} {0x2 carrot} {3 apple}
```
 See also
--------

 **[list](list.htm)**, **[lappend](lappend.htm)**, **[lindex](lindex.htm)**, **[linsert](linsert.htm)**, **[llength](llength.htm)**, **[lsearch](lsearch.htm)**, **[lset](lset.htm)**, **[lrange](lrange.htm)**, **[lreplace](lreplace.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 1999 Scriptics Corporation  
 Copyright © 2001 Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/lsort.htm>

re\_syntax
==========

  
[NAME](re_syntax.htm#M2) re\_syntax — Syntax of Tcl regular expressions 
[DESCRIPTION](re_syntax.htm#M3) 
[DIFFERENT FLAVORS OF REs](re_syntax.htm#M4) 
[REGULAR EXPRESSION SYNTAX](re_syntax.htm#M5) 
[QUANTIFIERS](re_syntax.htm#M6)  
[**\***](re_syntax.htm#M7) 
[**+**](re_syntax.htm#M8) 
[**?**](re_syntax.htm#M9) 
[**{***m***}**](re_syntax.htm#M10) 
[**{***m***,}**](re_syntax.htm#M11) 
[**{***m***,***n***}**](re_syntax.htm#M12) 
[**\*? +? ?? {***m***}? {***m***,}? {***m***,***n***}?**](re_syntax.htm#M13) 






 
[ATOMS](re_syntax.htm#M14)  
[**(***re***)**](re_syntax.htm#M15) 
[**(?:***re***)**](re_syntax.htm#M16) 
[**()**](re_syntax.htm#M17) 
[**(?:)**](re_syntax.htm#M18) 
[**[***chars***]**](re_syntax.htm#M19) 
[**.**](re_syntax.htm#M20) 
[**\***k*](re_syntax.htm#M21) 
[**\***c*](re_syntax.htm#M22) 
[**{**](re_syntax.htm#M23) 
[*x*](re_syntax.htm#M24) 









 
[CONSTRAINTS](re_syntax.htm#M25)  
[**^**](re_syntax.htm#M26) 
[**$**](re_syntax.htm#M27) 
[**(?=***re***)**](re_syntax.htm#M28) 
[**(?!***re***)**](re_syntax.htm#M29) 



 
[BRACKET EXPRESSIONS](re_syntax.htm#M30) 
[CHARACTER CLASSES](re_syntax.htm#M31)  
[**alpha**](re_syntax.htm#M32) 
[**upper**](re_syntax.htm#M33) 
[**lower**](re_syntax.htm#M34) 
[**digit**](re_syntax.htm#M35) 
[**xdigit**](re_syntax.htm#M36) 
[**alnum**](re_syntax.htm#M37) 
[**print**](re_syntax.htm#M38) 
[**blank**](re_syntax.htm#M39) 
[**space**](re_syntax.htm#M40) 
[**punct**](re_syntax.htm#M41) 
[**graph**](re_syntax.htm#M42) 
[**cntrl**](re_syntax.htm#M43) 











 
[BRACKETED CONSTRAINTS](re_syntax.htm#M44) 
[COLLATING ELEMENTS](re_syntax.htm#M45) 
[EQUIVALENCE CLASSES](re_syntax.htm#M46) 
[ESCAPES](re_syntax.htm#M47) 
[CHARACTER-ENTRY ESCAPES](re_syntax.htm#M48)  
[**\a**](re_syntax.htm#M49) 
[**\b**](re_syntax.htm#M50) 
[**\B**](re_syntax.htm#M51) 
[**\c***X*](re_syntax.htm#M52) 
[**\e**](re_syntax.htm#M53) 
[**\f**](re_syntax.htm#M54) 
[**\n**](re_syntax.htm#M55) 
[**\r**](re_syntax.htm#M56) 
[**\t**](re_syntax.htm#M57) 
[**\u***wxyz*](re_syntax.htm#M58) 
[**\U***stuvwxyz*](re_syntax.htm#M59) 
[**\v**](re_syntax.htm#M60) 
[**\x***hh*](re_syntax.htm#M61) 
[**\0**](re_syntax.htm#M62) 
[**\***xyz*](re_syntax.htm#M63) 
[**\***xy*](re_syntax.htm#M64) 















 
[CLASS-SHORTHAND ESCAPES](re_syntax.htm#M65)  
[**\d**](re_syntax.htm#M66) 
[**\s**](re_syntax.htm#M67) 
[**\w**](re_syntax.htm#M68) 
[**\D**](re_syntax.htm#M69) 
[**\S**](re_syntax.htm#M70) 
[**\W**](re_syntax.htm#M71) 





 
[CONSTRAINT ESCAPES](re_syntax.htm#M72)  
[**\A**](re_syntax.htm#M73) 
[**\m**](re_syntax.htm#M74) 
[**\M**](re_syntax.htm#M75) 
[**\y**](re_syntax.htm#M76) 
[**\Y**](re_syntax.htm#M77) 
[**\Z**](re_syntax.htm#M78) 
[**\***m*](re_syntax.htm#M79) 
[**\***mnn*](re_syntax.htm#M80) 







 
[BACK REFERENCES](re_syntax.htm#M81) 
[METASYNTAX](re_syntax.htm#M82)  
[**b**](re_syntax.htm#M83) 
[**c**](re_syntax.htm#M84) 
[**e**](re_syntax.htm#M85) 
[**i**](re_syntax.htm#M86) 
[**m**](re_syntax.htm#M87) 
[**n**](re_syntax.htm#M88) 
[**p**](re_syntax.htm#M89) 
[**q**](re_syntax.htm#M90) 
[**s**](re_syntax.htm#M91) 
[**t**](re_syntax.htm#M92) 
[**w**](re_syntax.htm#M93) 
[**x**](re_syntax.htm#M94) 











 
[MATCHING](re_syntax.htm#M95) 
[LIMITS AND COMPATIBILITY](re_syntax.htm#M96) 
[BASIC REGULAR EXPRESSIONS](re_syntax.htm#M97) 
[SEE ALSO](re_syntax.htm#M98) 
[KEYWORDS](re_syntax.htm#M99) 






















 Name
----

 re\_syntax — Syntax of Tcl regular expressions Description
-----------

 A *regular expression* describes strings of characters. It's a pattern that matches certain strings and does not match others. Different flavors of res
------------------------

 Regular expressions (“RE”s), as defined by POSIX, come in two flavors: *extended* REs (“ERE”s) and *basic* REs (“BRE”s). EREs are roughly those of the traditional *egrep*, while BREs are roughly those of the traditional *ed*. This implementation adds a third flavor, *advanced* REs (“ARE”s), basically EREs with some significant extensions.  This manual page primarily describes AREs. BREs mostly exist for backward compatibility in some old programs; they will be discussed at the end. POSIX EREs are almost an exact subset of AREs. Features of AREs that are not present in EREs will be indicated. 


Regular expression syntax
-------------------------

 Tcl regular expressions are implemented using the package written by Henry Spencer, based on the 1003.2 spec and some (not quite all) of the Perl5 extensions (thanks, Henry!). Much of the description of regular expressions below is copied verbatim from his manual entry.  An ARE is one or more *branches*, separated by “**|**”, matching anything that matches any of the branches. 


 A branch is zero or more *constraints* or *quantified atoms*, concatenated. It matches a match for the first, followed by a match for the second, etc; an empty branch matches the empty string. 


### Quantifiers

 A quantified atom is an *atom* possibly followed by a single *quantifier*. Without a quantifier, it matches a single match for the atom. The quantifiers, and what a so-quantified atom matches, are: 
 **\***
 a sequence of 0 or more matches of the atom 

**+**
 a sequence of 1 or more matches of the atom 

**?**
 a sequence of 0 or 1 matches of the atom 


**{***m***}**

 a sequence of exactly *m* matches of the atom 


**{***m***,}**

 a sequence of *m* or more matches of the atom 


**{***m***,***n***}**

 a sequence of *m* through *n* (inclusive) matches of the atom; *m* may not exceed *n*


**\*? +? ?? {***m***}? {***m***,}? {***m***,***n***}?**

 *non-greedy* quantifiers, which match the same possibilities, but prefer the smallest number rather than the largest number of matches (see **[MATCHING](#M95)**) 

  The forms using **{** and **}** are known as *bound*s. The numbers *m* and *n* are unsigned decimal integers with permissible values from 0 to 255 inclusive. 


### Atoms

 An atom is one of: 
 
**(***re***)**

 matches a match for *re* (*re* is any regular expression) with the match noted for possible reporting 


**(?:***re***)**

 as previous, but does no reporting (a “non-capturing” set of parentheses) 

**()**
 matches an empty string, noted for possible reporting 

**(?:)**
 matches an empty string, without reporting 


**[***chars***]**

 a *bracket expression*, matching any one of the *chars* (see **[BRACKET EXPRESSIONS](#M30)** for more detail) 

**.**
 matches any single character 


**\***k*

 matches the non-alphanumeric character *k* taken as an ordinary character, e.g. **\\** matches a backslash character 


**\***c*

 where *c* is alphanumeric (possibly followed by other characters), an *escape* (AREs only), see **[ESCAPES](#M47)** below 

**{**
 when followed by a character other than a digit, matches the left-brace character “**{**”; when followed by a digit, it is the beginning of a *bound* (see above) 

*x*
 where *x* is a single character with no other significance, matches that character. 

 ### Constraints

 A *constraint* matches an empty string when specific conditions are met. A constraint may not be followed by a quantifier. The simple constraints are as follows; some more constraints are described later, under **[ESCAPES](#M47)**. 
 **^**
 matches at the beginning of a line 

**$**
 matches at the end of a line 


**(?=***re***)**

 *positive lookahead* (AREs only), matches at any point where a substring matching *re* begins 


**(?!***re***)**

 *negative lookahead* (AREs only), matches at any point where no substring matching *re* begins 

  The lookahead constraints may not contain back references (see later), and all parentheses within them are considered non-capturing. 


 An RE may not end with “**\**”. 


Bracket expressions
-------------------

 A *bracket expression* is a list of characters enclosed in “**[ ]**”. It normally matches any single character from the list (but see below). If the list begins with “**^**”, it matches any single character (but see below) *not* from the rest of the list.  If two characters in the list are separated by “**-**”, this is shorthand for the full *range* of characters between those two (inclusive) in the collating sequence, e.g. “**[0-9]**” in Unicode matches any conventional decimal digit. Two ranges may not share an endpoint, so e.g. “**a-c-e**” is illegal. Ranges in Tcl always use the Unicode collating sequence, but other programs may use other collating sequences and this can be a source of incompatibility between programs. 


 To include a literal **]** or **-** in the list, the simplest method is to enclose it in **[.** and **.]** to make it a collating element (see below). Alternatively, make it the first character (following a possible “**^**”), or (AREs only) precede it with “**\**”. Alternatively, for “**-**”, make it the last character, or the second endpoint of a range. To use a literal **-** as the first endpoint of a range, make it a collating element or (AREs only) precede it with “**\**”. With the exception of these, some combinations using **[** (see next paragraphs), and escapes, all other special characters lose their special significance within a bracket expression. 


### Character classes

 Within a bracket expression, the name of a *character class* enclosed in **[:** and **:]** stands for the list of all characters (not all collating elements!) belonging to that class. Standard character classes are: 
 **alpha**
 A letter. 

**upper**
 An upper-case letter. 

**lower**
 A lower-case letter. 

**digit**
 A decimal digit. 

**xdigit**
 A hexadecimal digit. 

**alnum**
 An alphanumeric (letter or digit). 

**print**
 A "printable" (same as graph, except also including space). 

**blank**
 A space or tab character. 

**space**
 A character producing white space in displayed text. 

**punct**
 A punctuation character. 

**graph**
 A character with a visible representation (includes both **alnum** and **punct**). 

**cntrl**
 A control character. 

  A locale may provide others. A character class may not be used as an endpoint of a range. 


  (*Note:* the current Tcl implementation has only one locale, the Unicode locale, which supports exactly the above classes.) 


 ### Bracketed constraints

 There are two special cases of bracket expressions: the bracket expressions “**[[:<:]]**” and “**[[:>:]]**” are constraints, matching empty strings at the beginning and end of a word respectively. A word is defined as a sequence of word characters that is neither preceded nor followed by word characters. A word character is an *alnum* character or an underscore (“**\_**”). These special bracket expressions are deprecated; users of AREs should use constraint escapes instead (see below). ### Collating elements

 Within a bracket expression, a collating element (a character, a multi-character sequence that collates as if it were a single character, or a collating-sequence name for either) enclosed in **[.** and **.]** stands for the sequence of characters of that collating element. The sequence is a single element of the bracket expression's list. A bracket expression in a locale that has multi-character collating elements can thus match more than one character. So (insidiously), a bracket expression that starts with **^** can match multi-character collating elements even if none of them appear in the bracket expression!   (*Note:* Tcl has no multi-character collating elements. This information is only for illustration.) 


  For example, assume the collating sequence includes a **ch** multi-character collating element. Then the RE “**[[.ch.]]\*c**” (zero or more “**ch**s” followed by “**c**”) matches the first five characters of “**chchcc**”. Also, the RE “**[^c]b**” matches all of “**chb**” (because “**[^c]**” matches the multi-character “**ch**”). 


### Equivalence classes

 Within a bracket expression, a collating element enclosed in **[=** and **=]** is an equivalence class, standing for the sequences of characters of all collating elements equivalent to that one, including itself. (If there are no other equivalent collating elements, the treatment is as if the enclosing delimiters were “**[.**” and “**.]**”.) For example, if **o** and **ô** are the members of an equivalence class, then “**[[=o=]]**”, “**[[=ô=]]**”, and “**[oô]**” are all synonymous. An equivalence class may not be an endpoint of a range.   (*Note:* Tcl implements only the Unicode locale. It does not define any equivalence classes. The examples above are just illustrations.) 


 Escapes
-------

 Escapes (AREs only), which begin with a **\** followed by an alphanumeric character, come in several varieties: character entry, class shorthands, constraint escapes, and back references. A **\** followed by an alphanumeric character but not constituting a valid escape is illegal in AREs. In EREs, there are no escapes: outside a bracket expression, a **\** followed by an alphanumeric character merely stands for that character as an ordinary character, and inside a bracket expression, **\** is an ordinary character. (The latter is the one actual incompatibility between EREs and AREs.) ### Character-entry escapes

 Character-entry escapes (AREs only) exist to make it easier to specify non-printing and otherwise inconvenient characters in REs: 
 **\a**
 alert (bell) character, as in C 

**\b**
 backspace, as in C 

**\B**
 synonym for **\** to help reduce backslash doubling in some applications where there are multiple levels of backslash processing 


**\c***X*

 (where *X* is any character) the character whose low-order 5 bits are the same as those of *X*, and whose other bits are all zero 

**\e**
 the character whose collating-sequence name is “**ESC**”, or failing that, the character with octal value 033 

**\f**
 formfeed, as in C 

**\n**
 newline, as in C 

**\r**
 carriage return, as in C 

**\t**
 horizontal tab, as in C 


**\u***wxyz*

 (where *wxyz* is one up to four hexadecimal digits) the Unicode character **U+***wxyz* in the local byte ordering 


**\U***stuvwxyz*

 (where *stuvwxyz* is one up to eight hexadecimal digits) reserved for a Unicode extension up to 21 bits. The digits are parsed until the first non-hexadecimal character is encountered, the maximun of eight hexadecimal digits are reached, or an overflow would occur in the maximum value of **U+***10ffff*. 

**\v**
 vertical tab, as in C are all available. 


**\x***hh*

 (where *hh* is one or two hexadecimal digits) the character whose hexadecimal value is **0x***hh*. 

**\0**
 the character whose value is **0**


**\***xyz*

 (where *xyz* is exactly three octal digits, and is not a *back reference* (see below)) the character whose octal value is **0***xyz*. The first digit must be in the range 0-3, otherwise the two-digit form is assumed. 


**\***xy*

 (where *xy* is exactly two octal digits, and is not a *back reference* (see below)) the character whose octal value is **0***xy*

  Hexadecimal digits are “**0**–**9**”, “**a**–**f**”, and “**A**–**F**”. Octal digits are “**0**–**7**”. 


 The character-entry escapes are always taken as ordinary characters. For example, **\135** is **]** in Unicode, but **\135** does not terminate a bracket expression. Beware, however, that some applications (e.g., C compilers and the Tcl interpreter if the regular expression is not quoted with braces) interpret such sequences themselves before the regular-expression package gets to see them, which may require doubling (quadrupling, etc.) the “**\**”. 


### Class-shorthand escapes

 Class-shorthand escapes (AREs only) provide shorthands for certain commonly-used character classes: 
 **\d**
 **[[:digit:]]**

**\s**
 **[[:space:]]**

**\w**
 **[[:alnum:]\_]** (note underscore) 

**\D**
 **[^[:digit:]]**

**\S**
 **[^[:space:]]**

**\W**
 **[^[:alnum:]\_]** (note underscore) 

  Within bracket expressions, “**\d**”, “**\s**”, and “**\w**” lose their outer brackets, and “**\D**”, “**\S**”, and “**\W**” are illegal. (So, for example, “**[a-c\d]**” is equivalent to “**[a-c[:digit:]]**”. Also, “**[a-c\D]**”, which is equivalent to “**[a-c^[:digit:]]**”, is illegal.) 


### Constraint escapes

 A constraint escape (AREs only) is a constraint, matching the empty string if specific conditions are met, written as an escape: 
 **\A**
 matches only at the beginning of the string (see **[MATCHING](#M95)**, below, for how this differs from “**^**”) 

**\m**
 matches only at the beginning of a word 

**\M**
 matches only at the end of a word 

**\y**
 matches only at the beginning or end of a word 

**\Y**
 matches only at a point that is not the beginning or end of a word 

**\Z**
 matches only at the end of the string (see **[MATCHING](#M95)**, below, for how this differs from “**$**”) 


**\***m*

 (where *m* is a nonzero digit) a *back reference*, see below 


**\***mnn*

 (where *m* is a nonzero digit, and *nn* is some more digits, and the decimal value *mnn* is not greater than the number of closing capturing parentheses seen so far) a *back reference*, see below 

  A word is defined as in the specification of “**[[:<:]]**” and “**[[:>:]]**” above. Constraint escapes are illegal within bracket expressions. 


### Back references

 A back reference (AREs only) matches the same string matched by the parenthesized subexpression specified by the number, so that (e.g.) “**([bc])\1**” matches “**bb**” or “**cc**” but not “**bc**”. The subexpression must entirely precede the back reference in the RE. Subexpressions are numbered in the order of their leading parentheses. Non-capturing parentheses do not define subexpressions.  There is an inherent historical ambiguity between octal character-entry escapes and back references, which is resolved by heuristics, as hinted at above. A leading zero always indicates an octal escape. A single non-zero digit, not followed by another digit, is always taken as a back reference. A multi-digit sequence not starting with a zero is taken as a back reference if it comes after a suitable subexpression (i.e. the number is in the legal range for a back reference), and otherwise is taken as octal. 


Metasyntax
----------

 In addition to the main syntax described above, there are some special forms and miscellaneous syntactic facilities available.  Normally the flavor of RE being used is specified by application-dependent means. However, this can be overridden by a *director*. If an RE of any flavor begins with “**\*\*\*:**”, the rest of the RE is an ARE. If an RE of any flavor begins with “**\*\*\*=**”, the rest of the RE is taken to be a literal string, with all characters considered ordinary characters. 


 An ARE may begin with *embedded options*: a sequence **(?***xyz***)** (where *xyz* is one or more alphabetic characters) specifies options affecting the rest of the RE. These supplement, and can override, any options specified by the application. The available option letters are: 


 **b**
 rest of RE is a BRE 

**c**
 case-sensitive matching (usual default) 

**e**
 rest of RE is an ERE 

**i**
 case-insensitive matching (see **[MATCHING](#M95)**, below) 

**m**
 historical synonym for **n**

**n**
 newline-sensitive matching (see **[MATCHING](#M95)**, below) 

**p**
 partial newline-sensitive matching (see **[MATCHING](#M95)**, below) 

**q**
 rest of RE is a literal (“quoted”) string, all ordinary characters 

**s**
 non-newline-sensitive matching (usual default) 

**t**
 tight syntax (usual default; see below) 

**w**
 inverse partial newline-sensitive (“weird”) matching (see **[MATCHING](#M95)**, below) 

**x**
 expanded syntax (see below) 

  Embedded options take effect at the **)** terminating the sequence. They are available only at the start of an ARE, and may not be used later within it. 


 In addition to the usual (*tight*) RE syntax, in which all characters are significant, there is an *expanded* syntax, available in all flavors of RE with the **-expanded** switch, or in AREs with the embedded x option. In the expanded syntax, white-space characters are ignored and all characters between a **#** and the following newline (or the end of the RE) are ignored, permitting paragraphing and commenting a complex RE. There are three exceptions to that basic rule: 


* a white-space character or “**#**” preceded by “**\**” is retained
* white space or “**#**” within a bracket expression is retained
* white space and comments are illegal within multi-character symbols like the ARE “**(?:**” or the BRE “**\(**”

  Expanded-syntax white-space characters are blank, tab, newline, and any character that belongs to the *space* character class. 


 Finally, in an ARE, outside bracket expressions, the sequence “**(?#***ttt***)**” (where *ttt* is any text not containing a “**)**”) is a comment, completely ignored. Again, this is not allowed between the characters of multi-character symbols like “**(?:**”. Such comments are more a historical artifact than a useful facility, and their use is deprecated; use the expanded syntax instead. 


 *None* of these metasyntax extensions is available if the application (or an initial “**\*\*\*=**” director) has specified that the user's input be treated as a literal string rather than as an RE. 


Matching
--------

 In the event that an RE could match more than one substring of a given string, the RE matches the one starting earliest in the string. If the RE could match more than one substring starting at that point, its choice is determined by its *preference*: either the longest substring, or the shortest.  Most atoms, and all constraints, have no preference. A parenthesized RE has the same preference (possibly none) as the RE. A quantified atom with quantifier **{***m***}** or **{***m***}?** has the same preference (possibly none) as the atom itself. A quantified atom with other normal quantifiers (including **{***m***,***n***}** with *m* equal to *n*) prefers longest match. A quantified atom with other non-greedy quantifiers (including **{***m***,***n***}?** with *m* equal to *n*) prefers shortest match. A branch has the same preference as the first quantified atom in it which has a preference. An RE consisting of two or more branches connected by the **|** operator prefers longest match. 


 Subject to the constraints imposed by the rules for matching the whole RE, subexpressions also match the longest or shortest possible substrings, based on their preferences, with subexpressions starting earlier in the RE taking priority over ones starting later. Note that outer subexpressions thus take priority over their component subexpressions. 


 The quantifiers **{1,1}** and **{1,1}?** can be used to force longest and shortest preference, respectively, on a subexpression or a whole RE. 


  **NOTE:** This means that you can usually make a RE be non-greedy overall by putting **{1,1}?** after one of the first non-constraint atoms or parenthesized sub-expressions in it. *It pays to experiment* with the placing of this non-greediness override on a suitable range of input texts when you are writing a RE if you are using this level of complexity. 


 For example, this regular expression is non-greedy, and will match the shortest substring possible given that “**abc**” will be matched as early as possible (the quantifier does not change that): 



```
ab{1,1}?c.*x.*cba
```
  The atom “**a**” has no greediness preference, we explicitly give one for “**b**”, and the remaining quantifiers are overridden to be non-greedy by the preceding non-greedy quantifier. 


  Match lengths are measured in characters, not collating elements. An empty string is considered longer than no match at all. For example, “**bb\***” matches the three middle characters of “**abbbc**”, “**(week|wee)(night|knights)**” matches all ten characters of “**weeknights**”, when “**(.\*).\***” is matched against “**abc**” the parenthesized subexpression matches all three characters, and when “**(a\*)\***” is matched against “**bc**” both the whole RE and the parenthesized subexpression match an empty string. 


 If case-independent matching is specified, the effect is much as if all case distinctions had vanished from the alphabet. When an alphabetic that exists in multiple cases appears as an ordinary character outside a bracket expression, it is effectively transformed into a bracket expression containing both cases, so that **x** becomes “**[xX]**”. When it appears inside a bracket expression, all case counterparts of it are added to the bracket expression, so that “**[x]**” becomes “**[xX]**” and “**[^x]**” becomes “**[^xX]**”. 


 If newline-sensitive matching is specified, **.** and bracket expressions using **^** will never match the newline character (so that matches will never cross newlines unless the RE explicitly arranges it) and **^** and **$** will match the empty string after and before a newline respectively, in addition to matching at beginning and end of string respectively. ARE **\A** and **\Z** continue to match beginning or end of string *only*. 


 If partial newline-sensitive matching is specified, this affects **.** and bracket expressions as with newline-sensitive matching, but not **^** and **$**. 


 If inverse partial newline-sensitive matching is specified, this affects **^** and **$** as with newline-sensitive matching, but not **.** and bracket expressions. This is not very useful but is provided for symmetry. 


Limits and compatibility
------------------------

 No particular limit is imposed on the length of REs. Programs intended to be highly portable should not employ REs longer than 256 bytes, as a POSIX-compliant implementation can refuse to accept such REs.  The only feature of AREs that is actually incompatible with POSIX EREs is that **\** does not lose its special significance inside bracket expressions. All other ARE features use syntax which is illegal or has undefined or unspecified effects in POSIX EREs; the **\*\*\*** syntax of directors likewise is outside the POSIX syntax for both BREs and EREs. 


 Many of the ARE extensions are borrowed from Perl, but some have been changed to clean them up, and a few Perl extensions are not present. Incompatibilities of note include “**\b**”, “**\B**”, the lack of special treatment for a trailing newline, the addition of complemented bracket expressions to the things affected by newline-sensitive matching, the restrictions on parentheses and back references in lookahead constraints, and the longest/shortest-match (rather than first-match) matching semantics. 


 The matching rules for REs containing both normal and non-greedy quantifiers have changed since early beta-test versions of this package. (The new rules are much simpler and cleaner, but do not work as hard at guessing the user's real intentions.) 


 Henry Spencer's original 1986 *regexp* package, still in widespread use (e.g., in pre-8.1 releases of Tcl), implemented an early version of today's EREs. There are four incompatibilities between *regexp*'s near-EREs (“RREs” for short) and AREs. In roughly increasing order of significance: 


* In AREs, **\** followed by an alphanumeric character is either an escape or an error, while in RREs, it was just another way of writing the alphanumeric. This should not be a problem because there was no reason to write such a sequence in RREs.
* **{** followed by a digit in an ARE is the beginning of a bound, while in RREs, **{** was always an ordinary character. Such sequences should be rare, and will often result in an error because following characters will not look like a valid bound.
* In AREs, **\** remains a special character within “**[ ]**”, so a literal **\** within **[ ]** must be written “**\\**”. **\\** also gives a literal **\** within **[ ]** in RREs, but only truly paranoid programmers routinely doubled the backslash.
* AREs report the longest/shortest match for the RE, rather than the first found in a specified search order. This may affect some RREs which were written in the expectation that the first match would be reported. (The careful crafting of RREs to optimize the search order for fast matching is obsolete (AREs examine all possible matches in parallel, and their performance is largely insensitive to their complexity) but cases where the search order was exploited to deliberately find a match which was *not* the longest/shortest will need rewriting.)

 Basic regular expressions
-------------------------

 BREs differ from EREs in several respects. “**|**”, “**+**”, and **?** are ordinary characters and there is no equivalent for their functionality. The delimiters for bounds are **\{** and “**\}**”, with **{** and **}** by themselves ordinary characters. The parentheses for nested subexpressions are **\(** and “**\)**”, with **(** and **)** by themselves ordinary characters. **^** is an ordinary character except at the beginning of the RE or the beginning of a parenthesized subexpression, **$** is an ordinary character except at the end of the RE or the end of a parenthesized subexpression, and **\*** is an ordinary character if it appears at the beginning of the RE or the beginning of a parenthesized subexpression (after a possible leading “**^**”). Finally, single-digit back references are available, and **\<** and **\>** are synonyms for “**[[:<:]]**” and “**[[:>:]]**” respectively; no other escapes are available. See also
--------

 **[RegExp](regexp.htm)**, **[regexp](regexp.htm)**, **[regsub](regsub.htm)**, **[lsearch](lsearch.htm)**, **[switch](switch.htm)**, **[text](../tkcmd/text.htm)** Copyright © 1998 Sun Microsystems, Inc.  
 Copyright © 1999 Scriptics Corporation 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/re_syntax.htm>

lsearch
=======

  
[NAME](lsearch.htm#M2) lsearch — See if a list contains a particular element 
[SYNOPSIS](lsearch.htm#M3) 
[DESCRIPTION](lsearch.htm#M4) 
[MATCHING STYLE OPTIONS](lsearch.htm#M5)  
[**-exact**](lsearch.htm#M6) 
[**-glob**](lsearch.htm#M7) 
[**-regexp**](lsearch.htm#M8) 
[**-sorted**](lsearch.htm#M9) 



 
[GENERAL MODIFIER OPTIONS](lsearch.htm#M10)  
[**-all**](lsearch.htm#M11) 
[**-inline**](lsearch.htm#M12) 
[**-not**](lsearch.htm#M13) 
[**-start** *index*](lsearch.htm#M14) 



 
[CONTENTS DESCRIPTION OPTIONS](lsearch.htm#M15)  
[**-ascii**](lsearch.htm#M16) 
[**-dictionary**](lsearch.htm#M17) 
[**-integer**](lsearch.htm#M18) 
[**-nocase**](lsearch.htm#M19) 
[**-real**](lsearch.htm#M20) 




 
[SORTED LIST OPTIONS](lsearch.htm#M21)  
[**-decreasing**](lsearch.htm#M22) 
[**-increasing**](lsearch.htm#M23) 
[**-bisect**](lsearch.htm#M24) 


 
[NESTED LIST OPTIONS](lsearch.htm#M25)  
[**-index** *indexList*](lsearch.htm#M26) 
[**-subindices**](lsearch.htm#M27) 

 
[EXAMPLES](lsearch.htm#M28) 
[SEE ALSO](lsearch.htm#M29) 
[KEYWORDS](lsearch.htm#M30) 










 Name
----

 lsearch — See if a list contains a particular element Synopsis
--------

 **lsearch** ?*options*? *list pattern*  
 Description
-----------

 This command searches the elements of *list* to see if one of them matches *pattern*. If so, the command returns the index of the first matching element (unless the options **-all** or **-inline** are specified.) If not, the command returns **-1**. The *option* arguments indicates how the elements of the list are to be matched against *pattern* and must have one of the values below: ### Matching style options

 If all matching style options are omitted, the default matching style is **-glob**. If more than one matching style is specified, the last matching style given takes precedence. 
 **-exact**
 *Pattern* is a literal string that is compared for exact equality against each list element. 

**-glob**
 *Pattern* is a glob-style pattern which is matched against each list element using the same rules as the **[string match](string.htm)** command. 

**-regexp**
 *Pattern* is treated as a regular expression and matched against each list element using the rules described in the **[re\_syntax](re_syntax.htm)** reference page. 

**-sorted**
 The list elements are in sorted order. If this option is specified, **lsearch** will use a more efficient searching algorithm to search *list*. If no other options are specified, *list* is assumed to be sorted in increasing order, and to contain ASCII strings. This option is mutually exclusive with **-glob** and **-regexp**, and is treated exactly like **-exact** when either **-all** or **-not** are specified. 

 ### General modifier options

 These options may be given with all matching styles. 
 **-all**
 Changes the result to be the list of all matching indices (or all matching values if **-inline** is specified as well.) If indices are returned, the indices will be in numeric order. If values are returned, the order of the values will be the order of those values within the input *list*. 

**-inline**
 The matching value is returned instead of its index (or an empty string if no value matches.) If **-all** is also specified, then the result of the command is the list of all values that matched. 

**-not**
 This negates the sense of the match, returning the index of the first non-matching value in the list. 


**-start** *index*

 The list is searched starting at position *index*. The interpretation of the *index* value is the same as for the command **[string index](string.htm)**, supporting simple index arithmetic and indices relative to the end of the list. 

 ### Contents description options

 These options describe how to interpret the items in the list being searched. They are only meaningful when used with the **-exact** and **-sorted** options. If more than one is specified, the last one takes precedence. The default is **-ascii**. 
 **-ascii**
 The list elements are to be examined as Unicode strings (the name is for backward-compatibility reasons.) 

**-dictionary**
 The list elements are to be compared using dictionary-style comparisons (see **[lsort](lsort.htm)** for a fuller description). Note that this only makes a meaningful difference from the **-ascii** option when the **-sorted** option is given, because values are only dictionary-equal when exactly equal. 

**-integer**
 The list elements are to be compared as integers. 

**-nocase**
 Causes comparisons to be handled in a case-insensitive manner. Has no effect if combined with the **-dictionary**, **-integer**, or **-real** options. 

**-real**
 The list elements are to be compared as floating-point values. 

 ### Sorted list options

 These options (only meaningful with the **-sorted** option) specify how the list is sorted. If more than one is given, the last one takes precedence. The default option is **-increasing**. 
 **-decreasing**
 The list elements are sorted in decreasing order. This option is only meaningful when used with **-sorted**. 

**-increasing**
 The list elements are sorted in increasing order. This option is only meaningful when used with **-sorted**. 

**-bisect**
 Inexact search when the list elements are in sorted order. For an increasing list the last index where the element is less than or equal to the pattern is returned. For a decreasing list the last index where the element is greater than or equal to the pattern is returned. If the pattern is before the first element or the list is empty, -1 is returned. This option implies **-sorted** and cannot be used with either **-all** or **-not**. 

 ### Nested list options

 These options are used to search lists of lists. They may be used with any other options. 
 
**-index** *indexList*

 This option is designed for use when searching within nested lists. The *indexList* argument gives a path of indices (much as might be used with the **[lindex](lindex.htm)** or **[lset](lset.htm)** commands) within each element to allow the location of the term being matched against. 

**-subindices**
 If this option is given, the index result from this command (or every index result when **-all** is also specified) will be a complete path (suitable for use with **[lindex](lindex.htm)** or **[lset](lset.htm)**) within the overall list to the term found. This option has no effect unless the **-index** is also specified, and is just a convenience short-cut. 

 Examples
--------

 Basic searching: 

```
**lsearch** {a b c d e} c
      *→ 2*
**lsearch** -all {a b c a b c} c
      *→ 2 5*
```
  Using **lsearch** to filter lists: 



```
**lsearch** -inline {a20 b35 c47} b*
      *→ b35*
**lsearch** -inline -not {a20 b35 c47} b*
      *→ a20*
**lsearch** -all -inline -not {a20 b35 c47} b*
      *→ a20 c47*
**lsearch** -all -not {a20 b35 c47} b*
      *→ 0 2*
```
  This can even do a “set-like” removal operation: 



```
**lsearch** -all -inline -not -exact {a b c a d e a f g a} a
      *→ b c d e f g*
```
  Searching may start part-way through the list: 



```
**lsearch** -start 3 {a b c a b c} c
      *→ 5*
```
  It is also possible to search inside elements: 



```
**lsearch** -index 1 -all -inline {{a abc} {b bcd} {c cde}} *bc*
      *→ {a abc} {b bcd}*
```
 See also
--------

 **[foreach](foreach.htm)**, **[list](list.htm)**, **[lappend](lappend.htm)**, **[lindex](lindex.htm)**, **[linsert](linsert.htm)**, **[llength](llength.htm)**, **[lset](lset.htm)**, **[lsort](lsort.htm)**, **[lrange](lrange.htm)**, **[lreplace](lreplace.htm)**, **[string](string.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2001 Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved.  
 Copyright © 2003-2004 Donal K. Fellows. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/lsearch.htm>

mathfunc
========

  
[NAME](mathfunc.htm#M2) mathfunc — Mathematical functions for Tcl expressions 
[SYNOPSIS](mathfunc.htm#M3) 
[DESCRIPTION](mathfunc.htm#M4) 
[DETAILED DEFINITIONS](mathfunc.htm#M5)  
[**abs** *arg*](mathfunc.htm#M6) 
[**acos** *arg*](mathfunc.htm#M7) 
[**asin** *arg*](mathfunc.htm#M8) 
[**atan** *arg*](mathfunc.htm#M9) 
[**atan2** *y x*](mathfunc.htm#M10) 
[**bool** *arg*](mathfunc.htm#M11) 
[**ceil** *arg*](mathfunc.htm#M12) 
[**cos** *arg*](mathfunc.htm#M13) 
[**cosh** *arg*](mathfunc.htm#M14) 
[**double** *arg*](mathfunc.htm#M15) 
[**entier** *arg*](mathfunc.htm#M16) 
[**exp** *arg*](mathfunc.htm#M17) 
[**floor** *arg*](mathfunc.htm#M18) 
[**fmod** *x y*](mathfunc.htm#M19) 
[**hypot** *x y*](mathfunc.htm#M20) 
[**int** *arg*](mathfunc.htm#M21) 
[**isqrt** *arg*](mathfunc.htm#M22) 
[**log** *arg*](mathfunc.htm#M23) 
[**log10** *arg*](mathfunc.htm#M24) 
[**max** *arg**...*](mathfunc.htm#M25) 
[**min** *arg**...*](mathfunc.htm#M26) 
[**pow** *x y*](mathfunc.htm#M27) 
[**rand**](mathfunc.htm#M28) 
[**round** *arg*](mathfunc.htm#M29) 
[**sin** *arg*](mathfunc.htm#M30) 
[**sinh** *arg*](mathfunc.htm#M31) 
[**sqrt** *arg*](mathfunc.htm#M32) 
[**srand** *arg*](mathfunc.htm#M33) 
[**tan** *arg*](mathfunc.htm#M34) 
[**tanh** *arg*](mathfunc.htm#M35) 
[**wide** *arg*](mathfunc.htm#M36) 






























 
[SEE ALSO](mathfunc.htm#M37) 
[COPYRIGHT](mathfunc.htm#M38) 





 Name
----

 mathfunc — Mathematical functions for Tcl expressions Synopsis
--------

 package require **Tcl 8.5**  
 **::tcl::mathfunc::abs** *arg*  
 **::tcl::mathfunc::acos** *arg*  
 **::tcl::mathfunc::asin** *arg*  
 **::tcl::mathfunc::atan** *arg*  
 **::tcl::mathfunc::atan2** *y* *x*  
 **::tcl::mathfunc::bool** *arg*  
 **::tcl::mathfunc::ceil** *arg*  
 **::tcl::mathfunc::cos** *arg*  
 **::tcl::mathfunc::cosh** *arg*  
 **::tcl::mathfunc::double** *arg*  
 **::tcl::mathfunc::entier** *arg*  
 **::tcl::mathfunc::exp** *arg*  
 **::tcl::mathfunc::floor** *arg*  
 **::tcl::mathfunc::fmod** *x* *y*  
 **::tcl::mathfunc::hypot** *x* *y*  
 **::tcl::mathfunc::int** *arg*  
 **::tcl::mathfunc::isqrt** *arg*  
 **::tcl::mathfunc::log** *arg*  
 **::tcl::mathfunc::log10** *arg*  
 **::tcl::mathfunc::max** *arg* ?*arg* ...?  
 **::tcl::mathfunc::min** *arg* ?*arg* ...?  
 **::tcl::mathfunc::pow** *x* *y*  
 **::tcl::mathfunc::rand**  
 **::tcl::mathfunc::round** *arg*  
 **::tcl::mathfunc::sin** *arg*  
 **::tcl::mathfunc::sinh** *arg*  
 **::tcl::mathfunc::sqrt** *arg*  
 **::tcl::mathfunc::srand** *arg*  
 **::tcl::mathfunc::tan** *arg*  
 **::tcl::mathfunc::tanh** *arg*  
 **::tcl::mathfunc::wide** *arg*  
 Description
-----------

 The **[expr](expr.htm)** command handles mathematical functions of the form **sin($x)** or **atan2($y,$x)** by converting them to calls of the form **[tcl::mathfunc::sin [expr {$x}]]** or **[tcl::mathfunc::atan2 [expr {$y}] [expr {$x}]]**. A number of math functions are available by default within the namespace **::tcl::mathfunc**; these functions are also available for code apart from **[expr](expr.htm)**, by invoking the given commands directly.  Tcl supports the following mathematical functions in expressions, all of which work solely with floating-point numbers unless otherwise noted: 




|  |  |  |  |
| --- | --- | --- | --- |
| **abs** | **acos** | **asin** | **atan** |
| **atan2** | **bool** | **ceil** | **cos** |
| **cosh** | **double** | **entier** | **exp** |
| **floor** | **fmod** | **hypot** | **int** |
| **isqrt** | **log** | **log10** | **max** |
| **min** | **pow** | **rand** | **round** |
| **sin** | **sinh** | **sqrt** | **srand** |
| **tan** | **tanh** | **wide** |

  In addition to these predefined functions, applications may define additional functions by using **[proc](proc.htm)** (or any other method, such as **[interp alias](interp.htm)** or **[Tcl\_CreateObjCommand](https://www.tcl.tk/man/tcl/TclLib/CrtObjCmd.htm)**) to define new commands in the **tcl::mathfunc** namespace. In addition, an obsolete interface named **[Tcl\_CreateMathFunc](https://www.tcl.tk/man/tcl/TclLib/CrtMathFnc.htm)**() is available to extensions that are written in C. The latter interface is not recommended for new implementations. 


### Detailed definitions

  
**abs** *arg*

 Returns the absolute value of *arg*. *Arg* may be either integer or floating-point, and the result is returned in the same form. 


**acos** *arg*

 Returns the arc cosine of *arg*, in the range [*0*,*pi*] radians. *Arg* should be in the range [*-1*,*1*]. 


**asin** *arg*

 Returns the arc sine of *arg*, in the range [*-pi/2*,*pi/2*] radians. *Arg* should be in the range [*-1*,*1*]. 


**atan** *arg*

 Returns the arc tangent of *arg*, in the range [*-pi/2*,*pi/2*] radians. 


**atan2** *y x*

 Returns the arc tangent of *y*/*x*, in the range [*-pi*,*pi*] radians. *x* and *y* cannot both be 0. If *x* is greater than *0*, this is equivalent to “**atan** [**[expr](expr.htm)** {*y***/***x*}]”. 


**bool** *arg*

 Accepts any numeric value, or any string acceptable to **string is boolean**, and returns the corresponding boolean value **0** or **1**. Non-zero numbers are true. Other numbers are false. Non-numeric strings produce boolean value in agreement with **string is true** and **string is false**. 


**ceil** *arg*

 Returns the smallest integral floating-point value (i.e. with a zero fractional part) not less than *arg*. The argument may be any numeric value. 


**cos** *arg*

 Returns the cosine of *arg*, measured in radians. 


**cosh** *arg*

 Returns the hyperbolic cosine of *arg*. If the result would cause an overflow, an error is returned. 


**double** *arg*

 The argument may be any numeric value, If *arg* is a floating-point value, returns *arg*, otherwise converts *arg* to floating-point and returns the converted value. May return **Inf** or **-Inf** when the argument is a numeric value that exceeds the floating-point range. 


**entier** *arg*

 The argument may be any numeric value. The integer part of *arg* is determined and returned. The integer range returned by this function is unlimited, unlike **int** and **wide** which truncate their range to fit in particular storage widths. 


**exp** *arg*

 Returns the exponential of *arg*, defined as *e*\*\**arg*. If the result would cause an overflow, an error is returned. 


**floor** *arg*

 Returns the largest integral floating-point value (i.e. with a zero fractional part) not greater than *arg*. The argument may be any numeric value. 


**fmod** *x y*

 Returns the floating-point remainder of the division of *x* by *y*. If *y* is 0, an error is returned. 


**hypot** *x y*

 Computes the length of the hypotenuse of a right-angled triangle, approximately “**sqrt** [**[expr](expr.htm)** {*x***\****x***+***y***\****y*}]” except for being more numerically stable when the two arguments have substantially different magnitudes. 


**int** *arg*

 The argument may be any numeric value. The integer part of *arg* is determined, and then the low order bits of that integer value up to the machine word size are returned as an integer value. For reference, the number of bytes in the machine word are stored in the **wordSize** element of the **[tcl\_platform](tclvars.htm)** array. 


**isqrt** *arg*

 Computes the integer part of the square root of *arg*. *Arg* must be a positive value, either an integer or a floating point number. Unlike **sqrt**, which is limited to the precision of a floating point number, *isqrt* will return a result of arbitrary precision. 


**log** *arg*

 Returns the natural logarithm of *arg*. *Arg* must be a positive value. 


**log10** *arg*

 Returns the base 10 logarithm of *arg*. *Arg* must be a positive value. 


**max** *arg**...*

 Accepts one or more numeric arguments. Returns the one argument with the greatest value. 


**min** *arg**...*

 Accepts one or more numeric arguments. Returns the one argument with the least value. 


**pow** *x y*

 Computes the value of *x* raised to the power *y*. If *x* is negative, *y* must be an integer value. 

**rand**
 Returns a pseudo-random floating-point value in the range (*0*,*1*). The generator algorithm is a simple linear congruential generator that is not cryptographically secure. Each result from **rand** completely determines all future results from subsequent calls to **rand**, so **rand** should not be used to generate a sequence of secrets, such as one-time passwords. The seed of the generator is initialized from the internal clock of the machine or may be set with the **srand** function. 


**round** *arg*

 If *arg* is an integer value, returns *arg*, otherwise converts *arg* to integer by rounding and returns the converted value. 


**sin** *arg*

 Returns the sine of *arg*, measured in radians. 


**sinh** *arg*

 Returns the hyperbolic sine of *arg*. If the result would cause an overflow, an error is returned. 


**sqrt** *arg*

 The argument may be any non-negative numeric value. Returns a floating-point value that is the square root of *arg*. May return **Inf** when the argument is a numeric value that exceeds the square of the maximum value of the floating-point range. 


**srand** *arg*

 The *arg*, which must be an integer, is used to reset the seed for the random number generator of **rand**. Returns the first random number (see **rand**) from that seed. Each interpreter has its own seed. 


**tan** *arg*

 Returns the tangent of *arg*, measured in radians. 


**tanh** *arg*

 Returns the hyperbolic tangent of *arg*. 


**wide** *arg*

 The argument may be any numeric value. The integer part of *arg* is determined, and then the low order 64 bits of that integer value are returned as an integer value. 

 See also
--------

 **[expr](expr.htm)**, **[mathop](mathop.htm)**, **[namespace](namespace.htm)** Copyright
---------

 Copyright (c) 1993 The Regents of the University of California.  
 Copyright (c) 1994-2000 Sun Microsystems Incorporated.  
 Copyright (c) 2005, 2006 by Kevin B. Kenny <kennykb@acm.org>.  
 Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-2000 Sun Microsystems, Inc.  
 Copyright © 2005 by Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/mathfunc.htm>

tell
====

 Name
----

 tell — Return current access position for an open channel Synopsis
--------

 **tell** *channelId*  
 Description
-----------

 Returns an integer string giving the current access position in *channelId*. This value returned is a byte offset that can be passed to **[seek](seek.htm)** in order to set the channel to a particular position. Note that this value is in terms of bytes, not characters like **[read](read.htm)**. The value returned is -1 for channels that do not support seeking.  *ChannelId* must be an identifier for an open channel such as a Tcl standard channel (**[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, or **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**), the return value from an invocation of **[open](open.htm)** or **[socket](socket.htm)**, or the result of a channel creation command provided by a Tcl extension. 


Example
-------

 Read a line from a file channel only if it starts with **foobar**: 

```
# Save the offset in case we need to undo the read...
set offset [**tell** $chan]
if {[read $chan 6] eq "foobar"} {
    gets $chan line
} else {
    set line {}
    # Undo the read...
    seek $chan $offset
}
```
 See also
--------

 **[file](file.htm)**, **[open](open.htm)**, **[close](close.htm)**, **[gets](gets.htm)**, **[seek](seek.htm)**, **[Tcl\_StandardChannels](https://www.tcl.tk/man/tcl/TclLib/StdChannels.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/tell.htm>

return
======

  
[NAME](return.htm#M2) return — Return from a procedure, or set return code of a script 
[SYNOPSIS](return.htm#M3) 
[DESCRIPTION](return.htm#M4) 
[EXCEPTIONAL RETURN CODES](return.htm#M5)  
[**ok** (or **0**)](return.htm#M6) 
[**error** (or **1**)](return.htm#M7) 
[**return** (or **2**)](return.htm#M8) 
[**break** (or **3**)](return.htm#M9) 
[**continue** (or **4**)](return.htm#M10) 
[*value*](return.htm#M11) 





 
[RETURN OPTIONS](return.htm#M12)  
[**-errorcode** *list*](return.htm#M13) 
[**-errorinfo** *info*](return.htm#M14) 
[**-errorstack** *list*](return.htm#M15) 
[**-level** *level*](return.htm#M16) 
[**-options** *options*](return.htm#M17) 




 
[RETURN CODE HANDLING MECHANISMS](return.htm#M18) 
[EXAMPLES](return.htm#M19) 
[SEE ALSO](return.htm#M20) 
[KEYWORDS](return.htm#M21) 








 Name
----

 return — Return from a procedure, or set return code of a script Synopsis
--------

 **return** ?*result*?  
 **return** ?**-code** *code*? ?*result*?  
 **return** ?*option value* ...? ?*result*?  
 Description
-----------

 In its simplest usage, the **return** command is used without options in the body of a procedure to immediately return control to the caller of the procedure. If a *result* argument is provided, its value becomes the result of the procedure passed back to the caller. If *result* is not specified then an empty string will be returned to the caller as the result of the procedure.  The **return** command serves a similar function within script files that are evaluated by the **[source](source.htm)** command. When **[source](source.htm)** evaluates the contents of a file as a script, an invocation of the **return** command will cause script evaluation to immediately cease, and the value *result* (or an empty string) will be returned as the result of the **[source](source.htm)** command. 


Exceptional return codes
------------------------

 In addition to the result of a procedure, the return code of a procedure may also be set by **return** through use of the **-code** option. In the usual case where the **-code** option is not specified the procedure will return normally. However, the **-code** option may be used to generate an exceptional return from the procedure. *Code* may have any of the following values: 
 
**ok** (or **0**)
 Normal return: same as if the option is omitted. The return code of the procedure is 0 (**[TCL\_OK](catch.htm)**). 


**error** (or **1**)
 Error return: the return code of the procedure is 1 (**[TCL\_ERROR](catch.htm)**). The procedure command behaves in its calling context as if it were the command **[error](error.htm)** *result*. See below for additional options. 


**return** (or **2**)
 The return code of the procedure is 2 (**[TCL\_RETURN](catch.htm)**). The procedure command behaves in its calling context as if it were the command **return** (with no arguments). 


**break** (or **3**)
 The return code of the procedure is 3 (**[TCL\_BREAK](catch.htm)**). The procedure command behaves in its calling context as if it were the command **[break](break.htm)**. 


**continue** (or **4**)
 The return code of the procedure is 4 (**[TCL\_CONTINUE](catch.htm)**). The procedure command behaves in its calling context as if it were the command **[continue](continue.htm)**. 

*value*
 *Value* must be an integer; it will be returned as the return code for the current procedure. 

  When a procedure wants to signal that it has received invalid arguments from its caller, it may use **return -code error** with *result* set to a suitable error message. Otherwise usage of the **return -code** option is mostly limited to procedures that implement a new control structure. 


 The **return -code** command acts similarly within script files that are evaluated by the **[source](source.htm)** command. During the evaluation of the contents of a file as a script by **[source](source.htm)**, an invocation of the **return -code** *code* command will cause the return code of **[source](source.htm)** to be *code*. 


Return options
--------------

 In addition to a result and a return code, evaluation of a command in Tcl also produces a dictionary of return options. In general usage, all *option value* pairs given as arguments to **return** become entries in the return options dictionary, and any values at all are acceptable except as noted below. The **[catch](catch.htm)** command may be used to capture all of this information — the return code, the result, and the return options dictionary — that arise from evaluation of a script.  As documented above, the **-code** entry in the return options dictionary receives special treatment by Tcl. There are other return options also recognized and treated specially by Tcl. They are: 


 
**-errorcode** *list*

 The **-errorcode** option receives special treatment only when the value of the **-code** option is **[TCL\_ERROR](catch.htm)**. Then the *list* value is meant to be additional information about the error, presented as a Tcl list for further processing by programs. If no **-errorcode** option is provided to **return** when the **-code error** option is provided, Tcl will set the value of the **-errorcode** entry in the return options dictionary to the default value of **NONE**. The **-errorcode** return option will also be stored in the global variable **[errorCode](tclvars.htm)**. 


**-errorinfo** *info*

 The **-errorinfo** option receives special treatment only when the value of the **-code** option is **[TCL\_ERROR](catch.htm)**. Then *info* is the initial stack trace, meant to provide to a human reader additional information about the context in which the error occurred. The stack trace will also be stored in the global variable **[errorInfo](tclvars.htm)**. If no **-errorinfo** option is provided to **return** when the **-code error** option is provided, Tcl will provide its own initial stack trace value in the entry for **-errorinfo**. Tcl's initial stack trace will include only the call to the procedure, and stack unwinding will append information about higher stack levels, but there will be no information about the context of the error within the procedure. Typically the *info* value is supplied from the value of **-errorinfo** in a return options dictionary captured by the **[catch](catch.htm)** command (or from the copy of that information stored in the global variable **[errorInfo](tclvars.htm)**). 


**-errorstack** *list*

 The **-errorstack** option receives special treatment only when the value of the **-code** option is **[TCL\_ERROR](catch.htm)**. Then *list* is the initial error stack, recording actual argument values passed to each proc level. The error stack will also be reachable through **[info errorstack](info.htm)**. If no **-errorstack** option is provided to **return** when the **-code error** option is provided, Tcl will provide its own initial error stack in the entry for **-errorstack**. Tcl's initial error stack will include only the call to the procedure, and stack unwinding will append information about higher stack levels, but there will be no information about the context of the error within the procedure. Typically the *list* value is supplied from the value of **-errorstack** in a return options dictionary captured by the **[catch](catch.htm)** command (or from the copy of that information from **[info errorstack](info.htm)**). 


**-level** *level*

 The **-level** and **-code** options work together to set the return code to be returned by one of the commands currently being evaluated. The *level* value must be a non-negative integer representing a number of levels on the call stack. It defines the number of levels up the stack at which the return code of a command currently being evaluated should be *code*. If no **-level** option is provided, the default value of *level* is 1, so that **return** sets the return code that the current procedure returns to its caller, 1 level up the call stack. The mechanism by which these options work is described in more detail below. 


**-options** *options*

 The value *options* must be a valid dictionary. The entries of that dictionary are treated as additional *option value* pairs for the **return** command. 

 Return code handling mechanisms
-------------------------------

 Return codes are used in Tcl to control program flow. A Tcl script is a sequence of Tcl commands. So long as each command evaluation returns a return code of **[TCL\_OK](catch.htm)**, evaluation will continue to the next command in the script. Any exceptional return code (non-**[TCL\_OK](catch.htm)**) returned by a command evaluation causes the flow on to the next command to be interrupted. Script evaluation ceases, and the exceptional return code from the command becomes the return code of the full script evaluation. This is the mechanism by which errors during script evaluation cause an interruption and unwinding of the call stack. It is also the mechanism by which commands like **[break](break.htm)**, **[continue](continue.htm)**, and **return** cause script evaluation to terminate without evaluating all commands in sequence.  Some of Tcl's built-in commands evaluate scripts as part of their functioning. These commands can make use of exceptional return codes to enable special features. For example, the built-in Tcl commands that provide loops — such as **[while](while.htm)**, **[for](for.htm)**, and **[foreach](foreach.htm)** — evaluate a script that is the body of the loop. If evaluation of the loop body returns the return code of **[TCL\_BREAK](catch.htm)** or **[TCL\_CONTINUE](catch.htm)**, the loop command can react in such a way as to give the **[break](break.htm)** and **[continue](continue.htm)** commands their documented interpretation in loops. 


 Procedure invocation also involves evaluation of a script, the body of the procedure. Procedure invocation provides special treatment when evaluation of the procedure body returns the return code **[TCL\_RETURN](catch.htm)**. In that circumstance, the **-level** entry in the return options dictionary is decremented. If after decrementing, the value of the **-level** entry is 0, then the value of the **-code** entry becomes the return code of the procedure. If after decrementing, the value of the **-level** entry is greater than zero, then the return code of the procedure is **[TCL\_RETURN](catch.htm)**. If the procedure invocation occurred during the evaluation of the body of another procedure, the process will repeat itself up the call stack, decrementing the value of the **-level** entry at each level, so that the *code* will be the return code of the current command *level* levels up the call stack. The **[source](source.htm)** command performs the same handling of the **[TCL\_RETURN](catch.htm)** return code, which explains the similarity of **return** invocation during a **[source](source.htm)** to **return** invocation within a procedure. 


 The return code of the **return** command itself triggers this special handling by procedure invocation. If **return** is provided the option **-level 0**, then the return code of the **return** command itself will be the value *code* of the **-code** option (or **[TCL\_OK](catch.htm)** by default). Any other value for the **-level** option (including the default value of 1) will cause the return code of the **return** command itself to be **[TCL\_RETURN](catch.htm)**, triggering a return from the enclosing procedure. 


Examples
--------

 First, a simple example of using **return** to return from a procedure, interrupting the procedure body. 

```
proc printOneLine {} {
    puts "line 1"    ;# This line will be printed.
    **return**
    puts "line 2"    ;# This line will not be printed.
}
```
  Next, an example of using **return** to set the value returned by the procedure. 



```
proc returnX {} {**return** X}
puts [returnX]    ;# prints "X"
```
  Next, a more complete example, using **return -code error** to report invalid arguments. 



```
proc factorial {n} {
    if {![string is integer $n] || ($n < 0)} {
        **return** -code error \
                "expected non-negative integer,\
                but got \"$n\""
    }
    if {$n < 2} {
        **return** 1
    }
    set m [expr {$n - 1}]
    set code [catch {factorial $m} factor]
    if {$code != 0} {
        **return** -code $code $factor
    }
    set product [expr {$n * $factor}]
    if {$product < 0} {
        **return** -code error \
                "overflow computing factorial of $n"
    }
    **return** $product
}
```
  Next, a procedure replacement for **[break](break.htm)**. 



```
proc myBreak {} {
    **return** -code break
}
```
  With the **-level 0** option, **return** itself can serve as a replacement for **[break](break.htm)**, with the help of **[interp alias](interp.htm)**. 



```
interp alias {} Break {} **return** -level 0 -code break
```
  An example of using **[catch](catch.htm)** and **return -options** to re-raise a caught error: 



```
proc doSomething {} {
    set resource [allocate]
    catch {
        # Long script of operations
        # that might raise an error
    } result options
    deallocate $resource
    **return** -options $options $result
}
```
  Finally an example of advanced use of the **return** options to create a procedure replacement for **return** itself: 



```
proc myReturn {args} {
    set result ""
    if {[llength $args] % 2} {
        set result [lindex $args end]
        set args [lrange $args 0 end-1]
    }
    set options [dict merge {-level 1} $args]
    dict incr options -level
    **return** -options $options $result
}
```
 See also
--------

 **[break](break.htm)**, **[catch](catch.htm)**, **[continue](continue.htm)**, **[dict](dict.htm)**, **[error](error.htm)**, **[errorCode](tclvars.htm)**, **[errorInfo](tclvars.htm)**, **[proc](proc.htm)**, **[source](source.htm)**, **[throw](throw.htm)**, **[try](try.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/return.htm>

throw
=====

 Name
----

 throw — Generate a machine-readable error Synopsis
--------

 **throw** *type message*  
 Description
-----------

 This command causes the current evaluation to be unwound with an error. The error created is described by the *type* and *message* arguments: *type* must contain a list of words describing the error in a form that is machine-readable (and which will form the error-code part of the result dictionary), and *message* should contain text that is intended for display to a human being.  The stack will be unwound until the error is trapped by a suitable **[catch](catch.htm)** or **[try](try.htm)** command. If it reaches the event loop without being trapped, it will be reported through the **[bgerror](bgerror.htm)** mechanism. If it reaches the top level of script evaluation in **[tclsh](../usercmd/tclsh.htm)**, it will be printed on the console before, in the non-interactive case, causing an exit (the behavior in other programs will depend on the details of how Tcl is embedded and used). 


 By convention, the words in the *type* argument should go from most general to most specific. 


Examples
--------

 The following produces an error that is identical to that produced by **[expr](expr.htm)** when trying to divide a value by zero. 

```
**throw** {ARITH DIVZERO {divide by zero}} {divide by zero}
```
 See also
--------

 **[catch](catch.htm)**, **[error](error.htm)**, **[errorCode](tclvars.htm)**, **[errorInfo](tclvars.htm)**, **[return](return.htm)**, **[try](try.htm)** Copyright © 2008 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/throw.htm>

flush
=====

 Name
----

 flush — Flush buffered output for a channel Synopsis
--------

 **flush** *channelId*  
 Description
-----------

 Flushes any output that has been buffered for *channelId*.  *ChannelId* must be an identifier for an open channel such as a Tcl standard channel (**[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** or **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**), the return value from an invocation of **[open](open.htm)** or **[socket](socket.htm)**, or the result of a channel creation command provided by a Tcl extension. The channel must have been opened for writing. 


 If the channel is in blocking mode the command does not return until all the buffered output has been flushed to the channel. If the channel is in nonblocking mode, the command may return before all buffered output has been flushed; the remainder will be flushed in the background as fast as the underlying file or device is able to absorb it. 


Example
-------

 Prompt for the user to type some information in on the console: 

```
puts -nonewline "Please type your name: "
**flush** stdout
gets stdin name
puts "Hello there, $name!"
```
 See also
--------

 **[file](file.htm)**, **[open](open.htm)**, **[socket](socket.htm)**, **[Tcl\_StandardChannels](https://www.tcl.tk/man/tcl/TclLib/StdChannels.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/flush.htm>

time
====

 Name
----

 time — Time the execution of a script Synopsis
--------

 **time** *script* ?*count*?  
 Description
-----------

 This command will call the Tcl interpreter *count* times to evaluate *script* (or once if *count* is not specified). It will then return a string of the form 

```
**503.2 microseconds per iteration**
```
  which indicates the average amount of time required per iteration, in microseconds. Time is measured in elapsed time, not CPU time. 


Example
-------

 Estimate how long it takes for a simple Tcl **[for](for.htm)** loop to count to a thousand: 

```
time {
    for {set i 0} {$i<1000} {incr i} {
        # empty body
    }
}
```
 See also
--------

 **[clock](clock.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/time.htm>

fileevent
=========

 Name
----

 fileevent — Execute a script when a channel becomes readable or writable Synopsis
--------

 **fileevent** *channelId* **readable** ?*script*?  
 **fileevent** *channelId* **writable** ?*script*?  
 Description
-----------

 This command is used to create *file event handlers*. A file event handler is a binding between a channel and a script, such that the script is evaluated whenever the channel becomes readable or writable. File event handlers are most commonly used to allow data to be received from another process on an event-driven basis, so that the receiver can continue to interact with the user while waiting for the data to arrive. If an application invokes **[gets](gets.htm)** or **[read](read.htm)** on a blocking channel when there is no input data available, the process will block; until the input data arrives, it will not be able to service other events, so it will appear to the user to “freeze up”. With **fileevent**, the process can tell when data is present and only invoke **[gets](gets.htm)** or **[read](read.htm)** when they will not block.  The *channelId* argument to **fileevent** refers to an open channel such as a Tcl standard channel (**[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, or **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**), the return value from an invocation of **[open](open.htm)** or **[socket](socket.htm)**, or the result of a channel creation command provided by a Tcl extension. 


 If the *script* argument is specified, then **fileevent** creates a new event handler: *script* will be evaluated whenever the channel becomes readable or writable (depending on the second argument to **fileevent**). In this case **fileevent** returns an empty string. The **readable** and **writable** event handlers for a file are independent, and may be created and deleted separately. However, there may be at most one **readable** and one **writable** handler for a file at a given time in a given interpreter. If **fileevent** is called when the specified handler already exists in the invoking interpreter, the new script replaces the old one. 


 If the *script* argument is not specified, **fileevent** returns the current script for *channelId*, or an empty string if there is none. If the *script* argument is specified as an empty string then the event handler is deleted, so that no script will be invoked. A file event handler is also deleted automatically whenever its channel is closed or its interpreter is deleted. 


 A channel is considered to be readable if there is unread data available on the underlying device. A channel is also considered to be readable if there is unread data in an input buffer, except in the special case where the most recent attempt to read from the channel was a **[gets](gets.htm)** call that could not find a complete line in the input buffer. This feature allows a file to be read a line at a time in nonblocking mode using events. A channel is also considered to be readable if an end of file or error condition is present on the underlying file or device. It is important for *script* to check for these conditions and handle them appropriately; for example, if there is no special check for end of file, an infinite loop may occur where *script* reads no data, returns, and is immediately invoked again. 


 A channel is considered to be writable if at least one byte of data can be written to the underlying file or device without blocking, or if an error condition is present on the underlying file or device. 


 Event-driven I/O works best for channels that have been placed into nonblocking mode with the **[fconfigure](fconfigure.htm)** command. In blocking mode, a **[puts](puts.htm)** command may block if you give it more data than the underlying file or device can accept, and a **[gets](gets.htm)** or **[read](read.htm)** command will block if you attempt to read more data than is ready; a readable underlying file or device may not even guarantee that a blocking [read 1] will succeed (counter-examples being multi-byte encodings, compression or encryption transforms ). In all such cases, no events will be processed while the commands block. 


 In nonblocking mode **[puts](puts.htm)**, **[read](read.htm)**, and **[gets](gets.htm)** never block. See the documentation for the individual commands for information on how they handle blocking and nonblocking channels. 


 Testing for the end of file condition should be done after any attempts read the channel data. The eof flag is set once an attempt to read the end of data has occurred and testing before this read will require an additional event to be fired. 


 The script for a file event is executed at global level (outside the context of any Tcl procedure) in the interpreter in which the **fileevent** command was invoked. If an error occurs while executing the script then the command registered with **[interp bgerror](interp.htm)** is used to report the error. In addition, the file event handler is deleted if it ever returns an error; this is done in order to prevent infinite loops due to buggy handlers. 


Example
-------

 In this setup **GetData** will be called with the channel as an argument whenever $chan becomes readable. The **[read](read.htm)** call will read whatever binary data is currently available without blocking. Here the channel has the fileevent removed when an end of file occurs to avoid being continually called (see above). Alternatively the channel may be closed on this condition. 

```
proc GetData {chan} {
    set data [read $chan]
    puts "[string length $data] $data"
    if {[eof $chan]} {
        fileevent $chan readable {}
    }
}

fconfigure $chan -blocking 0 -encoding binary
**fileevent** $chan readable [list GetData $chan]
```
  The next example demonstrates use of **[gets](gets.htm)** to read line-oriented data. 



```
proc GetData {chan} {
    if {[gets $chan line] >= 0} {
        puts $line
    }
    if {[eof $chan]} {
        close $chan
    }
}

fconfigure $chan -blocking 0 -buffering line -translation crlf
**fileevent** $chan readable [list GetData $chan]
```
 Credits
-------

 **fileevent** is based on the **addinput** command created by Mark Diekhans. See also
--------

 **[fconfigure](fconfigure.htm)**, **[gets](gets.htm)**, **[interp](interp.htm)**, **[puts](puts.htm)**, **[read](read.htm)**, **[Tcl\_StandardChannels](https://www.tcl.tk/man/tcl/TclLib/StdChannels.htm)** Copyright © 1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2008 Pat Thoyts 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/fileevent.htm>

filename
========

  
[NAME](filename.htm#M2) filename — File name conventions supported by Tcl commands 
[INTRODUCTION](filename.htm#M3) 
[PATH TYPES](filename.htm#M4) 
[PATH SYNTAX](filename.htm#M5)  
[**Unix**](filename.htm#M6)  
[**/**](filename.htm#M7) 
[**/etc/passwd**](filename.htm#M8) 
 [**.**](filename.htm#M9) 
[**foo**](filename.htm#M10) 
[**foo/bar**](filename.htm#M11) 
 [**../foo**](filename.htm#M12) 





 
[**Windows**](filename.htm#M13)  
 [**\\Host\share/file**](filename.htm#M14) 
[**c:foo**](filename.htm#M15) 
[**c:/foo**](filename.htm#M16) 
[**foo\bar**](filename.htm#M17) 
 [**\foo**](filename.htm#M18) 
 [**\\foo**](filename.htm#M19) 





 

 
[TILDE SUBSTITUTION](filename.htm#M20) 
[PORTABILITY ISSUES](filename.htm#M21) 
[SEE ALSO](filename.htm#M22) 
[KEYWORDS](filename.htm#M23) 







 Name
----

 filename — File name conventions supported by Tcl commands Introduction
------------

 All Tcl commands and C procedures that take file names as arguments expect the file names to be in one of three forms, depending on the current platform. On each platform, Tcl supports file names in the standard forms(s) for that platform. In addition, on all platforms, Tcl supports a Unix-like syntax intended to provide a convenient way of constructing simple file names. However, scripts that are intended to be portable should not assume a particular form for file names. Instead, portable scripts must use the **[file split](file.htm)** and **file join** commands to manipulate file names (see the **[file](file.htm)** manual entry for more details). Path types
----------

 File names are grouped into three general types based on the starting point for the path used to specify the file: absolute, relative, and volume-relative. Absolute names are completely qualified, giving a path to the file relative to a particular volume and the root directory on that volume. Relative names are unqualified, giving a path to the file relative to the current working directory. Volume-relative names are partially qualified, either giving the path relative to the root directory on the current volume, or relative to the current directory of the specified volume. The **[file pathtype](file.htm)** command can be used to determine the type of a given path. Path syntax
-----------

 The rules for native names depend on the value reported in the Tcl **[platform](platform.htm)** element of the **[tcl\_platform](tclvars.htm)** array: 
 **Unix**
 On Unix and Apple MacOS X platforms, Tcl uses path names where the components are separated by slashes. Path names may be relative or absolute, and file names may contain any character other than slash. The file names  **.** and  **..** are special and refer to the current directory and the parent of the current directory respectively. Multiple adjacent slash characters are interpreted as a single separator. Any number of trailing slash characters at the end of a path are simply ignored, so the paths **foo**, **foo/** and **foo//** are all identical, and in particular **foo/** does not necessarily mean a directory is being referred.  The following examples illustrate various forms of path names: 


 **/**
 Absolute path to the root directory. 

**/etc/passwd**
 Absolute path to the file named **passwd** in the directory **etc** in the root directory. 

 **.**
 Relative path to the current directory. 

**foo**
 Relative path to the file **foo** in the current directory. 

**foo/bar**
 Relative path to the file **bar** in the directory **foo** in the current directory. 

 **../foo**
 Relative path to the file **foo** in the directory above the current directory. 



**Windows**
 On Microsoft Windows platforms, Tcl supports both drive-relative and UNC style names. Both **/** and **\** may be used as directory separators in either type of name. Drive-relative names consist of an optional drive specifier followed by an absolute or relative path. UNC paths follow the general form **\\servername\sharename\path\file**, but must at the very least contain the server and share components, i.e. **\\servername\sharename**. In both forms, the file names **.** and **..** are special and refer to the current directory and the parent of the current directory respectively. The following examples illustrate various forms of path names: 
  **\\Host\share/file**
 Absolute UNC path to a file called **[file](file.htm)** in the root directory of the export point **share** on the host **Host**. Note that repeated use of **[file dirname](file.htm)** on this path will give **//Host/share**, and will never give just **//Host**. 

**c:foo**
 Volume-relative path to a file **foo** in the current directory on drive **c**. 

**c:/foo**
 Absolute path to a file **foo** in the root directory of drive **c**. 

**foo\bar**
 Relative path to a file **bar** in the **foo** directory in the current directory on the current volume. 

 **\foo**
 Volume-relative path to a file **foo** in the root directory of the current volume. 

 **\\foo**
 Volume-relative path to a file **foo** in the root directory of the current volume. This is not a valid UNC path, so the assumption is that the extra backslashes are superfluous. 



 Tilde substitution
------------------

 In addition to the file name rules described above, Tcl also supports *csh*-style tilde substitution. If a file name starts with a tilde, then the file name will be interpreted as if the first element is replaced with the location of the home directory for the given user. If the tilde is followed immediately by a separator, then the **$HOME** environment variable is substituted. Otherwise the characters between the tilde and the next separator are taken as a user name, which is used to retrieve the user's home directory for substitution. This works on Unix, MacOS X and Windows (except very old releases).  Old Windows platforms do not support tilde substitution when a user name follows the tilde. On these platforms, attempts to use a tilde followed by a user name will generate an error that the user does not exist when Tcl attempts to interpret that part of the path or otherwise access the file. The behaviour of these paths when not trying to interpret them is the same as on Unix. File names that have a tilde without a user name will be correctly substituted using the **$HOME** environment variable, just like for Unix. 


Portability issues
------------------

 Not all file systems are case sensitive, so scripts should avoid code that depends on the case of characters in a file name. In addition, the character sets allowed on different devices may differ, so scripts should choose file names that do not contain special characters like: **<>:?"/\|**. The safest approach is to use names consisting of alphanumeric characters only. Care should be taken with filenames which contain spaces (common on Windows systems) and filenames where the backslash is the directory separator (Windows native path names). Also Windows 3.1 only supports file names with a root of no more than 8 characters and an extension of no more than 3 characters.  On Windows platforms there are file and path length restrictions. Complete paths or filenames longer than about 260 characters will lead to errors in most file operations. 


 Another Windows peculiarity is that any number of trailing dots “.” in filenames are totally ignored, so, for example, attempts to create a file or directory with a name “foo.” will result in the creation of a file/directory with name “foo”. This fact is reflected in the results of **[file normalize](file.htm)**. Furthermore, a file name consisting only of dots “.........” or dots with trailing characters “.....abc” is illegal. 


See also
--------

 **[file](file.htm)**, **[glob](glob.htm)** Copyright © 1995-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/filename.htm>

memory
======

  
[NAME](memory.htm#M2) memory — Control Tcl memory debugging capabilities 
[SYNOPSIS](memory.htm#M3) 
[DESCRIPTION](memory.htm#M4)  
[**memory active** *file*](memory.htm#M5) 
[**memory break\_on\_malloc** *count*](memory.htm#M6) 
[**memory info**](memory.htm#M7) 
[**memory init** [**on**|**off**]](memory.htm#M8) 
[**memory objs** *file*](memory.htm#M9) 
[**memory onexit** *file*](memory.htm#M10) 
[**memory tag** *string*](memory.htm#M11) 
[**memory trace** [**on**|**off**]](memory.htm#M12) 
[**memory trace\_on\_at\_malloc** *count*](memory.htm#M13) 
[**memory validate** [**on**|**off**]](memory.htm#M14) 









 
[SEE ALSO](memory.htm#M15) 
[KEYWORDS](memory.htm#M16) 




 Name
----

 memory — Control Tcl memory debugging capabilities Synopsis
--------

 **memory** *option* ?*arg arg ...*?  
 Description
-----------

 The **memory** command gives the Tcl developer control of Tcl's memory debugging capabilities. The memory command has several suboptions, which are described below. It is only available when Tcl has been compiled with memory debugging enabled (when **TCL\_MEM\_DEBUG** is defined at compile time), and after **[Tcl\_InitMemory](https://www.tcl.tk/man/tcl/TclLib/DumpActiveMemory.htm)** has been called. 
 
**memory active** *file*

 Write a list of all currently allocated memory to the specified *file*. 


**memory break\_on\_malloc** *count*

 After the *count* allocations have been performed, **[ckalloc](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)** outputs a message to this effect and that it is now attempting to enter the C debugger. Tcl will then issue a *SIGINT* signal against itself. If you are running Tcl under a C debugger, it should then enter the debugger command mode. 

**memory info**
 Returns a report containing the total allocations and frees since Tcl began, the current packets allocated (the current number of calls to **[ckalloc](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)** not met by a corresponding call to **[ckfree](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)**), the current bytes allocated, and the maximum number of packets and bytes allocated. 


**memory init** [**on**|**off**]
 Turn on or off the pre-initialization of all allocated memory with bogus bytes. Useful for detecting the use of uninitialized values. 


**memory objs** *file*

 Causes a list of all allocated [Tcl\_Obj](https://www.tcl.tk/man/tcl/TclLib/Object.htm) values to be written to the specified *file* immediately, together with where they were allocated. Useful for checking for leaks of values. 


**memory onexit** *file*

 Causes a list of all allocated memory to be written to the specified *file* during the finalization of Tcl's memory subsystem. Useful for checking that memory is properly cleaned up during process exit. 


**memory tag** *string*

 Each packet of memory allocated by **[ckalloc](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)** can have associated with it a string-valued tag. In the lists of allocated memory generated by **memory active** and **memory onexit**, the tag for each packet is printed along with other information about the packet. The **memory tag** command sets the tag value for subsequent calls to **[ckalloc](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)** to be *string*. 


**memory trace** [**on**|**off**]
 Turns memory tracing on or off. When memory tracing is on, every call to **[ckalloc](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)** causes a line of trace information to be written to *stderr*, consisting of the word *ckalloc*, followed by the address returned, the amount of memory allocated, and the C filename and line number of the code performing the allocation. For example: 

```
ckalloc 40e478 98 tclProc.c 1406
```
 Calls to **[ckfree](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)** are traced in the same manner. 




**memory trace\_on\_at\_malloc** *count*

 Enable memory tracing after *count* **[ckalloc](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)**s have been performed. For example, if you enter **memory trace\_on\_at\_malloc 100**, after the 100th call to **[ckalloc](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)**, memory trace information will begin being displayed for all allocations and frees. Since there can be a lot of memory activity before a problem occurs, judicious use of this option can reduce the slowdown caused by tracing (and the amount of trace information produced), if you can identify a number of allocations that occur before the problem sets in. The current number of memory allocations that have occurred since Tcl started is printed on a guard zone failure. 


**memory validate** [**on**|**off**]
 Turns memory validation on or off. When memory validation is enabled, on every call to **[ckalloc](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)** or **[ckfree](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)**, the guard zones are checked for every piece of memory currently in existence that was allocated by **[ckalloc](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)**. This has a large performance impact and should only be used when overwrite problems are strongly suspected. The advantage of enabling memory validation is that a guard zone overwrite can be detected on the first call to **[ckalloc](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)** or **[ckfree](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)** after the overwrite occurred, rather than when the specific memory with the overwritten guard zone(s) is freed, which may occur long after the overwrite occurred. 

 See also
--------

 **[ckalloc](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)**, **[ckfree](https://www.tcl.tk/man/tcl/TclLib/Alloc.htm)**, **[Tcl\_ValidateAllMemory](https://www.tcl.tk/man/tcl/TclLib/DumpActiveMemory.htm)**, **[Tcl\_DumpActiveMemory](https://www.tcl.tk/man/tcl/TclLib/DumpActiveMemory.htm)**, **TCL\_MEM\_DEBUG** Copyright © 1992-1999 by Karl Lehenbauer and Mark Diekhans  
 Copyright © 2000 by Scriptics Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/memory.htm>

seek
====

 Name
----

 seek — Change the access position for an open channel Synopsis
--------

 **seek** *channelId offset* ?*origin*?  
 Description
-----------

 Changes the current access position for *channelId*.  *ChannelId* must be an identifier for an open channel such as a Tcl standard channel (**[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, or **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**), the return value from an invocation of **[open](open.htm)** or **[socket](socket.htm)**, or the result of a channel creation command provided by a Tcl extension. 


 The *offset* and *origin* arguments specify the position at which the next read or write will occur for *channelId*. *Offset* must be an integer (which may be negative) and *origin* must be one of the following: 


 **start**
 The new access position will be *offset* bytes from the start of the underlying file or device. 

**current**
 The new access position will be *offset* bytes from the current access position; a negative *offset* moves the access position backwards in the underlying file or device. 

**end**
 The new access position will be *offset* bytes from the end of the file or device. A negative *offset* places the access position before the end of file, and a positive *offset* places the access position after the end of file. 

  The *origin* argument defaults to **start**. 


 The command flushes all buffered output for the channel before the command returns, even if the channel is in non-blocking mode. It also discards any buffered and unread input. This command returns an empty string. An error occurs if this command is applied to channels whose underlying file or device does not support seeking. 


 Note that *offset* values are byte offsets, not character offsets. Both **seek** and **[tell](tell.htm)** operate in terms of bytes, not characters, unlike **[read](read.htm)**. 


Examples
--------

 Read a file twice: 

```
set f [open file.txt]
set data1 [read $f]
**seek** $f 0
set data2 [read $f]
close $f
# $data1 eq $data2 if the file wasn't updated
```
  Read the last 10 bytes from a file: 



```
set f [open file.data]
# This is guaranteed to work with binary data but
# may fail with other encodings...
fconfigure $f -translation binary
**seek** $f -10 end
set data [read $f 10]
close $f
```
 See also
--------

 **[file](file.htm)**, **[open](open.htm)**, **[close](close.htm)**, **[gets](gets.htm)**, **[tell](tell.htm)**, **[Tcl\_StandardChannels](https://www.tcl.tk/man/tcl/TclLib/StdChannels.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/seek.htm>

safe
====

  
[NAME](safe.htm#M2) safe — Creating and manipulating safe interpreters 
[SYNOPSIS](safe.htm#M3) 
[OPTIONS](safe.htm#M4) 
[DESCRIPTION](safe.htm#M5) 
[COMMANDS](safe.htm#M6)  
[**::safe::interpCreate** ?*slave*? ?*options...*?](safe.htm#M7) 
[**::safe::interpInit** *slave* ?*options...*?](safe.htm#M8) 
[**::safe::interpConfigure** *slave* ?*options...*?](safe.htm#M9) 
[**::safe::interpDelete** *slave*](safe.htm#M10) 
[**::safe::interpFindInAccessPath** *slave* *directory*](safe.htm#M11) 
[**::safe::interpAddToAccessPath** *slave* *directory*](safe.htm#M12) 
[**::safe::setLogCmd** ?*cmd arg...*?](safe.htm#M13) 






 
[OPTIONS](safe.htm#M14)  
[**-accessPath** *directoryList*](safe.htm#M15) 
[**-statics** *boolean*](safe.htm#M16) 
[**-noStatics**](safe.htm#M17) 
[**-nested** *boolean*](safe.htm#M18) 
[**-nestedLoadOk**](safe.htm#M19) 
[**-deleteHook** *script*](safe.htm#M20) 





 
[ALIASES](safe.htm#M21)  
[**source** *fileName*](safe.htm#M22) 
[**load** *fileName*](safe.htm#M23) 
[**file** ?*subCmd args...*?](safe.htm#M24) 
[**encoding** ?*subCmd args...*?](safe.htm#M25) 
[**exit**](safe.htm#M26) 




 
[SECURITY](safe.htm#M27) 
[SEE ALSO](safe.htm#M28) 
[KEYWORDS](safe.htm#M29) 









 Name
----

 safe — Creating and manipulating safe interpreters Synopsis
--------

 **::safe::interpCreate** ?*slave*? ?*options...*?  
 **::safe::interpInit** *slave* ?*options...*?  
 **::safe::interpConfigure** *slave* ?*options...*?  
 **::safe::interpDelete** *slave*  
 **::safe::interpAddToAccessPath** *slave* *directory*  
 **::safe::interpFindInAccessPath** *slave* *directory*  
 **::safe::setLogCmd** ?*cmd arg...*?  
 ### Options

 ?**-accessPath** *pathList*? ?**-statics** *boolean*? ?**-noStatics**? ?**-nested** *boolean*? ?**-nestedLoadOk**? ?**-deleteHook** *script*? Description
-----------

 Safe Tcl is a mechanism for executing untrusted Tcl scripts safely and for providing mediated access by such scripts to potentially dangerous functionality.  Safe Tcl ensures that untrusted Tcl scripts cannot harm the hosting application. It prevents integrity and privacy attacks. Untrusted Tcl scripts are prevented from corrupting the state of the hosting application or computer. Untrusted scripts are also prevented from disclosing information stored on the hosting computer or in the hosting application to any party. 


 Safe Tcl allows a master interpreter to create safe, restricted interpreters that contain a set of predefined aliases for the **[source](source.htm)**, **[load](load.htm)**, **[file](file.htm)**, **[encoding](encoding.htm)**, and **[exit](exit.htm)** commands and are able to use the auto-loading and package mechanisms. 


 No knowledge of the file system structure is leaked to the safe interpreter, because it has access only to a virtualized path containing tokens. When the safe interpreter requests to source a file, it uses the token in the virtual path as part of the file name to source; the master interpreter transparently translates the token into a real directory name and executes the requested operation (see the section **[SECURITY](#M27)** below for details). Different levels of security can be selected by using the optional flags of the commands described below. 


 All commands provided in the master interpreter by Safe Tcl reside in the **safe** namespace. 


Commands
--------

 The following commands are provided in the master interpreter: 
 
**::safe::interpCreate** ?*slave*? ?*options...*?
 Creates a safe interpreter, installs the aliases described in the section **[ALIASES](#M21)** and initializes the auto-loading and package mechanism as specified by the supplied *options*. See the **[OPTIONS](#M14)** section below for a description of the optional arguments. If the *slave* argument is omitted, a name will be generated. **::safe::interpCreate** always returns the interpreter name. 


**::safe::interpInit** *slave* ?*options...*?
 This command is similar to **interpCreate** except it that does not create the safe interpreter. *slave* must have been created by some other means, like **[interp create](interp.htm)** **-safe**. 


**::safe::interpConfigure** *slave* ?*options...*?
 If no *options* are given, returns the settings for all options for the named safe interpreter as a list of options and their current values for that *slave*. If a single additional argument is provided, it will return a list of 2 elements *name* and *value* where *name* is the full name of that option and *value* the current value for that option and the *slave*. If more than two additional arguments are provided, it will reconfigure the safe interpreter and change each and only the provided options. See the section on **[OPTIONS](#M14)** below for options description. Example of use: 

```
# Create new interp with the same configuration as "$i0":
set i1 [safe::interpCreate {*}[safe::interpConfigure $i0]]

# Get the current deleteHook
set dh [safe::interpConfigure $i0  -del]

# Change (only) the statics loading ok attribute of an
# interp and its deleteHook (leaving the rest unchanged):
safe::interpConfigure $i0  -delete {foo bar} -statics 0
```



**::safe::interpDelete** *slave*

 Deletes the safe interpreter and cleans up the corresponding master interpreter data structures. If a *deleteHook* script was specified for this interpreter it is evaluated before the interpreter is deleted, with the name of the interpreter as an additional argument. 


**::safe::interpFindInAccessPath** *slave* *directory*

 This command finds and returns the token for the real directory *directory* in the safe interpreter's current virtual access path. It generates an error if the directory is not found. Example of use: 

```
$slave eval [list set tk_library \
      [::safe::interpFindInAccessPath $name $tk_library]]
```



**::safe::interpAddToAccessPath** *slave* *directory*

 This command adds *directory* to the virtual path maintained for the safe interpreter in the master, and returns the token that can be used in the safe interpreter to obtain access to files in that directory. If the directory is already in the virtual path, it only returns the token without adding the directory to the virtual path again. Example of use: 

```
$slave eval [list set tk_library \
      [::safe::interpAddToAccessPath $name $tk_library]]
```



**::safe::setLogCmd** ?*cmd arg...*?
 This command installs a script that will be called when interesting life cycle events occur for a safe interpreter. When called with no arguments, it returns the currently installed script. When called with one argument, an empty string, the currently installed script is removed and logging is turned off. The script will be invoked with one additional argument, a string describing the event of interest. The main purpose is to help in debugging safe interpreters. Using this facility you can get complete error messages while the safe interpreter gets only generic error messages. This prevents a safe interpreter from seeing messages about failures and other events that might contain sensitive information such as real directory names.  Example of use: 



```
::safe::setLogCmd puts stderr
```
  Below is the output of a sample session in which a safe interpreter attempted to source a file not found in its virtual access path. Note that the safe interpreter only received an error message saying that the file was not found: 



```
NOTICE for slave interp10 : Created
NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=()
NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)}
ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory
```


 ### Options

 The following options are common to **::safe::interpCreate**, **::safe::interpInit**, and **::safe::interpConfigure**. Any option name can be abbreviated to its minimal non-ambiguous name. Option names are not case sensitive. 
 
**-accessPath** *directoryList*

 This option sets the list of directories from which the safe interpreter can **[source](source.htm)** and **[load](load.htm)** files. If this option is not specified, or if it is given as the empty list, the safe interpreter will use the same directories as its master for auto-loading. See the section **[SECURITY](#M27)** below for more detail about virtual paths, tokens and access control. 


**-statics** *boolean*

 This option specifies if the safe interpreter will be allowed to load statically linked packages (like **load {} Tk**). The default value is **true** : safe interpreters are allowed to load statically linked packages. 

**-noStatics**
 This option is a convenience shortcut for **-statics false** and thus specifies that the safe interpreter will not be allowed to load statically linked packages. 


**-nested** *boolean*

 This option specifies if the safe interpreter will be allowed to load packages into its own sub-interpreters. The default value is **false** : safe interpreters are not allowed to load packages into their own sub-interpreters. 

**-nestedLoadOk**
 This option is a convenience shortcut for **-nested true** and thus specifies the safe interpreter will be allowed to load packages into its own sub-interpreters. 


**-deleteHook** *script*

 When this option is given a non-empty *script*, it will be evaluated in the master with the name of the safe interpreter as an additional argument just before actually deleting the safe interpreter. Giving an empty value removes any currently installed deletion hook script for that safe interpreter. The default value (**{}**) is not to have any deletion call back. 

 Aliases
-------

 The following aliases are provided in a safe interpreter: 
 
**source** *fileName*

 The requested file, a Tcl source file, is sourced into the safe interpreter if it is found. The **[source](source.htm)** alias can only source files from directories in the virtual path for the safe interpreter. The **[source](source.htm)** alias requires the safe interpreter to use one of the token names in its virtual path to denote the directory in which the file to be sourced can be found. See the section on **[SECURITY](#M27)** for more discussion of restrictions on valid filenames. 


**load** *fileName*

 The requested file, a shared object file, is dynamically loaded into the safe interpreter if it is found. The filename must contain a token name mentioned in the virtual path for the safe interpreter for it to be found successfully. Additionally, the shared object file must contain a safe entry point; see the manual page for the **[load](load.htm)** command for more details. 


**file** ?*subCmd args...*?
 The **[file](file.htm)** alias provides access to a safe subset of the subcommands of the **[file](file.htm)** command; it allows only **dirname**, **join**, **extension**, **root**, **tail**, **pathname** and **split** subcommands. For more details on what these subcommands do see the manual page for the **[file](file.htm)** command. 


**encoding** ?*subCmd args...*?
 The **[encoding](encoding.htm)** alias provides access to a safe subset of the subcommands of the **[encoding](encoding.htm)** command; it disallows setting of the system encoding, but allows all other subcommands including **system** to check the current encoding. 

**exit**
 The calling interpreter is deleted and its computation is stopped, but the Tcl process in which this interpreter exists is not terminated. 

 Security
--------

 Safe Tcl does not attempt to completely prevent annoyance and denial of service attacks. These forms of attack prevent the application or user from temporarily using the computer to perform useful work, for example by consuming all available CPU time or all available screen real estate. These attacks, while aggravating, are deemed to be of lesser importance in general than integrity and privacy attacks that Safe Tcl is to prevent.  The commands available in a safe interpreter, in addition to the safe set as defined in **[interp](interp.htm)** manual page, are mediated aliases for **[source](source.htm)**, **[load](load.htm)**, **[exit](exit.htm)**, and safe subsets of **[file](file.htm)** and **[encoding](encoding.htm)**. The safe interpreter can also auto-load code and it can request that packages be loaded. 


 Because some of these commands access the local file system, there is a potential for information leakage about its directory structure. To prevent this, commands that take file names as arguments in a safe interpreter use tokens instead of the real directory names. These tokens are translated to the real directory name while a request to, e.g., source a file is mediated by the master interpreter. This virtual path system is maintained in the master interpreter for each safe interpreter created by **::safe::interpCreate** or initialized by **::safe::interpInit** and the path maps tokens accessible in the safe interpreter into real path names on the local file system thus preventing safe interpreters from gaining knowledge about the structure of the file system of the host on which the interpreter is executing. The only valid file names arguments for the **[source](source.htm)** and **[load](load.htm)** aliases provided to the slave are path in the form of **[file join** *token filename***]** (i.e. when using the native file path formats: *token***/***filename* on Unix and *token***\***filename* on Windows), where *token* is representing one of the directories of the *accessPath* list and *filename* is one file in that directory (no sub directories access are allowed). 


 When a token is used in a safe interpreter in a request to source or load a file, the token is checked and translated to a real path name and the file to be sourced or loaded is located on the file system. The safe interpreter never gains knowledge of the actual path name under which the file is stored on the file system. 


 To further prevent potential information leakage from sensitive files that are accidentally included in the set of files that can be sourced by a safe interpreter, the **[source](source.htm)** alias restricts access to files meeting the following constraints: the file name must fourteen characters or shorter, must not contain more than one dot (“**.**”), must end up with the extension (“**.tcl**”) or be called (“**tclIndex**”.) 


 Each element of the initial access path list will be assigned a token that will be set in the slave **[auto\_path](tclvars.htm)** and the first element of that list will be set as the **[tcl\_library](tclvars.htm)** for that slave. 


 If the access path argument is not given or is the empty list, the default behavior is to let the slave access the same packages as the master has access to (Or to be more precise: only packages written in Tcl (which by definition cannot be dangerous as they run in the slave interpreter) and C extensions that provides a \_SafeInit entry point). For that purpose, the master's **[auto\_path](tclvars.htm)** will be used to construct the slave access path. In order that the slave successfully loads the Tcl library files (which includes the auto-loading mechanism itself) the **[tcl\_library](tclvars.htm)** will be added or moved to the first position if necessary, in the slave access path, so the slave **[tcl\_library](tclvars.htm)** will be the same as the master's (its real path will still be invisible to the slave though). In order that auto-loading works the same for the slave and the master in this by default case, the first-level sub directories of each directory in the master **[auto\_path](tclvars.htm)** will also be added (if not already included) to the slave access path. You can always specify a more restrictive path for which sub directories will never be searched by explicitly specifying your directory list with the **-accessPath** flag instead of relying on this default mechanism. 


 When the *accessPath* is changed after the first creation or initialization (i.e. through **interpConfigure -accessPath** *list*), an **[auto\_reset](library.htm)** is automatically evaluated in the safe interpreter to synchronize its **auto\_index** with the new token list. 


See also
--------

 **[interp](interp.htm)**, **[library](library.htm)**, **[load](load.htm)**, **[package](package.htm)**, **[source](source.htm)**, **[unknown](unknown.htm)** [safe interpreter](#), Copyright © 1995-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/safe.htm>

scan
====

  
[NAME](scan.htm#M2) scan — Parse string using conversion specifiers in the style of sscanf 
[SYNOPSIS](scan.htm#M3) 
[INTRODUCTION](scan.htm#M4) 
[DETAILS ON SCANNING](scan.htm#M5) 
[OPTIONAL POSITIONAL SPECIFIER](scan.htm#M6) 
[OPTIONAL SIZE MODIFIER](scan.htm#M7) 
[MANDATORY CONVERSION CHARACTER](scan.htm#M8)  
[**d**](scan.htm#M9) 
[**o**](scan.htm#M10) 
[**x** or **X**](scan.htm#M11) 
[**b**](scan.htm#M12) 
[**u**](scan.htm#M13) 
[**i**](scan.htm#M14) 
[**c**](scan.htm#M15) 
[**s**](scan.htm#M16) 
[**e** or **f** or **g** or **E** or **G**](scan.htm#M17) 
[**[***chars***]**](scan.htm#M18) 
[**[^***chars***]**](scan.htm#M19) 
[**n**](scan.htm#M20) 











 
[DIFFERENCES FROM ANSI SSCANF](scan.htm#M21) 
[EXAMPLES](scan.htm#M22) 
[SEE ALSO](scan.htm#M23) 
[KEYWORDS](scan.htm#M24) 










 Name
----

 scan — Parse string using conversion specifiers in the style of sscanf Synopsis
--------

 **scan** *string format* ?*varName varName ...*?  
 Introduction
------------

 This command parses substrings from an input string in a fashion similar to the ANSI C **sscanf** procedure and returns a count of the number of conversions performed, or -1 if the end of the input string is reached before any conversions have been performed. *String* gives the input to be parsed and *format* indicates how to parse it, using **%** conversion specifiers as in **sscanf**. Each *varName* gives the name of a variable; when a substring is scanned from *string* that matches a conversion specifier, the substring is assigned to the corresponding variable. If no *varName* variables are specified, then **scan** works in an inline manner, returning the data that would otherwise be stored in the variables as a list. In the inline case, an empty string is returned when the end of the input string is reached before any conversions have been performed. Details on scanning
-------------------

 **Scan** operates by scanning *string* and *format* together. If the next character in *format* is a blank or tab then it matches any number of white space characters in *string* (including zero). Otherwise, if it is not a **%** character then it must match the next character of *string*. When a **%** is encountered in *format*, it indicates the start of a conversion specifier. A conversion specifier contains up to four fields after the **%**: a XPG3 position specifier (or a **\*** to indicate the converted value is to be discarded instead of assigned to any variable); a number indicating a maximum substring width; a size modifier; and a conversion character. All of these fields are optional except for the conversion character. The fields that are present must appear in the order given above.  When **scan** finds a conversion specifier in *format*, it first skips any white-space characters in *string* (unless the conversion character is **[** or **c**). Then it converts the next input characters according to the conversion specifier and stores the result in the variable given by the next argument to **scan**. 


### Optional positional specifier

 If the **%** is followed by a decimal number and a **$**, as in “**%2$d**”, then the variable to use is not taken from the next sequential argument. Instead, it is taken from the argument indicated by the number, where 1 corresponds to the first *varName*. If there are any positional specifiers in *format* then all of the specifiers must be positional. Every *varName* on the argument list must correspond to exactly one conversion specifier or an error is generated, or in the inline case, any position can be specified at most once and the empty positions will be filled in with empty strings. ### Optional size modifier

 The size modifier field is used only when scanning a substring into one of Tcl's integer values. The size modifier field dictates the integer range acceptable to be stored in a variable, or, for the inline case, in a position in the result list. The syntactically valid values for the size modifier are **h**, **L**, **l**, and **ll**. The **h** size modifier value is equivalent to the absence of a size modifier in the the conversion specifier. Either one indicates the integer range to be stored is limited to the same range produced by the **[int()](mathfunc.htm)** function of the **[expr](expr.htm)** command. The **L** size modifier is equivalent to the **l** size modifier. Either one indicates the integer range to be stored is limited to the same range produced by the **[wide()](mathfunc.htm)** function of the **[expr](expr.htm)** command. The **ll** size modifier indicates that the integer range to be stored is unlimited. ### Mandatory conversion character

 The following conversion characters are supported: 
 **d**
 The input substring must be a decimal integer. It is read in and the integer value is stored in the variable, truncated as required by the size modifier value. 

**o**
 The input substring must be an octal integer. It is read in and the integer value is stored in the variable, truncated as required by the size modifier value. 


**x** or **X**

 The input substring must be a hexadecimal integer. It is read in and the integer value is stored in the variable, truncated as required by the size modifier value. 

**b**
 The input substring must be a binary integer. It is read in and the integer value is stored in the variable, truncated as required by the size modifier value. 

**u**
 The input substring must be a decimal integer. The integer value is truncated as required by the size modifier value, and the corresponding unsigned value for that truncated range is computed and stored in the variable as a decimal string. The conversion makes no sense without reference to a truncation range, so the size modifier **ll** is not permitted in combination with conversion character **u**. 

**i**
 The input substring must be an integer. The base (i.e. decimal, binary, octal, or hexadecimal) is determined in the same fashion as described in **[expr](expr.htm)**. The integer value is stored in the variable, truncated as required by the size modifier value. 

**c**
 A single character is read in and its Unicode value is stored in the variable as an integer value. Initial white space is not skipped in this case, so the input substring may be a white-space character. 

**s**
 The input substring consists of all the characters up to the next white-space character; the characters are copied to the variable. 


**e** or **f** or **g** or **E** or **G**

 The input substring must be a floating-point number consisting of an optional sign, a string of decimal digits possibly containing a decimal point, and an optional exponent consisting of an **e** or **E** followed by an optional sign and a string of decimal digits. It is read in and stored in the variable as a floating-point value. 


**[***chars***]**

 The input substring consists of one or more characters in *chars*. The matching string is stored in the variable. If the first character between the brackets is a **]** then it is treated as part of *chars* rather than the closing bracket for the set. If *chars* contains a sequence of the form *a***-***b* then any character between *a* and *b* (inclusive) will match. If the first or last character between the brackets is a **-**, then it is treated as part of *chars* rather than indicating a range. 


**[^***chars***]**

 The input substring consists of one or more characters not in *chars*. The matching string is stored in the variable. If the character immediately following the **^** is a **]** then it is treated as part of the set rather than the closing bracket for the set. If *chars* contains a sequence of the form *a***-***b* then any character between *a* and *b* (inclusive) will be excluded from the set. If the first or last character between the brackets is a **-**, then it is treated as part of *chars* rather than indicating a range value. 

**n**
 No input is consumed from the input string. Instead, the total number of characters scanned from the input string so far is stored in the variable. 

  The number of characters read from the input for a conversion is the largest number that makes sense for that particular conversion (e.g. as many decimal digits as possible for **%d**, as many octal digits as possible for **%o**, and so on). The input substring for a given conversion terminates either when a white-space character is encountered or when the maximum substring width has been reached, whichever comes first. If a **\*** is present in the conversion specifier then no variable is assigned and the next scan argument is not consumed. 


Differences from ansi sscanf
----------------------------

 The behavior of the **scan** command is the same as the behavior of the ANSI C **sscanf** procedure except for the following differences: 
1. **%p** conversion specifier is not supported.
2. For **%c** conversions a single character value is converted to a decimal string, which is then assigned to the corresponding *varName*; no substring width may be specified for this conversion.
3. The **h** modifier is always ignored and the **l** and **L** modifiers are ignored when converting real values (i.e. type **double** is used for the internal representation). The **ll** modifier has no **sscanf** counterpart.
4. If the end of the input string is reached before any conversions have been performed and no variables are given, an empty string is returned.

 Examples
--------

 Convert a UNICODE character to its numeric value: 

```
set char "x"
set value [**scan** $char %c]
```
  Parse a simple color specification of the form *#RRGGBB* using hexadecimal conversions with substring sizes: 



```
set string "#08D03F"
**scan** $string "#%2x%2x%2x" r g b
```
  Parse a *HH:MM* time string, noting that this avoids problems with octal numbers by forcing interpretation as decimals (if we did not care, we would use the **%i** conversion instead): 



```
set string "08:08"   ;# *Not* octal!
if {[**scan** $string "%d:%d" hours minutes] != 2} {
    error "not a valid time string"
}
# We have to understand numeric ranges ourselves...
if {$minutes < 0 || $minutes > 59} {
    error "invalid number of minutes"
}
```
  Break a string up into sequences of non-whitespace characters (note the use of the **%n** conversion so that we get skipping over leading whitespace correct): 



```
set string " a string {with braced words} + leading space "
set words {}
while {[**scan** $string %s%n word length] == 2} {
    lappend words $word
    set string [string range $string $length end]
}
```
  Parse a simple coordinate string, checking that it is complete by looking for the terminating character explicitly: 



```
set string "(5.2,-4e-2)"
# Note that the spaces before the literal parts of
# the scan pattern are significant, and that ")" is
# the Unicode character \u0029
if {
    [**scan** $string " (%f ,%f %c" x y last] != 3
    || $last != 0x0029
} then {
    error "invalid coordinate string"
}
puts "X=$x, Y=$y"
```
  An interactive session demonstrating the truncation of integer values determined by size modifiers: 



```
*%* set tcl_platform(wordSize)
4
*%* scan 20000000000000000000 %d
2147483647
*%* scan 20000000000000000000 %ld
9223372036854775807
*%* scan 20000000000000000000 %lld
20000000000000000000
```
 See also
--------

 **[format](format.htm)**, **sscanf** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2000 Scriptics Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/scan.htm>

self
====

  
[NAME](self.htm#M2) self — method call internal introspection 
[SYNOPSIS](self.htm#M3) 
[DESCRIPTION](self.htm#M4)  
[**self call**](self.htm#M5) 
[**self caller**](self.htm#M6) 
[**self class**](self.htm#M7) 
[**self filter**](self.htm#M8) 
[**self method**](self.htm#M9) 
[**self namespace**](self.htm#M10) 
[**self next**](self.htm#M11) 
[**self object**](self.htm#M12) 
[**self target**](self.htm#M13) 








 
[EXAMPLES](self.htm#M14) 
[SEE ALSO](self.htm#M15) 
[KEYWORDS](self.htm#M16) 





 Name
----

 self — method call internal introspection Synopsis
--------

 package require TclOO  
   
 **self** ?*subcommand*?  
 Description
-----------

 The **self** command, which should only be used from within the context of a call to a method (i.e. inside a method, constructor or destructor body) is used to allow the method to discover information about how it was called. It takes an argument, *subcommand*, that tells it what sort of information is actually desired; if omitted the result will be the same as if **self object** was invoked. The supported subcommands are: 
 **self call**
 This returns a two-element list describing the method implementations used to implement the current call chain. The first element is the same as would be reported by **[info object](info.htm)** **call** for the current method (except that this also reports useful values from within constructors and destructors, whose names are reported as **<constructor>** and **<destructor>** respectively), and the second element is an index into the first element's list that indicates which actual implementation is currently executing (the first implementation to execute is always at index 0). 

**self caller**
 When the method was invoked from inside another object method, this subcommand returns a three element list describing the containing object and method. The first element describes the declaring object or class of the method, the second element is the name of the object on which the containing method was invoked, and the third element is the name of the method (with the strings **<constructor>** and **<destructor>** indicating constructors and destructors respectively). 

**self class**
 This returns the name of the class that the current method was defined within. Note that this will change as the chain of method implementations is traversed with **[next](next.htm)**, and that if the method was defined on an object then this will fail.  If you want the class of the current object, you need to use this other construct: 



```
info object class [**self object**]
```


**self filter**
 When invoked inside a filter, this subcommand returns a three element list describing the filter. The first element gives the name of the object or class that declared the filter (note that this may be different from the object or class that provided the implementation of the filter), the second element is either **object** or **class** depending on whether the declaring entity was an object or class, and the third element is the name of the filter. 

**self method**
 This returns the name of the current method (with the strings **<constructor>** and **<destructor>** indicating constructors and destructors respectively). 

**self namespace**
 This returns the name of the unique namespace of the object that the method was invoked upon. 

**self next**
 When invoked from a method that is not at the end of a call chain (i.e. where the **[next](next.htm)** command will invoke an actual method implementation), this subcommand returns a two element list describing the next element in the method call chain; the first element is the name of the class or object that declares the next part of the call chain, and the second element is the name of the method (with the strings **<constructor>** and **<destructor>** indicating constructors and destructors respectively). If invoked from a method that is at the end of a call chain, this subcommand returns the empty string. 

**self object**
 This returns the name of the object that the method was invoked upon. 

**self target**
 When invoked inside a filter implementation, this subcommand returns a two element list describing the method being filtered. The first element will be the name of the declarer of the method, and the second element will be the actual name of the method. 

 Examples
--------

 This example shows basic use of **self** to provide information about the current object: 

```
oo::class create c {
    method foo {} {
        puts "this is the [**self**] object"
    }
}
c create a
c create b
a foo                *→ prints "this is the ::a object"*
b foo                *→ prints "this is the ::b object"*
```
  This demonstrates what a method call chain looks like, and how traversing along it changes the index into it: 



```
oo::class create c {
    method x {} {
        puts "Cls: [**self call**]"
    }
}
c create a
oo::objdefine a {
    method x {} {
        puts "Obj: [**self call**]"
        next
        puts "Obj: [**self call**]"
    }
}
a x     *→ Obj: {{method x object method} {method x ::c method}} 0*
        *→ Cls: {{method x object method} {method x ::c method}} 1*
        *→ Obj: {{method x object method} {method x ::c method}} 0*
```
 See also
--------

 **[info](info.htm)**, **[next](next.htm)** Copyright © 2007 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/self.htm>

my
==

 Name
----

 my — invoke any method of current object Synopsis
--------

 package require TclOO  
   
 **my** *methodName* ?*arg ...*?  
 Description
-----------

 The **my** command is used to allow methods of objects to invoke any method of the object (or its class). In particular, the set of valid values for *methodName* is the set of all methods supported by an object and its superclasses, including those that are not exported. The object upon which the method is invoked is always the one that is the current context of the method (i.e. the object that is returned by **[self object](self.htm)**) from which the **my** command is invoked.  Each object has its own **my** command, contained in its instance namespace. 


Examples
--------

 This example shows basic use of **my** to use the **variables** method of the **[oo::object](object.htm)** class, which is not publicly visible by default: 

```
oo::class create c {
    method count {} {
        **my** variable counter
        puts [incr counter]
    }
}
c create o
o count              *→ prints "1"*
o count              *→ prints "2"*
o count              *→ prints "3"*
```
 See also
--------

 **[next](next.htm)**, **[oo::object](object.htm)**, **[self](self.htm)** Copyright © 2007 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/my.htm>

file
====

  
[NAME](file.htm#M2) file — Manipulate file names and attributes 
[SYNOPSIS](file.htm#M3) 
[DESCRIPTION](file.htm#M4)  
[**file atime** *name* ?*time*?](file.htm#M5) 
[**file attributes** *name*](file.htm#M6) 
[**file attributes** *name* ?*option*?](file.htm#M7) 
[**file attributes** *name* ?*option value option value...*?](file.htm#M8) 
[**file channels** ?*pattern*?](file.htm#M9) 
[**file copy** ?**-force**? ?**--**? *source* *target*](file.htm#M10) 
[**file copy** ?**-force**? ?**--**? *source* ?*source* ...? *targetDir*](file.htm#M11) 
[**file delete** ?**-force**? ?**--**? ?*pathname* ... ?](file.htm#M12) 
[**file dirname** *name*](file.htm#M13) 
[**file executable** *name*](file.htm#M14) 
[**file exists** *name*](file.htm#M15) 
[**file extension** *name*](file.htm#M16) 
[**file isdirectory** *name*](file.htm#M17) 
[**file isfile** *name*](file.htm#M18) 
[**file join** *name* ?*name ...*?](file.htm#M19) 
[**file link** ?*-linktype*? *linkName* ?*target*?](file.htm#M20) 
[**file lstat** *name varName*](file.htm#M21) 
[**file mkdir** ?*dir* ...?](file.htm#M22) 
[**file mtime** *name* ?*time*?](file.htm#M23) 
[**file nativename** *name*](file.htm#M24) 
[**file normalize** *name*](file.htm#M25) 
[**file owned** *name*](file.htm#M26) 
[**file pathtype** *name*](file.htm#M27) 
[**file readable** *name*](file.htm#M28) 
[**file readlink** *name*](file.htm#M29) 
[**file rename** ?**-force**? ?**--**? *source* *target*](file.htm#M30) 
[**file rename** ?**-force**? ?**--**? *source* ?*source* ...? *targetDir*](file.htm#M31) 
[**file rootname** *name*](file.htm#M32) 
[**file separator** ?*name*?](file.htm#M33) 
[**file size** *name*](file.htm#M34) 
[**file split** *name*](file.htm#M35) 
[**file stat** *name varName*](file.htm#M36) 
[**file system** *name*](file.htm#M37) 
[**file tail** *name*](file.htm#M38) 
[**file tempfile** ?*nameVar*? ?*template*?](file.htm#M39) 
[**file type** *name*](file.htm#M40) 
[**file volumes**](file.htm#M41) 
[**file writable** *name*](file.htm#M42) 





































 
[PORTABILITY ISSUES](file.htm#M43)  
[**Unix**](file.htm#M44) 
[**Windows**](file.htm#M45) 

 
[EXAMPLES](file.htm#M46) 
[SEE ALSO](file.htm#M47) 
[KEYWORDS](file.htm#M48) 






 Name
----

 file — Manipulate file names and attributes Synopsis
--------

 **file** *option* *name* ?*arg arg ...*?  
 Description
-----------

 This command provides several operations on a file's name or attributes. *Name* is the name of a file; if it starts with a tilde, then tilde substitution is done before executing the command (see the manual entry for **[filename](filename.htm)** for details). *Option* indicates what to do with the file name. Any unique abbreviation for *option* is acceptable. The valid options are: 
 
**file atime** *name* ?*time*?
 Returns a decimal string giving the time at which file *name* was last accessed. If *time* is specified, it is an access time to set for the file. The time is measured in the standard POSIX fashion as seconds from a fixed starting time (often January 1, 1970). If the file does not exist or its access time cannot be queried or set then an error is generated. On Windows, FAT file systems do not support access time. 


**file attributes** *name*


**file attributes** *name* ?*option*?

**file attributes** *name* ?*option value option value...*?
 This subcommand returns or sets platform specific values associated with a file. The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows:  On Unix, **-group** gets or sets the group name for the file. A group id can be given to the command, but it returns a group name. **-owner** gets or sets the user name of the owner of the file. The command returns the owner name, but the numerical id can be passed when setting the owner. **-permissions** sets or retrieves the octal code that chmod(1) uses. This command does also has limited support for setting using the symbolic attributes for chmod(1), of the form [ugo]?[[+-=][rwxst],[...]], where multiple symbolic attributes can be separated by commas (example: **u+s,go-rw** add sticky bit for user, remove read and write permissions for group and other). A simplified **ls** style string, of the form rwxrwxrwx (must be 9 characters), is also supported (example: **rwxr-xr-t** is equivalent to 01755). On versions of Unix supporting file flags, **-readonly** gives the value or sets or clears the readonly attribute of the file, i.e. the user immutable flag **uchg** to chflags(1). 


 On Windows, **-archive** gives the value or sets or clears the archive attribute of the file. **-hidden** gives the value or sets or clears the hidden attribute of the file. **-longname** will expand each path element to its long version. This attribute cannot be set. **-readonly** gives the value or sets or clears the readonly attribute of the file. **-shortname** gives a string where every path element is replaced with its short (8.3) version of the name. This attribute cannot be set. **-system** gives or sets or clears the value of the system attribute of the file. 


On Mac OS X and Darwin, **-creator** gives or sets the Finder creator type of the file. **-hidden** gives or sets or clears the hidden attribute of the file. **-readonly** gives or sets or clears the readonly attribute of the file. **-rsrclength** gives the length of the resource fork of the file, this attribute can only be set to the value 0, which results in the resource fork being stripped off the file. 




**file channels** ?*pattern*?
 If *pattern* is not specified, returns a list of names of all registered open channels in this interpreter. If *pattern* is specified, only those names matching *pattern* are returned. Matching is determined using the same rules as for **[string match](string.htm)**. 


**file copy** ?**-force**? ?**--**? *source* *target*


**file copy** ?**-force**? ?**--**? *source* ?*source* ...? *targetDir*

 The first form makes a copy of the file or directory *source* under the pathname *target*. If *target* is an existing directory, then the second form is used. The second form makes a copy inside *targetDir* of each *source* file listed. If a directory is specified as a *source*, then the contents of the directory will be recursively copied into *targetDir*. Existing files will not be overwritten unless the **-force** option is specified (when Tcl will also attempt to adjust permissions on the destination file or directory if that is necessary to allow the copy to proceed). When copying within a single filesystem, *file copy* will copy soft links (i.e. the links themselves are copied, not the things they point to). Trying to overwrite a non-empty directory, overwrite a directory with a file, or overwrite a file with a directory will all result in errors even if **-force** was specified. Arguments are processed in the order specified, halting at the first error, if any. A **--** marks the end of switches; the argument following the **--** will be treated as a *source* even if it starts with a **-**. 


**file delete** ?**-force**? ?**--**? ?*pathname* ... ?
 Removes the file or directory specified by each *pathname* argument. Non-empty directories will be removed only if the **-force** option is specified. When operating on symbolic links, the links themselves will be deleted, not the objects they point to. Trying to delete a non-existent file is not considered an error. Trying to delete a read-only file will cause the file to be deleted, even if the **-force** flags is not specified. If the **-force** option is specified on a directory, Tcl will attempt both to change permissions and move the current directory “pwd” out of the given path if that is necessary to allow the deletion to proceed. Arguments are processed in the order specified, halting at the first error, if any. A **--** marks the end of switches; the argument following the **--** will be treated as a *pathname* even if it starts with a **-**. 


**file dirname** *name*

 Returns a name comprised of all of the path components in *name* excluding the last element. If *name* is a relative file name and only contains one path element, then returns “**.**”. If *name* refers to a root directory, then the root directory is returned. For example, 

```
**file dirname** c:/
```
  returns **c:/**. 


 Note that tilde substitution will only be performed if it is necessary to complete the command. For example, 



```
**file dirname** ~/src/foo.c
```
  returns **~/src**, whereas 



```
**file dirname** ~
```
 returns **/home** (or something similar). 




**file executable** *name*

 Returns **1** if file *name* is executable by the current user, **0** otherwise. On Windows, which does not have an executable attribute, the command treats all directories and any files with extensions **exe**, **com**, **cmd** or **bat** as executable. 


**file exists** *name*

 Returns **1** if file *name* exists and the current user has search privileges for the directories leading to it, **0** otherwise. 


**file extension** *name*

 Returns all of the characters in *name* after and including the last dot in the last element of *name*. If there is no dot in the last element of *name* then returns the empty string. 


**file isdirectory** *name*

 Returns **1** if file *name* is a directory, **0** otherwise. 


**file isfile** *name*

 Returns **1** if file *name* is a regular file, **0** otherwise. 


**file join** *name* ?*name ...*?
 Takes one or more file names and combines them, using the correct path separator for the current platform. If a particular *name* is relative, then it will be joined to the previous file name argument. Otherwise, any earlier arguments will be discarded, and joining will proceed from the current argument. For example, 

```
**file join** a b /foo bar
```
  returns **/foo/bar**. 


Note that any of the names can contain separators, and that the result is always canonical for the current platform: **/** for Unix and Windows. 




**file link** ?*-linktype*? *linkName* ?*target*?
 If only one argument is given, that argument is assumed to be *linkName*, and this command returns the value of the link given by *linkName* (i.e. the name of the file it points to). If *linkName* is not a link or its value cannot be read (as, for example, seems to be the case with hard links, which look just like ordinary files), then an error is returned.  If 2 arguments are given, then these are assumed to be *linkName* and *target*. If *linkName* already exists, or if *target* does not exist, an error will be returned. Otherwise, Tcl creates a new link called *linkName* which points to the existing filesystem object at *target* (which is also the returned value), where the type of the link is platform-specific (on Unix a symbolic link will be the default). This is useful for the case where the user wishes to create a link in a cross-platform way, and does not care what type of link is created. 


 If the user wishes to make a link of a specific type only, (and signal an error if for some reason that is not possible), then the optional *-linktype* argument should be given. Accepted values for *-linktype* are “**-symbolic**” and “**-hard**”. 


On Unix, symbolic links can be made to relative paths, and those paths must be relative to the actual *linkName*'s location (not to the cwd), but on all other platforms where relative links are not supported, target paths will always be converted to absolute, normalized form before the link is created (and therefore relative paths are interpreted as relative to the cwd). Furthermore, “~user” paths are always expanded to absolute form. When creating links on filesystems that either do not support any links, or do not support the specific type requested, an error message will be returned. Most Unix platforms support both symbolic and hard links (the latter for files only). Windows supports symbolic directory links and hard file links on NTFS drives. 




**file lstat** *name varName*

 Same as **stat** option (see below) except uses the *lstat* kernel call instead of *stat*. This means that if *name* refers to a symbolic link the information returned in *varName* is for the link rather than the file it refers to. On systems that do not support symbolic links this option behaves exactly the same as the **stat** option. 


**file mkdir** ?*dir* ...?
 Creates each directory specified. For each pathname *dir* specified, this command will create all non-existing parent directories as well as *dir* itself. If an existing directory is specified, then no action is taken and no error is returned. Trying to overwrite an existing file with a directory will result in an error. Arguments are processed in the order specified, halting at the first error, if any. 


**file mtime** *name* ?*time*?
 Returns a decimal string giving the time at which file *name* was last modified. If *time* is specified, it is a modification time to set for the file (equivalent to Unix **touch**). The time is measured in the standard POSIX fashion as seconds from a fixed starting time (often January 1, 1970). If the file does not exist or its modified time cannot be queried or set then an error is generated. 


**file nativename** *name*

 Returns the platform-specific name of the file. This is useful if the filename is needed to pass to a platform-specific call, such as to a subprocess via **[exec](exec.htm)** under Windows (see **[EXAMPLES](#M46)** below). 


**file normalize** *name*

 Returns a unique normalized path representation for the file-system object (file, directory, link, etc), whose string value can be used as a unique identifier for it. A normalized path is an absolute path which has all “../” and “./” removed. Also it is one which is in the “standard” format for the native platform. On Unix, this means the segments leading up to the path must be free of symbolic links/aliases (but the very last path component may be a symbolic link), and on Windows it also means we want the long form with that form's case-dependence (which gives us a unique, case-dependent path). The one exception concerning the last link in the path is necessary, because Tcl or the user may wish to operate on the actual symbolic link itself (for example **file delete**, **file rename**, **file copy** are defined to operate on symbolic links, not on the things that they point to). 


**file owned** *name*

 Returns **1** if file *name* is owned by the current user, **0** otherwise. 


**file pathtype** *name*

 Returns one of **absolute**, **relative**, **volumerelative**. If *name* refers to a specific file on a specific volume, the path type will be **absolute**. If *name* refers to a file relative to the current working directory, then the path type will be **relative**. If *name* refers to a file relative to the current working directory on a specified volume, or to a specific file on the current working volume, then the path type is **volumerelative**. 


**file readable** *name*

 Returns **1** if file *name* is readable by the current user, **0** otherwise. 


**file readlink** *name*

 Returns the value of the symbolic link given by *name* (i.e. the name of the file it points to). If *name* is not a symbolic link or its value cannot be read, then an error is returned. On systems that do not support symbolic links this option is undefined. 


**file rename** ?**-force**? ?**--**? *source* *target*


**file rename** ?**-force**? ?**--**? *source* ?*source* ...? *targetDir*

 The first form takes the file or directory specified by pathname *source* and renames it to *target*, moving the file if the pathname *target* specifies a name in a different directory. If *target* is an existing directory, then the second form is used. The second form moves each *source* file or directory into the directory *targetDir*. Existing files will not be overwritten unless the **-force** option is specified. When operating inside a single filesystem, Tcl will rename symbolic links rather than the things that they point to. Trying to overwrite a non-empty directory, overwrite a directory with a file, or a file with a directory will all result in errors. Arguments are processed in the order specified, halting at the first error, if any. A **--** marks the end of switches; the argument following the **--** will be treated as a *source* even if it starts with a **-**. 


**file rootname** *name*

 Returns all of the characters in *name* up to but not including the last “.” character in the last component of name. If the last component of *name* does not contain a dot, then returns *name*. 


**file separator** ?*name*?
 If no argument is given, returns the character which is used to separate path segments for native files on this platform. If a path is given, the filesystem responsible for that path is asked to return its separator character. If no file system accepts *name*, an error is generated. 


**file size** *name*

 Returns a decimal string giving the size of file *name* in bytes. If the file does not exist or its size cannot be queried then an error is generated. 


**file split** *name*

 Returns a list whose elements are the path components in *name*. The first element of the list will have the same path type as *name*. All other elements will be relative. Path separators will be discarded unless they are needed to ensure that an element is unambiguously relative. For example, under Unix 

```
**file split** /foo/~bar/baz
```
 returns “**/ foo ./~bar baz**” to ensure that later commands that use the third component do not attempt to perform tilde substitution. 




**file stat** *name varName*

 Invokes the **stat** kernel call on *name*, and uses the variable given by *varName* to hold information returned from the kernel call. *VarName* is treated as an array variable, and the following elements of that variable are set: **atime**, **ctime**, **dev**, **gid**, **ino**, **mode**, **mtime**, **nlink**, **size**, **type**, **uid**. Each element except **type** is a decimal string with the value of the corresponding field from the **stat** return structure; see the manual entry for **stat** for details on the meanings of the values. The **type** element gives the type of the file in the same form returned by the command **file type**. This command returns an empty string. 


**file system** *name*

 Returns a list of one or two elements, the first of which is the name of the filesystem to use for the file, and the second, if given, an arbitrary string representing the filesystem-specific nature or type of the location within that filesystem. If a filesystem only supports one type of file, the second element may not be supplied. For example the native files have a first element “native”, and a second element which when given is a platform-specific type name for the file's system (e.g. “NTFS”, “FAT”, on Windows). A generic virtual file system might return the list “vfs ftp” to represent a file on a remote ftp site mounted as a virtual filesystem through an extension called “vfs”. If the file does not belong to any filesystem, an error is generated. 


**file tail** *name*

 Returns all of the characters in the last filesystem component of *name*. Any trailing directory separator in *name* is ignored. If *name* contains no separators then returns *name*. So, **file tail a/b**, **file tail a/b/** and **file tail b** all return **b**. 


**file tempfile** ?*nameVar*? ?*template*?
 Creates a temporary file and returns a read-write channel opened on that file. If the *nameVar* is given, it specifies a variable that the name of the temporary file will be written into; if absent, Tcl will attempt to arrange for the temporary file to be deleted once it is no longer required. If the *template* is present, it specifies parts of the template of the filename to use when creating it (such as the directory, base-name or extension) though some platforms may ignore some or all of these parts and use a built-in default instead.  Note that temporary files are *only* ever created on the native filesystem. As such, they can be relied upon to be used with operating-system native APIs and external programs that require a filename. 




**file type** *name*

 Returns a string giving the type of file *name*, which will be one of **file**, **directory**, **characterSpecial**, **blockSpecial**, **fifo**, **link**, or **[socket](socket.htm)**. 

**file volumes**
 Returns the absolute paths to the volumes mounted on the system, as a proper Tcl list. Without any virtual filesystems mounted as root volumes, on UNIX, the command will always return “/”, since all filesystems are locally mounted. On Windows, it will return a list of the available local drives (e.g. “a:/ c:/”). If any virtual filesystem has mounted additional volumes, they will be in the returned list. 


**file writable** *name*

 Returns **1** if file *name* is writable by the current user, **0** otherwise. 

 Portability issues
------------------

  **Unix**
 These commands always operate using the real user and group identifiers, not the effective ones. 

**Windows**
 The **file owned** subcommand uses the user identifier (SID) of the process token, not the thread token which may be impersonating some other user. 

 Examples
--------

 This procedure shows how to search for C files in a given directory that have a correspondingly-named object file in the current directory: 

```
proc findMatchingCFiles {dir} {
    set files {}
    switch $::tcl_platform(platform) {
        windows {
            set ext .obj
        }
        unix {
           set ext .o
        }
    }
    foreach file [glob -nocomplain -directory $dir *.c] {
        set objectFile [**file tail** [**file rootname** $file]]$ext
        if {[**file exists** $objectFile]} {
            lappend files $file
        }
    }
    return $files
}
```
  Rename a file and leave a symbolic link pointing from the old location to the new place: 



```
set oldName foobar.txt
set newName foo/bar.txt
# Make sure that where we're going to move to exists...
if {![**file isdirectory** [**file dirname** $newName]]} {
    **file mkdir** [**file dirname** $newName]
}
**file rename** $oldName $newName
**file link** -symbolic $oldName $newName
```
  On Windows, a file can be “started” easily enough (equivalent to double-clicking on it in the Explorer interface) but the name passed to the operating system must be in native format: 



```
exec {*}[auto_execok start] {} [**file nativename** ~/example.txt]
```
 See also
--------

 **[filename](filename.htm)**, **[open](open.htm)**, **[close](close.htm)**, **[eof](eof.htm)**, **[gets](gets.htm)**, **[tell](tell.htm)**, **[seek](seek.htm)**, **[fblocked](fblocked.htm)**, **[flush](flush.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/file.htm>

mathop
======

  
[NAME](mathop.htm#M2) mathop — Mathematical operators as Tcl commands 
[SYNOPSIS](mathop.htm#M3) 
[DESCRIPTION](mathop.htm#M4) 
[MATHEMATICAL OPERATORS](mathop.htm#M5)  
[**!** *boolean*](mathop.htm#M6) 
[**+** ?*number* ...?](mathop.htm#M7) 
[**-** *number* ?*number* ...?](mathop.htm#M8) 
[**\*** ?*number* ...?](mathop.htm#M9) 
[**/** *number* ?*number* ...?](mathop.htm#M10) 
[**%** *number number*](mathop.htm#M11) 
[**\*\*** ?*number* ...?](mathop.htm#M12) 






 
[COMPARISON OPERATORS](mathop.htm#M13)  
[**==** ?*arg* ...?](mathop.htm#M14) 
[**eq** ?*arg* ...?](mathop.htm#M15) 
[**!=** *arg arg*](mathop.htm#M16) 
[**ne** *arg arg*](mathop.htm#M17) 
[**<** ?*arg* ...?](mathop.htm#M18) 
[**<=** ?*arg* ...?](mathop.htm#M19) 
[**>** ?*arg* ...?](mathop.htm#M20) 
[**>=** ?*arg* ...?](mathop.htm#M21) 







 
[BIT-WISE OPERATORS](mathop.htm#M22)  
[**~** *number*](mathop.htm#M23) 
[**&** ?*number* ...?](mathop.htm#M24) 
[**|** ?*number* ...?](mathop.htm#M25) 
[**^** ?*number* ...?](mathop.htm#M26) 
[**<<** *number number*](mathop.htm#M27) 
[**>>** *number number*](mathop.htm#M28) 





 
[LIST OPERATORS](mathop.htm#M29)  
[**in** *arg list*](mathop.htm#M30) 
[**ni** *arg list*](mathop.htm#M31) 

 
[EXAMPLES](mathop.htm#M32) 
[SEE ALSO](mathop.htm#M33) 
[KEYWORDS](mathop.htm#M34) 









 Name
----

 mathop — Mathematical operators as Tcl commands Synopsis
--------

 package require **Tcl 8.5**  
 **::tcl::mathop::!** *number*  
 **::tcl::mathop::~** *number*  
 **::tcl::mathop::+** ?*number* ...?  
 **::tcl::mathop::-** *number* ?*number* ...?  
 **::tcl::mathop::\*** ?*number* ...?  
 **::tcl::mathop::/** *number* ?*number* ...?  
 **::tcl::mathop::%** *number number*  
 **::tcl::mathop::\*\*** ?*number* ...?  
 **::tcl::mathop::&** ?*number* ...?  
 **::tcl::mathop::|** ?*number* ...?  
 **::tcl::mathop::^** ?*number* ...?  
 **::tcl::mathop::<<** *number number*  
 **::tcl::mathop::>>** *number number*  
 **::tcl::mathop::==** ?*arg* ...?  
 **::tcl::mathop::!=** *arg arg*  
 **::tcl::mathop::<** ?*arg* ...?  
 **::tcl::mathop::<=** ?*arg* ...?  
 **::tcl::mathop::>=** ?*arg* ...?  
 **::tcl::mathop::>** ?*arg* ...?  
 **::tcl::mathop::eq** ?*arg* ...?  
 **::tcl::mathop::ne** *arg arg*  
 **::tcl::mathop::in** *arg list*  
 **::tcl::mathop::ni** *arg list*  
 Description
-----------

 The commands in the **::tcl::mathop** namespace implement the same set of operations as supported by the **[expr](expr.htm)** command. All are exported from the namespace, but are not imported into any other namespace by default. Note that renaming, reimplementing or deleting any of the commands in the namespace does *not* alter the way that the **[expr](expr.htm)** command behaves, and nor does defining any new commands in the **::tcl::mathop** namespace.  The following operator commands are supported: 




|  |  |  |  |  |
| --- | --- | --- | --- | --- |
| **~** | **!** | **+** | **-** | **\*** |
| **/** | **%** | **\*\*** | **&** | **|** |
| **^** | **>>** | **<<** | **==** | **eq** |
| **!=** | **ne** | **<** | **<=** | **>** |
| **>=** | **in** | **ni** |

 ### Mathematical operators

 The behaviors of the mathematical operator commands are as follows: 
 
**!** *boolean*

 Returns the boolean negation of *boolean*, where *boolean* may be any numeric value or any other form of boolean value (i.e. it returns truth if the argument is falsity or zero, and falsity if the argument is truth or non-zero). 


**+** ?*number* ...?
 Returns the sum of arbitrarily many arguments. Each *number* argument may be any numeric value. If no arguments are given, the result will be zero (the summation identity). 


**-** *number* ?*number* ...?
 If only a single *number* argument is given, returns the negation of that numeric value. Otherwise returns the number that results when all subsequent numeric values are subtracted from the first one. All *number* arguments must be numeric values. At least one argument must be given. 


**\*** ?*number* ...?
 Returns the product of arbitrarily many arguments. Each *number* may be any numeric value. If no arguments are given, the result will be one (the multiplicative identity). 


**/** *number* ?*number* ...?
 If only a single *number* argument is given, returns the reciprocal of that numeric value (i.e. the value obtained by dividing 1.0 by that value). Otherwise returns the number that results when the first numeric argument is divided by all subsequent numeric arguments. All *number* arguments must be numeric values. At least one argument must be given.  Note that when the leading values in the list of arguments are integers, integer division will be used for those initial steps (i.e. the intermediate results will be as if the functions *floor* and *int* are applied to them, in that order). If all values in the operation are integers, the result will be an integer. 




**%** *number number*

 Returns the integral modulus (i.e., remainder) of the first argument with respect to the second. Each *number* must have an integral value. Also, the sign of the result will be the same as the sign of the second *number*, which must not be zero.  Note that Tcl defines this operation exactly even for negative numbers, so that the following command returns a true value (omitting the namespace for clarity): 



```
**==** [**\*** [**/** *x y*] *y*] [**-** *x* [**%** *x y*]]
```



**\*\*** ?*number* ...?
 Returns the result of raising each value to the power of the result of recursively operating on the result of processing the following arguments, so “**\*\* 2 3 4**” is the same as “**\*\* 2 [\*\* 3 4]**”. Each *number* may be any numeric value, though the second number must not be fractional if the first is negative. If no arguments are given, the result will be one, and if only one argument is given, the result will be that argument. The result will have an integral value only when all arguments are integral values. 

 ### Comparison operators

 The behaviors of the comparison operator commands (most of which operate preferentially on numeric arguments) are as follows: 
 
**==** ?*arg* ...?
 Returns whether each argument is equal to the arguments on each side of it in the sense of the **[expr](expr.htm)** == operator (*i.e.*, numeric comparison if possible, exact string comparison otherwise). If fewer than two arguments are given, this operation always returns a true value. 


**eq** ?*arg* ...?
 Returns whether each argument is equal to the arguments on each side of it using exact string comparison. If fewer than two arguments are given, this operation always returns a true value. 


**!=** *arg arg*

 Returns whether the two arguments are not equal to each other, in the sense of the **[expr](expr.htm)** != operator (*i.e.*, numeric comparison if possible, exact string comparison otherwise). 


**ne** *arg arg*

 Returns whether the two arguments are not equal to each other using exact string comparison. 


**<** ?*arg* ...?
 Returns whether the arbitrarily-many arguments are ordered, with each argument after the first having to be strictly more than the one preceding it. Comparisons are performed preferentially on the numeric values, and are otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the arguments are numeric but should be compared as strings, the **string compare** command should be used instead. 


**<=** ?*arg* ...?
 Returns whether the arbitrarily-many arguments are ordered, with each argument after the first having to be equal to or more than the one preceding it. Comparisons are performed preferentially on the numeric values, and are otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the arguments are numeric but should be compared as strings, the **string compare** command should be used instead. 


**>** ?*arg* ...?
 Returns whether the arbitrarily-many arguments are ordered, with each argument after the first having to be strictly less than the one preceding it. Comparisons are performed preferentially on the numeric values, and are otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the arguments are numeric but should be compared as strings, the **string compare** command should be used instead. 


**>=** ?*arg* ...?
 Returns whether the arbitrarily-many arguments are ordered, with each argument after the first having to be equal to or less than the one preceding it. Comparisons are performed preferentially on the numeric values, and are otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the arguments are numeric but should be compared as strings, the **string compare** command should be used instead. 

 ### Bit-wise operators

 The behaviors of the bit-wise operator commands (all of which only operate on integral arguments) are as follows: 
 
**~** *number*

 Returns the bit-wise negation of *number*. *Number* may be an integer of any size. Note that the result of this operation will always have the opposite sign to the input *number*. 


**&** ?*number* ...?
 Returns the bit-wise AND of each of the arbitrarily many arguments. Each *number* must have an integral value. If no arguments are given, the result will be minus one. 


**|** ?*number* ...?
 Returns the bit-wise OR of each of the arbitrarily many arguments. Each *number* must have an integral value. If no arguments are given, the result will be zero. 


**^** ?*number* ...?
 Returns the bit-wise XOR of each of the arbitrarily many arguments. Each *number* must have an integral value. If no arguments are given, the result will be zero. 


**<<** *number number*

 Returns the result of bit-wise shifting the first argument left by the number of bits specified in the second argument. Each *number* must have an integral value. 


**>>** *number number*

 Returns the result of bit-wise shifting the first argument right by the number of bits specified in the second argument. Each *number* must have an integral value. 

 ### List operators

 The behaviors of the list-oriented operator commands are as follows: 
 
**in** *arg list*

 Returns whether the value *arg* is present in the list *list* (according to exact string comparison of elements). 


**ni** *arg list*

 Returns whether the value *arg* is not present in the list *list* (according to exact string comparison of elements). 

 Examples
--------

 The simplest way to use the operators is often by using **[namespace path](namespace.htm)** to make the commands available. This has the advantage of not affecting the set of commands defined by the current namespace. 

```
namespace path {**::tcl::mathop** ::tcl::mathfunc}

*# Compute the sum of some numbers*
set sum [**+** 1 2 3]

*# Compute the average of a list*
set list {1 2 3 4 5 6}
set mean [**/** [**+** {*}$list] [double [llength $list]]]

*# Test for list membership*
set gotIt [**in** 3 $list]

*# Test to see if a value is within some defined range*
set inRange [**<=** 1 $x 5]

*# Test to see if a list is sorted*
set sorted [**<=** {*}$list]
```
 See also
--------

 **[expr](expr.htm)**, **[mathfunc](mathfunc.htm)**, **[namespace](namespace.htm)** 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/mathop.htm>

for
===

 Name
----

 for — 'For' loop Synopsis
--------

 **for** *start test next body*  
 Description
-----------

 **For** is a looping command, similar in structure to the C **for** statement. The *start*, *next*, and *body* arguments must be Tcl command strings, and *test* is an expression string. The **for** command first invokes the Tcl interpreter to execute *start*. Then it repeatedly evaluates *test* as an expression; if the result is non-zero it invokes the Tcl interpreter on *body*, then invokes the Tcl interpreter on *next*, then repeats the loop. The command terminates when *test* evaluates to 0. If a **[continue](continue.htm)** command is invoked within *body* then any remaining commands in the current execution of *body* are skipped; processing continues by invoking the Tcl interpreter on *next*, then evaluating *test*, and so on. If a **[break](break.htm)** command is invoked within *body* or *next*, then the **for** command will return immediately. The operation of **[break](break.htm)** and **[continue](continue.htm)** are similar to the corresponding statements in C. **For** returns an empty string.  Note: *test* should almost always be enclosed in braces. If not, variable substitutions will be made before the **for** command starts executing, which means that variable changes made by the loop body will not be considered in the expression. This is likely to result in an infinite loop. If *test* is enclosed in braces, variable substitutions are delayed until the expression is evaluated (before each loop iteration), so changes in the variables will be visible. See below for an example: 


Examples
--------

 Print a line for each of the integers from 0 to 9: 

```
**for** {set x 0} {$x<10} {incr x} {
    puts "x is $x"
}
```
  Either loop infinitely or not at all because the expression being evaluated is actually the constant, or even generate an error! The actual behaviour will depend on whether the variable *x* exists before the **for** command is run and whether its value is a value that is less than or greater than/equal to ten, and this is because the expression will be substituted before the **for** command is executed. 



```
**for** {set x 0} $x<10 {incr x} {
    puts "x is $x"
}
```
  Print out the powers of two from 1 to 1024: 



```
**for** {set x 1} {$x<=1024} {set x [expr {$x * 2}]} {
    puts "x is $x"
}
```
 See also
--------

 **[break](break.htm)**, **[continue](continue.htm)**, **[foreach](foreach.htm)**, **[while](while.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/for.htm>

set
===

 Name
----

 set — Read and write variables Synopsis
--------

 **set** *varName* ?*value*?  
 Description
-----------

 Returns the value of variable *varName*. If *value* is specified, then set the value of *varName* to *value*, creating a new variable if one does not already exist, and return its value. If *varName* contains an open parenthesis and ends with a close parenthesis, then it refers to an array element: the characters before the first open parenthesis are the name of the array, and the characters between the parentheses are the index within the array. Otherwise *varName* refers to a scalar variable.  If *varName* includes namespace qualifiers (in the array name if it refers to an array element), or if *varName* is unqualified (does not include the names of any containing namespaces) but no procedure is active, *varName* refers to a namespace variable resolved according to the rules described under **NAME RESOLUTION** in the **[namespace](namespace.htm)** manual page. 


 If a procedure is active and *varName* is unqualified, then *varName* refers to a parameter or local variable of the procedure, unless *varName* was declared to resolve differently through one of the **[global](global.htm)**, **[variable](variable.htm)** or **[upvar](upvar.htm)** commands. 


Examples
--------

 Store a random number in the variable *r*: 

```
**set** r [expr {rand()}]
```
  Store a short message in an array element: 



```
**set** anAry(msg) "Hello, World!"
```
  Store a short message in an array element specified by a variable: 



```
**set** elemName "msg"
**set** anAry($elemName) "Hello, World!"
```
  Copy a value into the variable *out* from a variable whose name is stored in the *vbl* (note that it is often easier to use arrays in practice instead of doing double-dereferencing): 



```
**set** in0 "small random"
**set** in1 "large random"
**set** vbl in[expr {rand() >= 0.5}]
**set** out [**set** $vbl]
```
 See also
--------

 **[expr](expr.htm)**, **[global](global.htm)**, **[namespace](namespace.htm)**, **[proc](proc.htm)**, **[trace](trace.htm)**, **[unset](unset.htm)**, **[upvar](upvar.htm)**, **[variable](variable.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/set.htm>

foreach
=======

 Name
----

 foreach — Iterate over all elements in one or more lists Synopsis
--------

 **foreach** *varname list body*  
 **foreach** *varlist1 list1* ?*varlist2 list2 ...*? *body*  
 Description
-----------

 The **foreach** command implements a loop where the loop variable(s) take on values from one or more lists. In the simplest case there is one loop variable, *varname*, and one list, *list*, that is a list of values to assign to *varname*. The *body* argument is a Tcl script. For each element of *list* (in order from first to last), **foreach** assigns the contents of the element to *varname* as if the **[lindex](lindex.htm)** command had been used to extract the element, then calls the Tcl interpreter to execute *body*.  In the general case there can be more than one value list (e.g., *list1* and *list2*), and each value list can be associated with a list of loop variables (e.g., *varlist1* and *varlist2*). During each iteration of the loop the variables of each *varlist* are assigned consecutive values from the corresponding *list*. Values in each *list* are used in order from first to last, and each value is used exactly once. The total number of loop iterations is large enough to use up all the values from all the value lists. If a value list does not contain enough elements for each of its loop variables in each iteration, empty values are used for the missing elements. 


 The **[break](break.htm)** and **[continue](continue.htm)** statements may be invoked inside *body*, with the same effect as in the **[for](for.htm)** command. **Foreach** returns an empty string. 


Examples
--------

 This loop prints every value in a list together with the square and cube of the value: 

```
set values {1 3 5 7 2 4 6 8}	;# Odd numbers first, for fun!
puts "Value\tSquare\tCube"	;# Neat-looking header
**foreach** x $values {	;# Now loop and print...
    puts " $x\t [expr {$x**2}]\t [expr {$x**3}]"
}
```
  The following loop uses i and j as loop variables to iterate over pairs of elements of a single list. 



```
set x {}
**foreach** {i j} {a b c d e f} {
    lappend x $j $i
}
# The value of x is "b a d c f e"
# There are 3 iterations of the loop.
```
  The next loop uses i and j to iterate over two lists in parallel. 



```
set x {}
**foreach** i {a b c} j {d e f g} {
    lappend x $i $j
}
# The value of x is "a d b e c f {} g"
# There are 4 iterations of the loop.
```
  The two forms are combined in the following example. 



```
set x {}
**foreach** i {a b c} {j k} {d e f g} {
    lappend x $i $j $k
}
# The value of x is "a d e b f g c {} {}"
# There are 3 iterations of the loop.
```
 See also
--------

 **[for](for.htm)**, **[while](while.htm)**, **[break](break.htm)**, **[continue](continue.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/foreach.htm>

bgerror
=======

 Name
----

 bgerror — Command invoked to process background errors Synopsis
--------

 **bgerror** *message*  
 Description
-----------

 Release 8.5 of Tcl supports the **[interp bgerror](interp.htm)** command, which allows applications to register in an interpreter the command that will handle background errors in that interpreter. In older releases of Tcl, this level of control was not available, and applications could control the handling of background errors only by creating a command with the particular command name **bgerror** in the global namespace of an interpreter. The following documentation describes the interface requirements of the **bgerror** command an application might define to retain compatibility with pre-8.5 releases of Tcl. Applications intending to support only Tcl releases 8.5 and later should simply make use of **[interp bgerror](interp.htm)**.  The **bgerror** command does not exist as built-in part of Tcl. Instead, individual applications or users can define a **bgerror** command (e.g. as a Tcl procedure) if they wish to handle background errors. 


 A background error is one that occurs in an event handler or some other command that did not originate with the application. For example, if an error occurs while executing a command specified with the **[after](after.htm)** command, then it is a background error. For a non-background error, the error can simply be returned up through nested Tcl command evaluations until it reaches the top-level code in the application; then the application can report the error in whatever way it wishes. When a background error occurs, the unwinding ends in the Tcl library and there is no obvious way for Tcl to report the error. 


 When Tcl detects a background error, it saves information about the error and invokes a handler command registered by **[interp bgerror](interp.htm)** later as an idle event handler. The default handler command in turn calls the **bgerror** command . Before invoking **bgerror**, Tcl restores the **[errorInfo](tclvars.htm)** and **[errorCode](tclvars.htm)** variables to their values at the time the error occurred, then it invokes **bgerror** with the error message as its only argument. Tcl assumes that the application has implemented the **bgerror** command, and that the command will report the error in a way that makes sense for the application. Tcl will ignore any result returned by the **bgerror** command as long as no error is generated. 


 If another Tcl error occurs within the **bgerror** command (for example, because no **bgerror** command has been defined) then Tcl reports the error itself by writing a message to stderr. 


 If several background errors accumulate before **bgerror** is invoked to process them, **bgerror** will be invoked once for each error, in the order they occurred. However, if **bgerror** returns with a break exception, then any remaining errors are skipped without calling **bgerror**. 


 If you are writing code that will be used by others as part of a package or other kind of library, consider avoiding **bgerror**. The reason for this is that the application programmer may also want to define a **bgerror**, or use other code that does and thus will have trouble integrating your code. 


Example
-------

 This **bgerror** procedure appends errors to a file, with a timestamp. 

```
proc bgerror {message} {
    set timestamp [clock format [clock seconds]]
    set fl [open mylog.txt {WRONLY CREAT APPEND}]
    puts $fl "$timestamp: bgerror in $::argv '$message'"
    close $fl
}
```
 See also
--------

 **[after](after.htm)**, **[errorCode](tclvars.htm)**, **[errorInfo](tclvars.htm)**, **[interp](interp.htm)** Copyright © 1990-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/bgerror.htm>

gets
====

 Name
----

 gets — Read a line from a channel Synopsis
--------

 **gets** *channelId* ?*varName*?  
 Description
-----------

 This command reads the next line from *channelId*, returns everything in the line up to (but not including) the end-of-line character(s), and discards the end-of-line character(s).  *ChannelId* must be an identifier for an open channel such as the Tcl standard input channel (**[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**), the return value from an invocation of **[open](open.htm)** or **[socket](socket.htm)**, or the result of a channel creation command provided by a Tcl extension. The channel must have been opened for input. 


 If *varName* is omitted the line is returned as the result of the command. If *varName* is specified then the line is placed in the variable by that name and the return value is a count of the number of characters returned. 


 If end of file occurs while scanning for an end of line, the command returns whatever input is available up to the end of file. If *channelId* is in non-blocking mode and there is not a full line of input available, the command returns an empty string and does not consume any input. If *varName* is specified and an empty string is returned in *varName* because of end-of-file or because of insufficient data in non-blocking mode, then the return count is -1. Note that if *varName* is not specified then the end-of-file and no-full-line-available cases can produce the same results as if there were an input line consisting only of the end-of-line character(s). The **[eof](eof.htm)** and **[fblocked](fblocked.htm)** commands can be used to distinguish these three cases. 


Example
-------

 This example reads a file one line at a time and prints it out with the current line number attached to the start of each line. 

```
set chan [open "some.file.txt"]
set lineNumber 0
while {[**gets** $chan line] >= 0} {
    puts "[incr lineNumber]: $line"
}
close $chan
```
 See also
--------

 **[file](file.htm)**, **[eof](eof.htm)**, **[fblocked](fblocked.htm)**, **[Tcl\_StandardChannels](https://www.tcl.tk/man/tcl/TclLib/StdChannels.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/gets.htm>

split
=====

 Name
----

 split — Split a string into a proper Tcl list Synopsis
--------

 **split** *string* ?*splitChars*?  
 Description
-----------

 Returns a list created by splitting *string* at each character that is in the *splitChars* argument. Each element of the result list will consist of the characters from *string* that lie between instances of the characters in *splitChars*. Empty list elements will be generated if *string* contains adjacent characters in *splitChars*, or if the first or last character of *string* is in *splitChars*. If *splitChars* is an empty string then each character of *string* becomes a separate element of the result list. *SplitChars* defaults to the standard white-space characters. Examples
--------

 Divide up a USENET group name into its hierarchical components: 

```
**split** "comp.lang.tcl" .
      *→ comp lang tcl*
```
  See how the **split** command splits on *every* character in *splitChars*, which can result in information loss if you are not careful: 



```
**split** "alpha beta gamma" "temp"
      *→ al {ha b} {} {a ga} {} a*
```
  Extract the list words from a string that is not a well-formed list: 



```
**split** "Example with {unbalanced brace character"
      *→ Example with \{unbalanced brace character*
```
  Split a string into its constituent characters 



```
**split** "Hello world" {}
      *→ H e l l o { } w o r l d*
```
 ### Parsing record-oriented files

 Parse a Unix /etc/passwd file, which consists of one entry per line, with each line consisting of a colon-separated list of fields: 

```
## Read the file
set fid [open /etc/passwd]
set content [read $fid]
close $fid

## Split into records on newlines
set records [**split** $content "\n"]

## Iterate over the records
foreach rec $records {

    ## Split into fields on colons
    set fields [**split** $rec ":"]

    ## Assign fields to variables and print some out...
    lassign $fields \
            userName password uid grp longName homeDir shell
    puts "$longName uses [file tail $shell] for a login shell"
}
```
 See also
--------

 **[join](join.htm)**, **[list](list.htm)**, **[string](string.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/split.htm>

break
=====

 Name
----

 break — Abort looping command Synopsis
--------

 **break**  
 Description
-----------

 This command is typically invoked inside the body of a looping command such as **[for](for.htm)** or **[foreach](foreach.htm)** or **[while](while.htm)**. It returns a 3 (**[TCL\_BREAK](catch.htm)**) result code, which causes a break exception to occur. The exception causes the current script to be aborted out to the innermost containing loop command, which then aborts its execution and returns normally. Break exceptions are also handled in a few other situations, such as the **[catch](catch.htm)** command, Tk event bindings, and the outermost scripts of procedure bodies. Example
-------

 Print a line for each of the integers from 0 to 5: 

```
for {set x 0} {$x<10} {incr x} {
    if {$x > 5} {
        **break**
    }
    puts "x is $x"
}
```
 See also
--------

 **[catch](catch.htm)**, **[continue](continue.htm)**, **[for](for.htm)**, **[foreach](foreach.htm)**, **[return](return.htm)**, **[while](while.htm)** Copyright © 1993-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/break.htm>

tm
==

  
[NAME](tm.htm#M2) tm — Facilities for locating and loading of Tcl Modules 
[SYNOPSIS](tm.htm#M3) 
[DESCRIPTION](tm.htm#M4)  
[**::tcl::tm::path add** ?*path*...?](tm.htm#M5) 
[**::tcl::tm::path remove** ?*path*...?](tm.htm#M6) 
[**::tcl::tm::path list**](tm.htm#M7) 
[**::tcl::tm::roots** ?*path*...?](tm.htm#M8) 



 
[MODULE DEFINITION](tm.htm#M9) 
[FINDING MODULES](tm.htm#M10) 
[DEFAULT PATHS](tm.htm#M11) 
[SYSTEM SPECIFIC PATHS](tm.htm#M12)  
[**file normalize [info library]/../tcl***X***/***X***.***y*](tm.htm#M13) 
[**file normalize EXEC/tcl***X***/***X***.***y*](tm.htm#M14) 

 
[SITE SPECIFIC PATHS](tm.htm#M15)  
[**file normalize [info library]/../tcl***X***/site-tcl**](tm.htm#M16) 
 
[USER SPECIFIC PATHS](tm.htm#M17)  
[**$::env(TCL***X***\_***y***\_TM\_PATH)**](tm.htm#M18) 
[**$::env(TCL***X***.***y***\_TM\_PATH)**](tm.htm#M19) 

 
[SEE ALSO](tm.htm#M20) 
[KEYWORDS](tm.htm#M21) 










 Name
----

 tm — Facilities for locating and loading of Tcl Modules Synopsis
--------

 **::tcl::tm::path add** ?*path*...?  
 **::tcl::tm::path remove** ?*path*...?  
 **::tcl::tm::path list**  
 **::tcl::tm::roots** ?*path*...?  
 Description
-----------

 This document describes the facilities for locating and loading Tcl Modules (see **[MODULE DEFINITION](#M9)** for the definition of a Tcl Module). The following commands are supported: 
 
**::tcl::tm::path add** ?*path*...?
 The paths are added at the head to the list of module paths, in order of appearance. This means that the last argument ends up as the new head of the list.  The command enforces the restriction that no path may be an ancestor directory of any other path on the list. If any of the new paths violates this restriction an error will be raised, before any of the paths have been added. In other words, if only one path argument violates the restriction then none will be added. 


 If a path is already present as is, no error will be raised and no action will be taken. 


Paths are searched later in the order of their appearance in the list. As they are added to the front of the list they are searched in reverse order of addition. In other words, the paths added last are looked at first. 




**::tcl::tm::path remove** ?*path*...?
 Removes the paths from the list of module paths. The command silently ignores all paths which are not on the list. 

**::tcl::tm::path list**
 Returns a list containing all registered module paths, in the order that they are searched for modules. 


**::tcl::tm::roots** ?*path*...?
 Similar to **path add**, and layered on top of it. This command takes a list of paths, extends each with “**tcl***X***/site-tcl**”, and “**tcl***X***/***X***.***y*”, for major version *X* of the Tcl interpreter and minor version *y* less than or equal to the minor version of the interpreter, and adds the resulting set of paths to the list of paths to search.  This command is used internally by the system to set up the system-specific default paths. 


The command has been exposed to allow a build system to define additional root paths beyond those described by this document. 



 Module definition
-----------------

 A Tcl Module is a Tcl Package contained in a single file, and no other files required by it. This file has to be **[source](source.htm)**able. In other words, a Tcl Module is always imported via: 

```
source module_file
```
  The **[load](load.htm)** command is not directly used. This restriction is not an actual limitation, as some may believe. Ever since 8.4 the Tcl **[source](source.htm)** command reads only until the first ^Z character. This allows us to combine an arbitrary Tcl script with arbitrary binary data into one file, where the script processes the attached data in any it chooses to fully import and activate the package. 


 The name of a module file has to match the regular expression: 



```
([_[:alpha:]][:_[:alnum:]]*)-([[:digit:]].*)\.tm
```
  The first capturing parentheses provides the name of the package, the second clause its version. In addition to matching the pattern, the extracted version number must not raise an error when used in the command: 



```
package vcompare $version 0
```
 Finding modules
---------------

 The directory tree for storing Tcl modules is separate from other parts of the filesystem and independent of **[auto\_path](tclvars.htm)**.  Tcl Modules are searched for in all directories listed in the result of the command **::tcl::tm::path list**. This is called the *Module path*. Neither the **[auto\_path](tclvars.htm)** nor the **[tcl\_pkgPath](tclvars.htm)** variables are used. All directories on the module path have to obey one restriction: 


  For any two directories, neither is an ancestor directory of the other. 


  This is required to avoid ambiguities in package naming. If for example the two directories “*foo/*” and “*foo/cool*” were on the path a package named **cool::ice** could be found via the names **cool::ice** or **ice**, the latter potentially obscuring a package named **ice**, unqualified. 


 Before the search is started, the name of the requested package is translated into a partial path, using the following algorithm: 


  All occurrences of “**::**” in the package name are replaced by the appropriate directory separator character for the platform we are on. On Unix, for example, this is “**/**”. 


  Example: 


  The requested package is **encoding::base64**. The generated partial path is “*encoding/base64*”. 


  After this translation the package is looked for in all module paths, by combining them one-by-one, first to last with the partial path to form a complete search pattern. Note that the search algorithm rejects all files where the filename does not match the regular expression given in the section **[MODULE DEFINITION](#M9)**. For the remaining files *provide scripts* are generated and added to the package ifneeded database. 


 The algorithm falls back to the previous unknown handler when none of the found module files satisfy the request. If the request was satisfied the fall-back is ignored. 


 Note that packages in module form have *no* control over the *index* and *provide script*s entered into the package database for them. For a module file **MF** the *index script* is always: 



```
package ifneeded **PNAME PVERSION** [list source **MF**]
```
  and the *provide script* embedded in the above is: 



```
source **MF**
```
  Both package name **PNAME** and package version **PVERSION** are extracted from the filename **MF** according to the definition below: 



```
**MF** = /module_path/**PNAME′**-**PVERSION**.tm
```
  Where **PNAME′** is the partial path of the module as defined in section **[FINDING MODULES](#M10)**, and translated into **PNAME** by changing all directory separators to “**::**”, and **module\_path** is the path (from the list of paths to search) that we found the module file under. 


 Note also that we are here creating a connection between package names and paths. Tcl is case-sensitive when it comes to comparing package names, but there are filesystems which are not, like NTFS. Luckily these filesystems do store the case of the name, despite not using the information when comparing. 


 Given the above we allow the names for packages in Tcl modules to have mixed-case, but also require that there are no collisions when comparing names in a case-insensitive manner. In other words, if a package **Foo** is deployed in the form of a Tcl Module, packages like **foo**, **fOo**, etc. are not allowed anymore. 


Default paths
-------------

 The default list of paths on the module path is computed by a **[tclsh](../usercmd/tclsh.htm)** as follows, where *X* is the major version of the Tcl interpreter and *y* is less than or equal to the minor version of the Tcl interpreter.  All the default paths are added to the module path, even those paths which do not exist. Non-existent paths are filtered out during actual searches. This enables a user to create one of the paths searched when needed and all running applications will automatically pick up any modules placed in them. 


 The paths are added in the order as they are listed below, and for lists of paths defined by an environment variable in the order they are found in the variable. 


### System specific paths

  
**file normalize [info library]/../tcl***X***/***X***.***y*

 In other words, the interpreter will look into a directory specified by its major version and whose minor versions are less than or equal to the minor version of the interpreter.  For example for Tcl 8.4 the paths searched are: 



```
**[info library]/../tcl8/8.4**
**[info library]/../tcl8/8.3**
**[info library]/../tcl8/8.2**
**[info library]/../tcl8/8.1**
**[info library]/../tcl8/8.0**
```
 This definition assumes that a package defined for Tcl *X***.***y* can also be used by all interpreters which have the same major number *X* and a minor number greater than *y*. 




**file normalize EXEC/tcl***X***/***X***.***y*

 Where **EXEC** is **file normalize [info nameofexecutable]/../lib** or **file normalize [::tcl::pkgconfig get libdir,runtime]**  This sets of paths is handled equivalently to the set coming before, except that it is anchored in **EXEC\_PREFIX**. For a build with **PREFIX** = **EXEC\_PREFIX** the two sets are identical. 



 ### Site specific paths

  
**file normalize [info library]/../tcl***X***/site-tcl**

 Note that this is always a single entry because *X* is always a specific value (the current major version of Tcl). 

 ### User specific paths

  
**$::env(TCL***X***\_***y***\_TM\_PATH)**

 A list of paths, separated by either **:** (Unix) or **;** (Windows). This is user and site specific as this environment variable can be set not only by the user's profile, but by system configuration scripts as well. 


**$::env(TCL***X***.***y***\_TM\_PATH)**

 Same meaning and content as the previous variable. However the use of dot '.' to separate major and minor version number makes this name less to non-portable and its use is discouraged. Support of this variable has been kept only for backward compatibility with the original specification, i.e. TIP 189. 

  These paths are seen and therefore shared by all Tcl shells in the **$::env(PATH)** of the user. 


 Note that *X* and *y* follow the general rules set out above. In other words, Tcl 8.4, for example, will look at these 10 environment variables: 



```
**$::env(TCL8.4\_TM\_PATH)**  **$::env(TCL8\_4\_TM\_PATH)**
**$::env(TCL8.3\_TM\_PATH)**  **$::env(TCL8\_3\_TM\_PATH)**
**$::env(TCL8.2\_TM\_PATH)**  **$::env(TCL8\_2\_TM\_PATH)**
**$::env(TCL8.1\_TM\_PATH)**  **$::env(TCL8\_1\_TM\_PATH)**
**$::env(TCL8.0\_TM\_PATH)**  **$::env(TCL8\_0\_TM\_PATH)**
```
 See also
--------

 **[package](package.htm)**, **Tcl Improvement Proposal #189 “*Tcl Modules*” (online at <http://tip.tcl.tk/189.html>)**, **Tcl Improvement Proposal #190 “*Implementation Choices for Tcl Modules*” (online at <http://tip.tcl.tk/190.html>)** Copyright © 2004-2010 Andreas Kupries <andreas\_kupries(at)users.sourceforge.net> 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/tm.htm>

next
====

  
[NAME](next.htm#M2) next, nextto — invoke superclass method implementations 
[SYNOPSIS](next.htm#M3) 
[DESCRIPTION](next.htm#M4) 
[THE METHOD CHAIN](next.htm#M5) 
[METHOD SEARCH ORDER](next.htm#M6) 
[FILTERS](next.htm#M7) 
[EXAMPLES](next.htm#M8) 
[SEE ALSO](next.htm#M9) 
[KEYWORDS](next.htm#M10) 








 Name
----

 next, nextto — invoke superclass method implementations Synopsis
--------

 package require TclOO  
   
 **next** ?*arg ...*?  
 **nextto** *class* ?*arg ...*?  
 Description
-----------

 The **next** command is used to call implementations of a method by a class, superclass or mixin that are overridden by the current method. It can only be used from within a method. It is also used within filters to indicate the point where a filter calls the actual implementation (the filter may decide to not go along the chain, and may process the results of going along the chain of methods as it chooses). The result of the **next** command is the result of the next method in the method chain; if there are no further methods in the method chain, the result of **next** will be an error. The arguments, *arg*, to **next** are the arguments to pass to the next method in the chain.  The **nextto** command is the same as the **next** command, except that it takes an additional *class* argument that identifies a class whose implementation of the current method chain (see **[info object](info.htm)** **call**) should be used; the method implementation selected will be the one provided by the given class, and it must refer to an existing non-filter invocation that lies further along the chain than the current implementation. 


The method chain
----------------

 When a method of an object is invoked, things happen in several stages: 
1. The structure of the object, its class, superclasses, filters, and mixins, are examined to build a *method chain*, which contains a list of method implementations to invoke.
2. The first method implementation on the chain is invoked.
3. If that method implementation invokes the **next** command, the next method implementation is invoked (with its arguments being those that were passed to **next**).
4. The result from the overall method call is the result from the outermost method implementation; inner method implementations return their results through **next**.
5. The method chain is cached for future use.

 ### Method search order

 When constructing the method chain, method implementations are searched for in the following order: 
1. In the classes mixed into the object, in class traversal order. The list of mixins is checked in natural order.
2. In the classes mixed into the classes of the object, with sources of mixing in being searched in class traversal order. Within each class, the list of mixins is processed in natural order.
3. In the object itself.
4. In the object's class.
5. In the superclasses of the class, following each superclass in a depth-first fashion in the natural order of the superclass list.

  Any particular method implementation always comes as *late* in the resulting list of implementations as possible; this means that if some class, A, is both mixed into a class, B, and is also a superclass of B, the instances of B will always treat A as a superclass from the perspective of inheritance. This is true even when the multiple inheritance is processed indirectly. 


### Filters

 When an object has a list of filter names set upon it, or is an instance of a class (or has mixed in a class) that has a list of filter names set upon it, before every invocation of any method the filters are processed. Filter implementations are found in class traversal order, as are the lists of filter names (each of which is traversed in natural list order). Explicitly invoking a method used as a filter will cause that method to be invoked twice, once as a filter and once as a normal method.  Each filter should decide for itself whether to permit the execution to go forward to the proper implementation of the method (which it does by invoking the **next** command as filters are inserted into the front of the method call chain) and is responsible for returning the result of **next**. 


 Filters are invoked when processing an invokation of the **unknown** method because of a failure to locate a method implementation, but *not* when invoking either constructors or destructors. (Note however that the **[destroy](../tkcmd/destroy.htm)** method is a conventional method, and filters are invoked as normal when it is called.) 


Examples
--------

 This example demonstrates how to use the **next** command to call the (super)class's implementation of a method. The script: 

```
oo::class create theSuperclass {
    method example {args} {
        puts "in the superclass, args = $args"
    }
}
oo::class create theSubclass {
    superclass theSuperclass
    method example {args} {
        puts "before chaining from subclass, args = $args"
        **next** a {*}$args b
        **next** pureSynthesis
        puts "after chaining from subclass"
    }
}
theSubclass create obj
oo::objdefine obj method example args {
    puts "per-object method, args = $args"
    **next** x {*}$args y
    **next**
}
obj example 1 2 3
```
  prints the following: 



```
per-object method, args = 1 2 3
before chaining from subclass, args = x 1 2 3 y
in the superclass, args = a x 1 2 3 y b
in the superclass, args = pureSynthesis
after chaining from subclass
before chaining from subclass, args = 
in the superclass, args = a b
in the superclass, args = pureSynthesis
after chaining from subclass
```
  This example demonstrates how to build a simple cache class that applies memoization to all the method calls of the objects it is mixed into, and shows how it can make a difference to computation times: 



```
oo::class create cache {
    filter Memoize
    method Memoize args {
        *# Do not filter the core method implementations*
        if {[lindex [self target] 0] eq "::oo::object"} {
            return [**next** {*}$args]
        }

        *# Check if the value is already in the cache*
        my variable ValueCache
        set key [self target],$args
        if {[info exist ValueCache($key)]} {
            return $ValueCache($key)
        }

        *# Compute value, insert into cache, and return it*
        return [set ValueCache($key) [**next** {*}$args]]
    }
    method flushCache {} {
        my variable ValueCache
        unset ValueCache
        *# Skip the caching*
        return -level 2 ""
    }
}

oo::object create demo
oo::objdefine demo {
    mixin cache
    method compute {a b c} {
        after 3000 *;# Simulate deep thought*
        return [expr {$a + $b * $c}]
    }
    method compute2 {a b c} {
        after 3000 *;# Simulate deep thought*
        return [expr {$a * $b + $c}]
    }
}

puts [demo compute  1 2 3]      *→ prints "7" after delay*
puts [demo compute2 4 5 6]      *→ prints "26" after delay*
puts [demo compute  1 2 3]      *→ prints "7" instantly*
puts [demo compute2 4 5 6]      *→ prints "26" instantly*
puts [demo compute  4 5 6]      *→ prints "34" after delay*
puts [demo compute  4 5 6]      *→ prints "34" instantly*
puts [demo compute  1 2 3]      *→ prints "7" instantly*
demo flushCache
puts [demo compute  1 2 3]      *→ prints "7" after delay*
```
 See also
--------

 **[oo::class](class.htm)**, **[oo::define](define.htm)**, **[oo::object](object.htm)**, **[self](self.htm)** Copyright © 2007 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/next.htm>

transchan
=========

  
[NAME](transchan.htm#M2) transchan — command handler API of channel transforms 
[SYNOPSIS](transchan.htm#M3) 
[DESCRIPTION](transchan.htm#M4) 
[GENERIC SUBCOMMANDS](transchan.htm#M5)  
[*cmdPrefix* **clear** *handle*](transchan.htm#M6) 
[*cmdPrefix* **finalize** *handle*](transchan.htm#M7) 
[*cmdPrefix* **initialize** *handle mode*](transchan.htm#M8)  
[**write**](transchan.htm#M9) 
[**read**](transchan.htm#M10) 

 


 
[READ-RELATED SUBCOMMANDS](transchan.htm#M11)  
[*cmdPrefix* **drain** *handle*](transchan.htm#M12) 
[*cmdPrefix* **limit?** *handle*](transchan.htm#M13) 
[*cmdPrefix* **read** *handle buffer*](transchan.htm#M14) 


 
[WRITE-RELATED SUBCOMMANDS](transchan.htm#M15)  
[*cmdPrefix* **flush** *handle*](transchan.htm#M16) 
[*cmdPrefix* **write** *handle buffer*](transchan.htm#M17) 

 
[SEE ALSO](transchan.htm#M18) 
[KEYWORDS](transchan.htm#M19) 







 Name
----

 transchan — command handler API of channel transforms Synopsis
--------

 **cmdPrefix** *option* ?*arg arg ...*?  
 Description
-----------

 The Tcl-level handler for a channel transformation has to be a command with subcommands (termed an *ensemble* despite not implying that it must be created with **namespace ensemble create**; this mechanism is not tied to **[namespace ensemble](namespace.htm)** in any way). Note that *cmdPrefix* is whatever was specified in the call to **[chan push](chan.htm)**, and may consist of multiple arguments; this will be expanded to multiple words in place of the prefix.  Of all the possible subcommands, the handler *must* support **initialize** and **finalize**. Transformations for writable channels must also support **write**, and transformations for readable channels must also support **[read](read.htm)**. 


 Note that in the descriptions below *cmdPrefix* may be more than one word, and *handle* is the value returned by the **[chan push](chan.htm)** call used to create the transformation. 


### Generic subcommands

 The following subcommands are relevant to all types of channel. 
 
*cmdPrefix* **clear** *handle*

 This optional subcommand is called to signify to the transformation that any data stored in internal buffers (either incoming or outgoing) must be cleared. It is called when a **[chan seek](chan.htm)** is performed on the channel being transformed. 


*cmdPrefix* **finalize** *handle*

 This mandatory subcommand is called last for the given *handle*, and then never again, and it exists to allow for cleaning up any Tcl-level data structures associated with the transformation. *Warning!* Any errors thrown by this subcommand will be ignored. It is not guaranteed to be called if the interpreter is deleted. 


*cmdPrefix* **initialize** *handle mode*

 This mandatory subcommand is called first, and then never again (for the given *handle*). Its responsibility is to initialize all parts of the transformation at the Tcl level. The *mode* is a list containing any of **read** and **write**. 
 **write**
 implies that the channel is writable. 

**read**
 implies that the channel is readable. 

The return value of the subcommand should be a list containing the names of all subcommands supported by this handler. Any error thrown by the subcommand will prevent the creation of the transformation. The thrown error will appear as error thrown by **[chan push](chan.htm)**.



 ### Read-related subcommands

 These subcommands are used for handling transformations applied to readable channels; though strictly **read** is optional, it must be supported if any of the others is or the channel will be made non-readable. 
 
*cmdPrefix* **drain** *handle*

 This optional subcommand is called whenever data in the transformation input (i.e. read) buffer has to be forced upward, i.e. towards the user or script. The result returned by the method is taken as the *binary* data to push upward to the level above this transformation (the reader or a higher-level transformation).  In other words, when this method is called the transformation cannot defer the actual transformation operation anymore and has to transform all data waiting in its internal read buffers and return the result of that action. 




*cmdPrefix* **limit?** *handle*

 This optional subcommand is called to allow the Tcl I/O engine to determine how far ahead it should read. If present, it should return an integer number greater than zero which indicates how many bytes ahead should be read, or an integer less than zero to indicate that the I/O engine may read as far ahead as it likes. 


*cmdPrefix* **read** *handle buffer*

 This subcommand, which must be present if the transformation is to work with readable channels, is called whenever the base channel, or a transformation below this transformation, pushes data upward. The *buffer* contains the binary data which has been given to us from below. It is the responsibility of this subcommand to actually transform the data. The result returned by the subcommand is taken as the binary data to push further upward to the transformation above this transformation. This can also be the user or script that originally read from the channel.  Note that the result is allowed to be empty, or even less than the data we received; the transformation is not required to transform everything given to it right now. It is allowed to store incoming data in internal buffers and to defer the actual transformation until it has more data. 



 ### Write-related subcommands

 These subcommands are used for handling transformations applied to writable channels; though strictly **write** is optional, it must be supported if any of the others is or the channel will be made non-writable. 
 
*cmdPrefix* **flush** *handle*

 This optional subcommand is called whenever data in the transformation 'write' buffer has to be forced downward, i.e. towards the base channel. The result returned by the subcommand is taken as the binary data to write to the transformation below the current transformation. This can be the base channel as well.  In other words, when this subcommand is called the transformation cannot defer the actual transformation operation anymore and has to transform all data waiting in its internal write buffers and return the result of that action. 




*cmdPrefix* **write** *handle buffer*

 This subcommand, which must be present if the transformation is to work with writable channels, is called whenever the user, or a transformation above this transformation, writes data downward. The *buffer* contains the binary data which has been written to us. It is the responsibility of this subcommand to actually transform the data.  The result returned by the subcommand is taken as the binary data to write to the transformation below this transformation. This can be the base channel as well. Note that the result is allowed to be empty, or less than the data we got; the transformation is not required to transform everything which was written to it right now. It is allowed to store this data in internal buffers and to defer the actual transformation until it has more data. 



 See also
--------

 **[chan](chan.htm)**, **[refchan](refchan.htm)** Copyright © 2008 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/transchan.htm>

try
===

 Name
----

 try — Trap and process errors and exceptions Synopsis
--------

 **try** *body* ?*handler...*? ?**finally** *script*?  
 Description
-----------

 This command executes the script *body* and, depending on what the outcome of that script is (normal exit, error, or some other exceptional result), runs a handler script to deal with the case. Once that has all happened, if the **finally** clause is present, the *script* it includes will be run and the result of the handler (or the *body* if no handler matched) is allowed to continue to propagate. Note that the **finally** clause is processed even if an error occurs and irrespective of which, if any, *handler* is used.  The *handler* clauses are each expressed as several words, and must have one of the following forms: 


 
**on** *code variableList script*

 This clause matches if the evaluation of *body* completed with the exception code *code*. The *code* may be expressed as an integer or one of the following literal words: **ok**, **[error](error.htm)**, **[return](return.htm)**, **[break](break.htm)**, or **[continue](continue.htm)**. Those literals correspond to the integers 0 through 4 respectively. 


**trap** *pattern variableList script*

 This clause matches if the evaluation of *body* resulted in an error and the prefix of the **-errorcode** from the interpreter's status dictionary is equal to the *pattern*. The number of prefix words taken from the **-errorcode** is equal to the list-length of *pattern*, and inter-word spaces are normalized in both the **-errorcode** and *pattern* before comparison. 

  The *variableList* word in each *handler* is always interpreted as a list of variable names. If the first word of the list is present and non-empty, it names a variable into which the result of the evaluation of *body* (from the main **try**) will be placed; this will contain the human-readable form of any errors. If the second word of the list is present and non-empty, it names a variable into which the options dictionary of the interpreter at the moment of completion of execution of *body* will be placed. 


 The *script* word of each *handler* is also always interpreted the same: as a Tcl script to evaluate if the clause is matched. If *script* is a literal “-” and the *handler* is not the last one, the *script* of the following *handler* is invoked instead (just like with the **[switch](switch.htm)** command). 


 Note that *handler* clauses are matched against in order, and that the first matching one is always selected. At most one *handler* clause will selected. As a consequence, an **on error** will mask any subsequent **trap** in the **try**. Also note that **on error** is equivalent to **trap {}**. 


 If an exception (i.e. any non-**ok** result) occurs during the evaluation of either the *handler* or the **finally** clause, the original exception's status dictionary will be added to the new exception's status dictionary under the **-during** key. 


Examples
--------

 Ensure that a file is closed no matter what: 

```
set f [open /some/file/name a]
**try** {
    puts $f "some message"
    # ...
} **finally** {
    close $f
}
```
  Handle different reasons for a file to not be openable for reading: 



```
**try** {
    set f [open /some/file/name w]
} **trap** {POSIX EISDIR} {} {
    puts "failed to open /some/file/name: it's a directory"
} **trap** {POSIX ENOENT} {} {
    puts "failed to open /some/file/name: it doesn't exist"
}
```
 See also
--------

 **[catch](catch.htm)**, **[error](error.htm)**, **[return](return.htm)**, **[throw](throw.htm)** Copyright © 2008 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/try.htm>

class
=====

  
[NAME](class.htm#M2) oo::class — class of all classes 
[SYNOPSIS](class.htm#M3) 
[CLASS HIERARCHY](class.htm#M4) 
[DESCRIPTION](class.htm#M5) 
[CONSTRUCTOR](class.htm#M6) 
[DESTRUCTOR](class.htm#M7) 
[EXPORTED METHODS](class.htm#M8)  
[*cls* **create** *name* ?*arg ...*?](class.htm#M9) 
[*cls* **new** ?*arg ...*?](class.htm#M10) 

 
[NON-EXPORTED METHODS](class.htm#M11)  
[*cls* **createWithNamespace** *name nsName* ?*arg ...*?](class.htm#M12) 
 
[EXAMPLES](class.htm#M13) 
[SEE ALSO](class.htm#M14) 
[KEYWORDS](class.htm#M15) 










 Name
----

 oo::class — class of all classes Synopsis
--------

 package require TclOO  
   
 **oo::class** *method* ?*arg ...*?  
 Class hierarchy
---------------

 **[oo::object](object.htm)**  
 → **oo::class**  
 Description
-----------

 Classes are objects that can manufacture other objects according to a pattern stored in the factory object (the class). An instance of the class is created by calling one of the class's factory methods, typically either **create** if an explicit name is being given, or **new** if an arbitrary unique name is to be automatically selected.  The **oo::class** class is the class of all classes; every class is an instance of this class, which is consequently an instance of itself. This class is a subclass of **[oo::object](object.htm)**, so every class is also an object. Additional metaclasses (i.e., classes of classes) can be defined if necessary by subclassing **oo::class**. Note that the **oo::class** object hides the **new** method on itself, so new classes should always be made using the **create** method. 


### Constructor

 The constructor of the **oo::class** class takes an optional argument which, if present, is sent to the **[oo::define](define.htm)** command (along with the name of the newly-created class) to allow the class to be conveniently configured at creation time. ### Destructor

 The **oo::class** class does not define an explicit destructor. However, when a class is destroyed, all its subclasses and instances are also destroyed, along with all objects that it has been mixed into. ### Exported methods

  
*cls* **create** *name* ?*arg ...*?
 This creates a new instance of the class *cls* called *name* (which is resolved within the calling context's namespace if not fully qualified), passing the arguments, *arg ...*, to the constructor, and (if that returns a successful result) returning the fully qualified name of the created object (the result of the constructor is ignored). If the constructor fails (i.e. returns a non-OK result) then the object is destroyed and the error message is the result of this method call. 


*cls* **new** ?*arg ...*?
 This creates a new instance of the class *cls* with a new unique name, passing the arguments, *arg ...*, to the constructor, and (if that returns a successful result) returning the fully qualified name of the created object (the result of the constructor is ignored). If the constructor fails (i.e., returns a non-OK result) then the object is destroyed and the error message is the result of this method call.  Note that this method is not exported by the **oo::class** object itself, so classes should not be created using this method. 



 ### Non-exported methods

 The **oo::class** class supports the following non-exported methods: 
 
*cls* **createWithNamespace** *name nsName* ?*arg ...*?
 This creates a new instance of the class *cls* called *name* (which is resolved within the calling context's namespace if not fully qualified), passing the arguments, *arg ...*, to the constructor, and (if that returns a successful result) returning the fully qualified name of the created object (the result of the constructor is ignored). The name of the instance's internal namespace will be *nsName* unless that namespace already exists (when an arbitrary name will be chosen instead). If the constructor fails (i.e., returns a non-OK result) then the object is destroyed and the error message is the result of this method call. 

 Examples
--------

 This example defines a simple class hierarchy and creates a new instance of it. It then invokes a method of the object before destroying the hierarchy and showing that the destruction is transitive. 

```
**oo::class create** fruit {
    method eat {} {
        puts "yummy!"
    }
}
**oo::class create** banana {
    superclass fruit
    constructor {} {
        my variable peeled
        set peeled 0
    }
    method peel {} {
        my variable peeled
        set peeled 1
        puts "skin now off"
    }
    method edible? {} {
        my variable peeled
        return $peeled
    }
    method eat {} {
        if {![my edible?]} {
            my peel
        }
        next
    }
}
set b [banana **new**]
$b eat               *→ prints "skin now off" and "yummy!"*
fruit destroy
$b eat               *→ error "unknown command"*
```
 See also
--------

 **[oo::define](define.htm)**, **[oo::object](object.htm)** Copyright © 2007 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/class.htm>

text
====

  
[NAME](text.htm#M2) text, tk\_textCopy, tk\_textCut, tk\_textPaste — Create and manipulate 'text' hypertext editing widgets 
[SYNOPSIS](text.htm#M3) 
[STANDARD OPTIONS](text.htm#M4)  
[-background or -bg, background, Background](options.htm#M-background) 
[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth) 
[-cursor, cursor, Cursor](options.htm#M-cursor) 
[-exportselection, exportSelection, ExportSelection](options.htm#M-exportselection) 
[-font, font, Font](options.htm#M-font) 
[-foreground or -fg, foreground, Foreground](options.htm#M-foreground) 
[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground) 
[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor) 
[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness) 
[-insertbackground, insertBackground, Foreground](options.htm#M-insertbackground) 
[-insertborderwidth, insertBorderWidth, BorderWidth](options.htm#M-insertborderwidth) 
[-insertofftime, insertOffTime, OffTime](options.htm#M-insertofftime) 
[-insertontime, insertOnTime, OnTime](options.htm#M-insertontime) 
[-insertwidth, insertWidth, InsertWidth](options.htm#M-insertwidth) 
[-padx, padX, Pad](options.htm#M-padx) 
[-pady, padY, Pad](options.htm#M-pady) 
[-relief, relief, Relief](options.htm#M-relief) 
[-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground) 
[-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth) 
[-selectforeground, selectForeground, Background](options.htm#M-selectforeground) 
[-setgrid, setGrid, SetGrid](options.htm#M-setgrid) 
[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus) 
[-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand) 
[-yscrollcommand, yScrollCommand, ScrollCommand](options.htm#M-yscrollcommand) 























 
[WIDGET-SPECIFIC OPTIONS](text.htm#M5)  
[-autoseparators, autoSeparators, AutoSeparators](text.htm#M6) 
[-blockcursor, blockCursor, BlockCursor](text.htm#M7) 
[-endline, endLine, EndLine](text.htm#M8) 
[-height, height, Height](text.htm#M9) 
[-inactiveselectbackground, inactiveSelectBackground, Foreground](text.htm#M10) 
[-insertunfocussed, insertUnfocussed, InsertUnfocussed](text.htm#M11) 
[-maxundo, maxUndo, MaxUndo](text.htm#M12) 
[-spacing1, spacing1, Spacing1](text.htm#M13) 
[-spacing2, spacing2, Spacing2](text.htm#M14) 
[-spacing3, spacing3, Spacing3](text.htm#M15) 
[-startline, startLine, StartLine](text.htm#M16) 
[-state, state, State](text.htm#M17) 
[-tabs, tabs, Tabs](text.htm#M18) 
[-tabstyle, tabStyle, TabStyle](text.htm#M19) 
[-undo, undo, Undo](text.htm#M20) 
[-width, width, Width](text.htm#M21) 
[-wrap, wrap, Wrap](text.htm#M22) 
















 
[DESCRIPTION](text.htm#M23) 
[INDICES](text.htm#M24)  
[*line***.***char*](text.htm#M25) 
[**@***x***,***y*](text.htm#M26) 
[**end**](text.htm#M27) 
[*mark*](text.htm#M28) 
[*tag***.first**](text.htm#M29) 
[*tag***.last**](text.htm#M30) 
[*pathName*](text.htm#M31) 
[*imageName*](text.htm#M32) 







  
[**+** *count* ?*submodifier*? **chars**](text.htm#M33) 
[**-** *count* ?*submodifier*? **chars**](text.htm#M34) 
[**+** *count* ?*submodifier*? **indices**](text.htm#M35) 
[**-** *count* ?*submodifier*? **indices**](text.htm#M36) 
[**+** *count* ?*submodifier*? **lines**](text.htm#M37) 
[**-** *count* ?*submodifier*? **lines**](text.htm#M38) 
[?*submodifier*? **linestart**](text.htm#M39) 
[?*submodifier*? **lineend**](text.htm#M40) 
[?*submodifier*? **wordstart**](text.htm#M41) 
[?*submodifier*? **wordend**](text.htm#M42) 









 
[TAGS](text.htm#M43)  
[**-background** *color*](text.htm#M44) 
[**-bgstipple** *bitmap*](text.htm#M45) 
[**-borderwidth** *pixels*](text.htm#M46) 
[**-elide** *boolean*](text.htm#M47) 
[**-fgstipple** *bitmap*](text.htm#M48) 
[**-font** *fontName*](text.htm#M49) 
[**-foreground** *color*](text.htm#M50) 
[**-justify** *justify*](text.htm#M51) 
[**-lmargin1** *pixels*](text.htm#M52) 
[**-lmargin2** *pixels*](text.htm#M53) 
[**-lmargincolor** *color*](text.htm#M54) 
[**-offset** *pixels*](text.htm#M55) 
[**-overstrike** *boolean*](text.htm#M56) 
[**-overstrikefg** *color*](text.htm#M57) 
[**-relief** *relief*](text.htm#M58) 
[**-rmargin** *pixels*](text.htm#M59) 
[**-rmargincolor** *color*](text.htm#M60) 
[**-selectbackground** *color*](text.htm#M61) 
[**-selectforeground** *color*](text.htm#M62) 
[**-spacing1** *pixels*](text.htm#M63) 
[**-spacing2** *pixels*](text.htm#M64) 
[**-spacing3** *pixels*](text.htm#M65) 
[**-tabs** *tabList*](text.htm#M66) 
[**-tabstyle** *style*](text.htm#M67) 
[**-underline** *boolean*](text.htm#M68) 
[**-underlinefg** *color*](text.htm#M69) 
[**-wrap** *mode*](text.htm#M70) 


























 
[MARKS](text.htm#M71) 
[EMBEDDED WINDOWS](text.htm#M72)  
[**-align** *where*](text.htm#M73) 
[**-create** *script*](text.htm#M74) 
[**-padx** *pixels*](text.htm#M75) 
[**-pady** *pixels*](text.htm#M76) 
[**-stretch** *boolean*](text.htm#M77) 
[**-window** *pathName*](text.htm#M78) 





 
[EMBEDDED IMAGES](text.htm#M79)  
[**-align** *where*](text.htm#M80) 
[**-image** *image*](text.htm#M81) 
[**-name** *ImageName*](text.htm#M82) 
[**-padx** *pixels*](text.htm#M83) 
[**-pady** *pixels*](text.htm#M84) 




 
[THE SELECTION](text.htm#M85) 
[THE INSERTION CURSOR](text.htm#M86) 
[THE MODIFIED FLAG](text.htm#M87) 
[THE UNDO MECHANISM](text.htm#M88) 
[PEER WIDGETS](text.htm#M89) 
[ASYNCHRONOUS UPDATE OF LINE HEIGHTS](text.htm#M90) 
[WIDGET COMMAND](text.htm#M91)  
[*pathName* **bbox** *index*](text.htm#M92) 
[*pathName* **cget** *option*](text.htm#M93) 
[*pathName* **compare** *index1 op index2*](text.htm#M94) 
[*pathName* **configure** ?*option*? *?value option value ...*?](text.htm#M95) 
[*pathName* **count** *?options*? *index1 index2*](text.htm#M96)  
[**-chars**](text.htm#M97) 
[**-displaychars**](text.htm#M98) 
[**-displayindices**](text.htm#M99) 
[**-displaylines**](text.htm#M100) 
[**-indices**](text.htm#M101) 
[**-lines**](text.htm#M102) 
[**-xpixels**](text.htm#M103) 
[**-ypixels**](text.htm#M104) 







 
[*pathName* **debug** ?*boolean*?](text.htm#M105) 
[*pathName* **delete** *index1* ?*index2 ...*?](text.htm#M106) 
[*pathName* **dlineinfo** *index*](text.htm#M107) 
[*pathName* **dump** ?*switches*? *index1* ?*index2*?](text.htm#M108)  
[**-all**](text.htm#M109) 
[**-command** *command*](text.htm#M110) 
[**-image**](text.htm#M111) 
[**-mark**](text.htm#M112) 
[**-tag**](text.htm#M113) 
[**-text**](text.htm#M114) 
[**-window**](text.htm#M115) 






 
[*pathName* **edit** *option* ?*arg arg ...*?](text.htm#M116)  
[*pathName* **edit canredo**](text.htm#M117) 
[*pathName* **edit canundo**](text.htm#M118) 
[*pathName* **edit modified** ?*boolean*?](text.htm#M119) 
[*pathName* **edit redo**](text.htm#M120) 
[*pathName* **edit reset**](text.htm#M121) 
[*pathName* **edit separator**](text.htm#M122) 
[*pathName* **edit undo**](text.htm#M123) 






 
[*pathName* **get** ?**-displaychars**? ?**--**? *index1* ?*index2 ...*?](text.htm#M124) 
[*pathName* **image** *option* ?*arg arg ...*?](text.htm#M125)  
[*pathName* **image cget** *index option*](text.htm#M126) 
[*pathName* **image configure** *index* ?*option value ...*?](text.htm#M127) 
[*pathName* **image create** *index* ?*option value ...*?](text.htm#M128) 
[*pathName* **image names**](text.htm#M129) 



 
[*pathName* **index** *index*](text.htm#M130) 
[*pathName* **insert** *index chars* ?*tagList chars tagList ...*?](text.htm#M131) 
[*pathName* **mark** *option* ?*arg arg ...*?](text.htm#M132)  
[*pathName* **mark gravity** *markName* ?*direction*?](text.htm#M133) 
[*pathName* **mark names**](text.htm#M134) 
[*pathName* **mark next** *index*](text.htm#M135) 
[*pathName* **mark previous** *index*](text.htm#M136) 
[*pathName* **mark set** *markName index*](text.htm#M137) 
[*pathName* **mark unset** *markName* ?*markName markName ...*?](text.htm#M138) 





 
[*pathName* **peer** *option args*](text.htm#M139)  
[*pathName* **peer create** *newPathName* ?*options*?](text.htm#M140) 
[*pathName* **peer names**](text.htm#M141) 

 
[*pathName* **pendingsync**](text.htm#M142) 
[*pathName* **replace** *index1 index2 chars* ?*tagList chars tagList ...*?](text.htm#M143) 
[*pathName* **scan** *option args*](text.htm#M144)  
[*pathName* **scan mark** *x y*](text.htm#M145) 
[*pathName* **scan dragto** *x y*](text.htm#M146) 

 
[*pathName* **search** ?*switches*? *pattern index* ?*stopIndex*?](text.htm#M147)  
[**-forwards**](text.htm#M148) 
[**-backwards**](text.htm#M149) 
[**-exact**](text.htm#M150) 
[**-regexp**](text.htm#M151) 
[**-nolinestop**](text.htm#M152) 
[**-nocase**](text.htm#M153) 
[**-count** *varName*](text.htm#M154) 
[**-all**](text.htm#M155) 
[**-overlap**](text.htm#M156) 
[**-strictlimits**](text.htm#M157) 
[**-elide**](text.htm#M158) 
[**--**](text.htm#M159) 











 
[*pathName* **see** *index*](text.htm#M160) 
[*pathName* **sync** ?**-command** *command*?](text.htm#M161)  
[*pathName* **sync**](text.htm#M162) 
[*pathName* **sync -command** *command*](text.htm#M163) 

 
[*pathName* **tag** *option* ?*arg arg ...*?](text.htm#M164)  
[*pathName* **tag add** *tagName index1* ?*index2 index1 index2 ...*?](text.htm#M165) 
[*pathName* **tag bind** *tagName* ?*sequence*? ?*script*?](text.htm#M166) 
[*pathName* **tag cget** *tagName option*](text.htm#M167) 
[*pathName* **tag configure** *tagName* ?*option*? ?*value*? ?*option value ...*?](text.htm#M168) 
[*pathName* **tag delete** *tagName* ?*tagName ...*?](text.htm#M169) 
[*pathName* **tag lower** *tagName* ?*belowThis*?](text.htm#M170) 
[*pathName* **tag names** ?*index*?](text.htm#M171) 
[*pathName* **tag nextrange** *tagName index1* ?*index2*?](text.htm#M172) 
[*pathName* **tag prevrange** *tagName index1* ?*index2*?](text.htm#M173) 
[*pathName* **tag raise** *tagName* ?*aboveThis*?](text.htm#M174) 
[*pathName* **tag ranges** *tagName*](text.htm#M175) 
[*pathName* **tag remove** *tagName index1* ?*index2 index1 index2 ...*?](text.htm#M176) 











 
[*pathName* **window** *option* ?*arg arg ...*?](text.htm#M177)  
[*pathName* **window cget** *index option*](text.htm#M178) 
[*pathName* **window configure** *index* ?*option value ...*?](text.htm#M179) 
[*pathName* **window create** *index* ?*option value ...*?](text.htm#M180) 
[*pathName* **window names**](text.htm#M181) 



 
[*pathName* **xview** *option args*](text.htm#M182)  
[*pathName* **xview**](text.htm#M183) 
[*pathName* **xview moveto** *fraction*](text.htm#M184) 
[*pathName* **xview scroll** *number what*](text.htm#M185) 


 
[*pathName* **yview** ?*args*?](text.htm#M186)  
[*pathName* **yview**](text.htm#M187) 
[*pathName* **yview moveto** *fraction*](text.htm#M188) 
[*pathName* **yview scroll** *number what*](text.htm#M189) 
[*pathName* **yview** ?**-pickplace**? *index*](text.htm#M190) 
[*pathName* **yview** *number*](text.htm#M191) 




 

























 
[BINDINGS](text.htm#M192) 
[KNOWN ISSUES](text.htm#M193) 
[ISSUES CONCERNING CHARS AND INDICES](text.htm#M194) 
[PERFORMANCE ISSUES](text.htm#M195) 
[KNOWN BUGS](text.htm#M196) 
[SEE ALSO](text.htm#M197) 
[KEYWORDS](text.htm#M198) 























 Name
----

 text, tk\_textCopy, tk\_textCut, tk\_textPaste — Create and manipulate 'text' hypertext editing widgets Synopsis
--------

 **text** *pathName* ?*options*?  
 **tk\_textCopy** *pathName*  
 **tk\_textCut** *pathName*  
 **tk\_textPaste** *pathName*  
 Standard options
----------------

  
**[-background or -bg, background, Background](options.htm#M-background)** 
**[-borderwidth or -bd, borderWidth, BorderWidth](options.htm#M-borderwidth)** 
**[-cursor, cursor, Cursor](options.htm#M-cursor)** 
**[-exportselection, exportSelection, ExportSelection](options.htm#M-exportselection)** 
**[-font, font, Font](options.htm#M-font)** 
**[-foreground or -fg, foreground, Foreground](options.htm#M-foreground)** 
**[-highlightbackground, highlightBackground, HighlightBackground](options.htm#M-highlightbackground)** 
**[-highlightcolor, highlightColor, HighlightColor](options.htm#M-highlightcolor)** 
**[-highlightthickness, highlightThickness, HighlightThickness](options.htm#M-highlightthickness)** 
**[-insertbackground, insertBackground, Foreground](options.htm#M-insertbackground)** 
**[-insertborderwidth, insertBorderWidth, BorderWidth](options.htm#M-insertborderwidth)** 
**[-insertofftime, insertOffTime, OffTime](options.htm#M-insertofftime)** 
**[-insertontime, insertOnTime, OnTime](options.htm#M-insertontime)** 
**[-insertwidth, insertWidth, InsertWidth](options.htm#M-insertwidth)** 
**[-padx, padX, Pad](options.htm#M-padx)** 
**[-pady, padY, Pad](options.htm#M-pady)** 
**[-relief, relief, Relief](options.htm#M-relief)** 
**[-selectbackground, selectBackground, Foreground](options.htm#M-selectbackground)** 
**[-selectborderwidth, selectBorderWidth, BorderWidth](options.htm#M-selectborderwidth)** 
**[-selectforeground, selectForeground, Background](options.htm#M-selectforeground)** 
**[-setgrid, setGrid, SetGrid](options.htm#M-setgrid)** 
**[-takefocus, takeFocus, TakeFocus](options.htm#M-takefocus)** 
**[-xscrollcommand, xScrollCommand, ScrollCommand](options.htm#M-xscrollcommand)** 
**[-yscrollcommand, yScrollCommand, ScrollCommand](options.htm#M-yscrollcommand)** 























 Widget-specific options
-----------------------

  Command-Line Name: **-autoseparators** Database Name: **autoSeparators** Database Class: **AutoSeparators** 


Specifies a boolean that says whether separators are automatically inserted in the undo stack. Only meaningful when the **-undo** option is true. 

Command-Line Name: **-blockcursor** Database Name: **blockCursor** Database Class: **BlockCursor** 


Specifies a boolean that says whether the blinking insertion cursor should be drawn as a character-sized rectangular block. If false (the default) a thin vertical line is used for the insertion cursor. 

Command-Line Name: **-endline** Database Name: **endLine** Database Class: **EndLine** 


Specifies an integer line index representing the line of the underlying textual data store that should be just after the last line contained in the widget. This allows a text widget to reflect only a portion of a larger piece of text. Instead of an integer, the empty string can be provided to this configuration option, which will configure the widget to end at the very last line in the textual data store. 

Command-Line Name: **-height** Database Name: **height** Database Class: **Height** 


Specifies the desired height for the window, in units of characters in the font given by the **-font** option. Must be at least one. 

Command-Line Name: **-inactiveselectbackground** Database Name: **inactiveSelectBackground** Database Class: **Foreground** 


Specifies the colour to use for the selection (the **sel** tag) when the window does not have the input focus. If empty, **{}**, then no selection is shown when the window does not have the focus. 

Command-Line Name: **-insertunfocussed** Database Name: **insertUnfocussed** Database Class: **InsertUnfocussed** 


Specifies how to display the insertion cursor when the widget does not have the focus. Must be **none** (the default) which means to not display the cursor, **hollow** which means to display a hollow box, or **solid** which means to display a solid box. Note that **hollow** and **solid** will appear very similar when the **-blockcursor** option is false. 

Command-Line Name: **-maxundo** Database Name: **maxUndo** Database Class: **MaxUndo** 


Specifies the maximum number of compound undo actions on the undo stack. A zero or a negative value imply an unlimited undo stack. 

Command-Line Name: **-spacing1** Database Name: **spacing1** Database Class: **Spacing1** 


Requests additional space above each text line in the widget, using any of the standard forms for screen distances. If a line wraps, this option only applies to the first line on the display. This option may be overridden with **-spacing1** options in tags. 

Command-Line Name: **-spacing2** Database Name: **spacing2** Database Class: **Spacing2** 


For lines that wrap (so that they cover more than one line on the display) this option specifies additional space to provide between the display lines that represent a single line of text. The value may have any of the standard forms for screen distances. This option may be overridden with **-spacing2** options in tags. 

Command-Line Name: **-spacing3** Database Name: **spacing3** Database Class: **Spacing3** 


Requests additional space below each text line in the widget, using any of the standard forms for screen distances. If a line wraps, this option only applies to the last line on the display. This option may be overridden with **-spacing3** options in tags. 

Command-Line Name: **-startline** Database Name: **startLine** Database Class: **StartLine** 


Specifies an integer line index representing the first line of the underlying textual data store that should be contained in the widget. This allows a text widget to reflect only a portion of a larger piece of text. Instead of an integer, the empty string can be provided to this configuration option, which will configure the widget to start at the very first line in the textual data store. 

Command-Line Name: **-state** Database Name: **state** Database Class: **State** 


Specifies one of two states for the text: **normal** or **disabled**. If the text is disabled then characters may not be inserted or deleted and no insertion cursor will be displayed, even if the input focus is in the widget. 

Command-Line Name: **-tabs** Database Name: **tabs** Database Class: **Tabs** 


Specifies a set of tab stops for the window. The option's value consists of a list of screen distances giving the positions of the tab stops, each of which is a distance relative to the left edge of the widget (excluding borders, padding, etc). Each position may optionally be followed in the next list element by one of the keywords **left**, **right**, **center**, or **numeric**, which specifies how to justify text relative to the tab stop. **Left** is the default; it causes the text following the tab character to be positioned with its left edge at the tab position. **Right** means that the right edge of the text following the tab character is positioned at the tab position, and **center** means that the text is centered at the tab position. **Numeric** means that the decimal point in the text is positioned at the tab position; if there is no decimal point then the least significant digit of the number is positioned just to the left of the tab position; if there is no number in the text then the text is right-justified at the tab position. For example, “**-tabs {2c left 4c 6c center}**” creates three tab stops at two-centimeter intervals; the first two use left justification and the third uses center justification.  If the list of tab stops does not have enough elements to cover all of the tabs in a text line, then Tk extrapolates new tab stops using the spacing and alignment from the last tab stop in the list. Tab distances must be strictly positive, and must always increase from one tab stop to the next (if not, an error is thrown). The value of the **-tabs** option may be overridden by **-tabs** options in tags. 


 If no **-tabs** option is specified, or if it is specified as an empty list, then Tk uses default tabs spaced every eight (average size) characters. To achieve a different standard spacing, for example every 4 characters, simply configure the widget with “**-tabs "[expr {4 \* [font measure $font 0]}] left" -tabstyle wordprocessor**”. 



Command-Line Name: **-tabstyle** Database Name: **tabStyle** Database Class: **TabStyle** 


Specifies how to interpret the relationship between tab stops on a line and tabs in the text of that line. The value must be **tabular** (the default) or **wordprocessor**. Note that tabs are interpreted as they are encountered in the text. If the tab style is **tabular** then the *n*'th tab character in the line's text will be associated with the *n*'th tab stop defined for that line. If the tab character's x coordinate falls to the right of the *n*'th tab stop, then a gap of a single space will be inserted as a fallback. If the tab style is **wordprocessor** then any tab character being laid out will use (and be defined by) the first tab stop to the right of the preceding characters already laid out on that line. The value of the **-tabstyle** option may be overridden by **-tabstyle** options in tags. 

Command-Line Name: **-undo** Database Name: **undo** Database Class: **Undo** 


Specifies a boolean that says whether the undo mechanism is active or not. 

Command-Line Name: **-width** Database Name: **width** Database Class: **Width** 


Specifies the desired width for the window in units of characters in the font given by the **-font** option. If the font does not have a uniform width then the width of the character “0” is used in translating from character units to screen units. 

Command-Line Name: **-wrap** Database Name: **wrap** Database Class: **Wrap** 


Specifies how to handle lines in the text that are too long to be displayed in a single line of the text's window. The value must be **none** or **char** or **word**. A wrap mode of **none** means that each line of text appears as exactly one line on the screen; extra characters that do not fit on the screen are not displayed. In the other modes each line of text will be broken up into several screen lines if necessary to keep all the characters visible. In **char** mode a screen line break may occur after any character; in **word** mode a line break will only be made at word boundaries. 
 Description
-----------

 The **text** command creates a new window (given by the *pathName* argument) and makes it into a text widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the text such as its default background color and relief. The **text** command returns the path name of the new window.  A text widget displays one or more lines of text and allows that text to be edited. Text widgets support four different kinds of annotations on the text, called tags, marks, embedded windows or embedded images. Tags allow different portions of the text to be displayed with different fonts and colors. In addition, Tcl commands can be associated with tags so that scripts are invoked when particular actions such as keystrokes and mouse button presses occur in particular ranges of the text. See **[TAGS](#M43)** below for more details. 


 The second form of annotation consists of floating markers in the text called “marks”. Marks are used to keep track of various interesting positions in the text as it is edited. See **[MARKS](#M71)** below for more details. 


 The third form of annotation allows arbitrary windows to be embedded in a text widget. See **[EMBEDDED WINDOWS](#M72)** below for more details. 


 The fourth form of annotation allows Tk images to be embedded in a text widget. See **[EMBEDDED IMAGES](#M79)** below for more details. 


 The text widget also has a built-in undo/redo mechanism. See **[THE UNDO MECHANISM](#M88)** below for more details. 


 The text widget allows for the creation of peer widgets. These are other text widgets which share the same underlying data (text, marks, tags, images, etc). See **[PEER WIDGETS](#M89)** below for more details. 


Indices
-------

 Many of the widget commands for texts take one or more indices as arguments. An index is a string used to indicate a particular place within a text, such as a place to insert characters or one endpoint of a range of characters to delete. Indices have the syntax 
```
*base modifier modifier modifier ...*
```
 Where *base* gives a starting point and the *modifier*s adjust the index from the starting point (e.g. move forward or backward one character). Every index must contain a *base*, but the *modifier*s are optional. Most modifiers (as documented below) allow an optional submodifier. Valid submodifiers are **any** and **display**. If the submodifier is abbreviated, then it must be followed by whitespace, but otherwise there need be no space between the submodifier and the following *modifier*. Typically the **display** submodifier adjusts the meaning of the following *modifier* to make it refer to visual or non-elided units rather than logical units, but this is explained for each relevant case below. Lastly, where *count* is used as part of a modifier, it can be positive or negative, so “*base* - -3 lines” is perfectly valid (and equivalent to “*base* +3lines”).  The *base* for an index must have one of the following forms: 


 
*line***.***char*

 Indicates *char*'th character on line *line*. Lines are numbered from 1 for consistency with other UNIX programs that use this numbering scheme. Within a line, characters are numbered from 0. If *char* is **end** then it refers to the newline character that ends the line. 


**@***x***,***y*

 Indicates the character that covers the pixel whose x and y coordinates within the text's window are *x* and *y*. 

**end**
 Indicates the end of the text (the character just after the last newline). 

*mark*
 Indicates the character just after the mark whose name is *mark*. 


*tag***.first**

 Indicates the first character in the text that has been tagged with *tag*. This form generates an error if no characters are currently tagged with *tag*. 


*tag***.last**

 Indicates the character just after the last one in the text that has been tagged with *tag*. This form generates an error if no characters are currently tagged with *tag*. 

*pathName*
 Indicates the position of the embedded window whose name is *pathName*. This form generates an error if there is no embedded window by the given name. 

*imageName*
 Indicates the position of the embedded image whose name is *imageName*. This form generates an error if there is no embedded image by the given name. 

  If the *base* could match more than one of the above forms, such as a *mark* and *imageName* both having the same value, then the form earlier in the above list takes precedence. If modifiers follow the base index, each one of them must have one of the forms listed below. Keywords such as **chars** and **wordend** may be abbreviated as long as the abbreviation is unambiguous. 


 
**+** *count* ?*submodifier*? **chars**

 Adjust the index forward by *count* characters, moving to later lines in the text if necessary. If there are fewer than *count* characters in the text after the current index, then set the index to the last index in the text. Spaces on either side of *count* are optional. If the **display** submodifier is given, elided characters are skipped over without being counted. If **any** is given, then all characters are counted. For historical reasons, if neither modifier is given then the count actually takes place in units of index positions (see **[INDICES](#M24)** for details). This behaviour may be changed in a future major release, so if you need an index count, you are encouraged to use **indices** instead wherever possible. 


**-** *count* ?*submodifier*? **chars**

 Adjust the index backward by *count* characters, moving to earlier lines in the text if necessary. If there are fewer than *count* characters in the text before the current index, then set the index to the first index in the text (1.0). Spaces on either side of *count* are optional. If the **display** submodifier is given, elided characters are skipped over without being counted. If **any** is given, then all characters are counted. For historical reasons, if neither modifier is given then the count actually takes place in units of index positions (see **[INDICES](#M24)** for details). This behavior may be changed in a future major release, so if you need an index count, you are encouraged to use **indices** instead wherever possible. 


**+** *count* ?*submodifier*? **indices**

 Adjust the index forward by *count* index positions, moving to later lines in the text if necessary. If there are fewer than *count* index positions in the text after the current index, then set the index to the last index position in the text. Spaces on either side of *count* are optional. Note that an index position is either a single character or a single embedded image or embedded window. If the **display** submodifier is given, elided indices are skipped over without being counted. If **any** is given, then all indices are counted; this is also the default behaviour if no modifier is given. 


**-** *count* ?*submodifier*? **indices**

 Adjust the index backward by *count* index positions, moving to earlier lines in the text if necessary. If there are fewer than *count* index positions in the text before the current index, then set the index to the first index position (1.0) in the text. Spaces on either side of *count* are optional. If the **display** submodifier is given, elided indices are skipped over without being counted. If **any** is given, then all indices are counted; this is also the default behaviour if no modifier is given. 


**+** *count* ?*submodifier*? **lines**

 Adjust the index forward by *count* lines, retaining the same character position within the line. If there are fewer than *count* lines after the line containing the current index, then set the index to refer to the same character position on the last line of the text. Then, if the line is not long enough to contain a character at the indicated character position, adjust the character position to refer to the last character of the line (the newline). Spaces on either side of *count* are optional. If the **display** submodifier is given, then each visual display line is counted separately. Otherwise, if **any** (or no modifier) is given, then each logical line (no matter how many times it is visually wrapped) counts just once. If the relevant lines are not wrapped, then these two methods of counting are equivalent. 


**-** *count* ?*submodifier*? **lines**

 Adjust the index backward by *count* logical lines, retaining the same character position within the line. If there are fewer than *count* lines before the line containing the current index, then set the index to refer to the same character position on the first line of the text. Then, if the line is not long enough to contain a character at the indicated character position, adjust the character position to refer to the last character of the line (the newline). Spaces on either side of *count* are optional. If the **display** submodifier is given, then each visual display line is counted separately. Otherwise, if **any** (or no modifier) is given, then each logical line (no matter how many times it is visually wrapped) counts just once. If the relevant lines are not wrapped, then these two methods of counting are equivalent. 

?*submodifier*? **linestart**

 Adjust the index to refer to the first index on the line. If the **display** submodifier is given, this is the first index on the display line, otherwise on the logical line. 

?*submodifier*? **lineend**

 Adjust the index to refer to the last index on the line (the newline). If the **display** submodifier is given, this is the last index on the display line, otherwise on the logical line. 

?*submodifier*? **wordstart**

 Adjust the index to refer to the first character of the word containing the current index. A word consists of any number of adjacent characters that are letters, digits, or underscores, or a single character that is not one of these. If the **display** submodifier is given, this only examines non-elided characters, otherwise all characters (elided or not) are examined. 

?*submodifier*? **wordend**

 Adjust the index to refer to the character just after the last one of the word containing the current index. If the current index refers to the last character of the text then it is not modified. If the **display** submodifier is given, this only examines non-elided characters, otherwise all characters (elided or not) are examined. 

  If more than one modifier is present then they are applied in left-to-right order. For example, the index “**end - 1 chars**” refers to the next-to-last character in the text and “**insert wordstart - 1 c**” refers to the character just before the first one in the word containing the insertion cursor. Modifiers are applied one by one in this left to right order, and after each step the resulting index is constrained to be a valid index in the text widget. So, for example, the index “**1.0 -1c +1c**” refers to the index “**2.0**”. 


 Where modifiers result in index changes by display lines, display chars or display indices, and the *base* refers to an index inside an elided tag, that base index is considered to be equivalent to the first following non-elided index. 


Tags
----

 The first form of annotation in text widgets is a tag. A tag is a textual string that is associated with some of the characters in a text. Tags may contain arbitrary characters, but it is probably best to avoid using the characters “ ” (space), **+**, or **-**: these characters have special meaning in indices, so tags containing them cannot be used as indices. There may be any number of tags associated with characters in a text. Each tag may refer to a single character, a range of characters, or several ranges of characters. An individual character may have any number of tags associated with it.  A priority order is defined among tags, and this order is used in implementing some of the tag-related functions described below. When a tag is defined (by associating it with characters or setting its display options or binding commands to it), it is given a priority higher than any existing tag. The priority order of tags may be redefined using the “*pathName* **tag raise**” and “*pathName* **tag lower**” widget commands. 


 Tags serve three purposes in text widgets. First, they control the way information is displayed on the screen. By default, characters are displayed as determined by the **-background**, **-font**, and **-foreground** options for the text widget. However, display options may be associated with individual tags using the “*pathName* **tag configure**” widget command. If a character has been tagged, then the display options associated with the tag override the default display style. The following options are currently supported for tags: 


 
**-background** *color*

 *Color* specifies the background color to use for characters associated with the tag. It may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. 


**-bgstipple** *bitmap*

 *Bitmap* specifies a bitmap that is used as a stipple pattern for the background. It may have any of the forms accepted by **[Tk\_GetBitmap](https://www.tcl.tk/man/tcl/TkLib/GetBitmap.htm)**. If *bitmap* has not been specified, or if it is specified as an empty string, then a solid fill will be used for the background. 


**-borderwidth** *pixels*

 *Pixels* specifies the width of a border to draw around the tag using any of the forms accepted by **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**. This option should be used in conjunction with the **-relief** option to provide the desired border. 


**-elide** *boolean*

 *Elide* specifies whether the data should be elided. Elided data (characters, images, embedded windows, etc.) is not displayed and takes no space on screen, but further on behaves just as normal data. 


**-fgstipple** *bitmap*

 *Bitmap* specifies a bitmap that is used as a stipple pattern when drawing text and other foreground information such as underlines. It may have any of the forms accepted by **[Tk\_GetBitmap](https://www.tcl.tk/man/tcl/TkLib/GetBitmap.htm)**. If *bitmap* has not been specified, or if it is specified as an empty string, then a solid fill will be used. 


**-font** *fontName*

 *FontName* is the name of a font to use for drawing characters. It may have any of the forms accepted by **[Tk\_GetFont](https://www.tcl.tk/man/tcl/TkLib/GetFont.htm)**. 


**-foreground** *color*

 *Color* specifies the color to use when drawing text and other foreground information such as underlines. It may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. 


**-justify** *justify*

 If the first non-elided character of a display line has a tag for which this option has been specified, then *justify* determines how to justify the line. It must be one of **left**, **right**, or **center**. If a line wraps, then the justification for each line on the display is determined by the first non-elided character of that display line. 


**-lmargin1** *pixels*

 If the first non-elided character of a text line has a tag for which this option has been specified, then *pixels* specifies how much the line should be indented from the left edge of the window. *Pixels* may have any of the standard forms for screen distances. If a line of text wraps, this option only applies to the first line on the display; the **-lmargin2** option controls the indentation for subsequent lines. 


**-lmargin2** *pixels*

 If the first non-elided character of a display line has a tag for which this option has been specified, and if the display line is not the first for its text line (i.e., the text line has wrapped), then *pixels* specifies how much the line should be indented from the left edge of the window. *Pixels* may have any of the standard forms for screen distances. This option is only used when wrapping is enabled, and it only applies to the second and later display lines for a text line. 


**-lmargincolor** *color*

 *Color* specifies the background color to use in regions that do not contain characters because they are indented by **-lmargin1** or **-lmargin2**. It may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**.If *color* has not been specified, or if it is specified as an empty string, then the color specified by the **-background** widget option is used. 


**-offset** *pixels*

 *Pixels* specifies an amount by which the text's baseline should be offset vertically from the baseline of the overall line, in pixels. For example, a positive offset can be used for superscripts and a negative offset can be used for subscripts. *Pixels* may have any of the standard forms for screen distances. 


**-overstrike** *boolean*

 Specifies whether or not to draw a horizontal rule through the middle of characters. *Boolean* may have any of the forms accepted by **[Tcl\_GetBoolean](https://www.tcl.tk/man/tcl/TclLib/GetInt.htm)**. 


**-overstrikefg** *color*

 *Color* specifies the color to use when displaying the overstrike. It may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. If *color* has not been specified, or if it is specified as an empty string, then the color specified by the **-foreground** tag option is used. 


**-relief** *relief*

 *Relief* specifies the relief style to use for drawing the border, in any of the forms accepted by **[Tk\_GetRelief](https://www.tcl.tk/man/tcl/TkLib/GetRelief.htm)**. This option is used in conjunction with the **-borderwidth** option to enable to the desired border appearance. 


**-rmargin** *pixels*

 If the first non-elided character of a display line has a tag for which this option has been specified, then *pixels* specifies how wide a margin to leave between the end of the line and the right edge of the window. *Pixels* may have any of the standard forms for screen distances. This option is only used when wrapping is enabled. If a text line wraps, the right margin for each line on the display is determined by the first non-elided character of that display line. 


**-rmargincolor** *color*

 *Color* specifies the background color to use in regions that do not contain characters because they are indented by **-rmargin1**. It may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**.If *color* has not been specified, or if it is specified as an empty string, then the color specified by the **-background** widget option is used. 


**-selectbackground** *color*

 *Color* specifies the background color to use when displaying selected items. It may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. If *color* has not been specified, or if it is specified as an empty string, then the color specified by the **-background** tag option is used. 


**-selectforeground** *color*

 *Color* specifies the foreground color to use when displaying selected items. It may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. If *color* has not been specified, or if it is specified as an empty string, then the color specified by the **-foreground** tag option is used. 


**-spacing1** *pixels*

 *Pixels* specifies how much additional space should be left above each text line, using any of the standard forms for screen distances. If a line wraps, this option only applies to the first line on the display. 


**-spacing2** *pixels*

 For lines that wrap, this option specifies how much additional space to leave between the display lines for a single text line. *Pixels* may have any of the standard forms for screen distances. 


**-spacing3** *pixels*

 *Pixels* specifies how much additional space should be left below each text line, using any of the standard forms for screen distances. If a line wraps, this option only applies to the last line on the display. 


**-tabs** *tabList*

 *TabList* specifies a set of tab stops in the same form as for the **-tabs** option for the text widget. This option only applies to a display line if it applies to the first non-elided character on that display line. If this option is specified as an empty string, it cancels the option, leaving it unspecified for the tag (the default). If the option is specified as a non-empty string that is an empty list, such as **-tags { }**, then it requests default 8-character tabs as described for the **-tags** widget option. 


**-tabstyle** *style*

 *Style* specifies either the *tabular* or *wordprocessor* style of tabbing to use for the text widget. This option only applies to a display line if it applies to the first non-elided character on that display line. If this option is specified as an empty string, it cancels the option, leaving it unspecified for the tag (the default). 


**-underline** *boolean*

 *Boolean* specifies whether or not to draw an underline underneath characters. It may have any of the forms accepted by **[Tcl\_GetBoolean](https://www.tcl.tk/man/tcl/TclLib/GetInt.htm)**. 


**-underlinefg** *color*

 *Color* specifies the color to use when displaying the underline. It may have any of the forms accepted by **[Tk\_GetColor](https://www.tcl.tk/man/tcl/TkLib/GetColor.htm)**. If *color* has not been specified, or if it is specified as an empty string, then the color specified by the **-foreground** tag option is used. 


**-wrap** *mode*

 *Mode* specifies how to handle lines that are wider than the text's window. It has the same legal values as the **-wrap** option for the text widget: **none**, **char**, or **word**. If this tag option is specified, it overrides the **-wrap** option for the text widget. 

  If a character has several tags associated with it, and if their display options conflict, then the options of the highest priority tag are used. If a particular display option has not been specified for a particular tag, or if it is specified as an empty string, then that option will never be used; the next-highest-priority tag's option will used instead. If no tag specifies a particular display option, then the default style for the widget will be used. 


 The second purpose for tags is event bindings. You can associate bindings with a tag in much the same way you can associate bindings with a widget class: whenever particular X events occur on characters with the given tag, a given Tcl command will be executed. Tag bindings can be used to give behaviors to ranges of characters; among other things, this allows hypertext-like features to be implemented. For details, see the description of the “*pathName* **tag bind**” widget command below. Tag bindings are shared between all peer widgets (including any bindings for the special **sel** tag). 


 The third use for tags is in managing the selection. See **[THE SELECTION](#M85)** below. With the exception of the special **sel** tag, all tags are shared between peer text widgets, and may be manipulated on an equal basis from any such widget. The **sel** tag exists separately and independently in each peer text widget (but any tag bindings to **sel** are shared). 


Marks
-----

 The second form of annotation in text widgets is a mark. Marks are used for remembering particular places in a text. They are something like tags, in that they have names and they refer to places in the file, but a mark is not associated with particular characters. Instead, a mark is associated with the gap between two characters. Only a single position may be associated with a mark at any given time. If the characters around a mark are deleted the mark will still remain; it will just have new neighbor characters. In contrast, if the characters containing a tag are deleted then the tag will no longer have an association with characters in the file. Marks may be manipulated with the “*pathName* **mark**” widget command, and their current locations may be determined by using the mark name as an index in widget commands.  Each mark also has a “gravity”, which is either **left** or **right**. The gravity for a mark specifies what happens to the mark when text is inserted at the point of the mark. If a mark has left gravity, then the mark is treated as if it were attached to the character on its left, so the mark will remain to the left of any text inserted at the mark position. If the mark has right gravity, new text inserted at the mark position will appear to the left of the mark (so that the mark remains rightmost). The gravity for a mark defaults to **right**. 


 The name space for marks is different from that for tags: the same name may be used for both a mark and a tag, but they will refer to different things. 


 Two marks have special significance. First, the mark **insert** is associated with the insertion cursor, as described under **[THE INSERTION CURSOR](#M86)** below. Second, the mark **current** is associated with the character closest to the mouse and is adjusted automatically to track the mouse position and any changes to the text in the widget (one exception: **current** is not updated in response to mouse motions if a mouse button is down; the update will be deferred until all mouse buttons have been released). Neither of these special marks may be deleted. With the exception of these two special marks, all marks are shared between peer text widgets, and may be manipulated on an equal basis from any peer. 


Embedded windows
----------------

 The third form of annotation in text widgets is an embedded window. Each embedded window annotation causes a window to be displayed at a particular point in the text. There may be any number of embedded windows in a text widget, and any widget may be used as an embedded window (subject to the usual rules for geometry management, which require the text window to be the parent of the embedded window or a descendant of its parent).  The embedded window's position on the screen will be updated as the text is modified or scrolled, and it will be mapped and unmapped as it moves into and out of the visible area of the text widget. Each embedded window occupies one unit's worth of index space in the text widget, and it may be referred to either by the name of its embedded window or by its position in the widget's index space. If the range of text containing the embedded window is deleted then the window is destroyed. Similarly if the text widget as a whole is deleted, then the window is destroyed. 


 Eliding an embedded window immediately after scheduling it for creation via *pathName* **window create** *index* **-create** will prevent it from being effectively created. Uneliding an elided embedded window scheduled for creation via *pathName* **window create** *index* **-create** will automatically trigger the associated creation script. After destroying an elided embedded window, the latter won't get automatically recreated. 


 When an embedded window is added to a text widget with the *pathName* **window create** widget command, several configuration options may be associated with it. These options may be modified later with the *pathName* **window configure** widget command. The following options are currently supported: 


 
**-align** *where*

 If the window is not as tall as the line in which it is displayed, this option determines where the window is displayed in the line. *Where* must have one of the values **top** (align the top of the window with the top of the line), **center** (center the window within the range of the line), **bottom** (align the bottom of the window with the bottom of the line's area), or **baseline** (align the bottom of the window with the baseline of the line). 


**-create** *script*

 Specifies a Tcl script that may be evaluated to create the window for the annotation. If no **-window** option has been specified for the annotation this script will be evaluated when the annotation is about to be displayed on the screen. *Script* must create a window for the annotation and return the name of that window as its result. Two substitutions will be performed in *script* before evaluation. *%W* will be substituted by the name of the parent text widget, and *%%* will be substituted by a single *%*. If the annotation's window should ever be deleted, *script* will be evaluated again the next time the annotation is displayed. 


**-padx** *pixels*

 *Pixels* specifies the amount of extra space to leave on each side of the embedded window. It may have any of the usual forms defined for a screen distance. 


**-pady** *pixels*

 *Pixels* specifies the amount of extra space to leave on the top and on the bottom of the embedded window. It may have any of the usual forms defined for a screen distance. 


**-stretch** *boolean*

 If the requested height of the embedded window is less than the height of the line in which it is displayed, this option can be used to specify whether the window should be stretched vertically to fill its line. If the **-pady** option has been specified as well, then the requested padding will be retained even if the window is stretched. 


**-window** *pathName*

 Specifies the name of a window to display in the annotation. Note that if a *pathName* has been set, then later configuring a window to the empty string will not delete the widget corresponding to the old *pathName*. Rather it will remove the association between the old *pathName* and the text widget. If multiple peer widgets are in use, it is usually simpler to use the **-create** option if embedded windows are desired in each peer. 

 Embedded images
---------------

 The final form of annotation in text widgets is an embedded image. Each embedded image annotation causes an image to be displayed at a particular point in the text. There may be any number of embedded images in a text widget, and a particular image may be embedded in multiple places in the same text widget.  The embedded image's position on the screen will be updated as the text is modified or scrolled. Each embedded image occupies one unit's worth of index space in the text widget, and it may be referred to either by its position in the widget's index space, or the name it is assigned when the image is inserted into the text widget with *pathName* **[image create](image.htm)**. If the range of text containing the embedded image is deleted then that copy of the image is removed from the screen. 


 Eliding an embedded image immediately after scheduling it for creation via *pathName* **image create** *index* **-create** will prevent it from being effectively created. Uneliding an elided embedded image scheduled for creation via *pathName* **image create** *index* **-create** will automatically trigger the associated creation script. After destroying an elided embedded image, the latter won't get automatically recreated. 


 When an embedded image is added to a text widget with the *pathName* **image create** widget command, a name unique to this instance of the image is returned. This name may then be used to refer to this image instance. The name is taken to be the value of the **-name** option (described below). If the **-name** option is not provided, the **-image** name is used instead. If the *imageName* is already in use in the text widget, then **#***nn* is added to the end of the *imageName*, where *nn* is an arbitrary integer. This insures the *imageName* is unique. Once this name is assigned to this instance of the image, it does not change, even though the **-image** or **-name** values can be changed with *pathName* **image configure**. 


 When an embedded image is added to a text widget with the *pathName* **image create** widget command, several configuration options may be associated with it. These options may be modified later with the *pathName* **image configure** widget command. The following options are currently supported: 


 
**-align** *where*

 If the image is not as tall as the line in which it is displayed, this option determines where the image is displayed in the line. *Where* must have one of the values **top** (align the top of the image with the top of the line), **center** (center the image within the range of the line), **bottom** (align the bottom of the image with the bottom of the line's area), or **baseline** (align the bottom of the image with the baseline of the line). 


**-image** *image*

 Specifies the name of the Tk image to display in the annotation. If *image* is not a valid Tk image, then an error is returned. 


**-name** *ImageName*

 Specifies the name by which this image instance may be referenced in the text widget. If *ImageName* is not supplied, then the name of the Tk image is used instead. If the *imageName* is already in use, *#nn* is appended to the end of the name as described above. 


**-padx** *pixels*

 *Pixels* specifies the amount of extra space to leave on each side of the embedded image. It may have any of the usual forms defined for a screen distance. 


**-pady** *pixels*

 *Pixels* specifies the amount of extra space to leave on the top and on the bottom of the embedded image. It may have any of the usual forms defined for a screen distance. 

 The selection
-------------

 Selection support is implemented via tags. If the **-exportselection** option for the text widget is true then the **sel** tag will be associated with the selection: 
1. Whenever characters are tagged with **sel** the text widget will claim ownership of the selection.
2. Attempts to retrieve the selection will be serviced by the text widget, returning all the characters with the **sel** tag.
3. If the selection is claimed away by another application or by another window within this application, then the **sel** tag will be removed from all characters in the text.
4. Whenever the **sel** tag range changes a virtual event **<<Selection>>** is generated.

  The **sel** tag is automatically defined when a text widget is created, and it may not be deleted with the “*pathName* **tag delete**” widget command. Furthermore, the **-selectbackground**, **-selectborderwidth**, and **-selectforeground** options for the text widget are tied to the **-background**, **-borderwidth**, and **-foreground** options for the **sel** tag: changes in either will automatically be reflected in the other. Also the **-inactiveselectbackground** option for the text widget is used instead of **-selectbackground** when the text widget does not have the focus. This allows programmatic control over the visualization of the **sel** tag for foreground and background windows, or to have **sel** not shown at all (when **-inactiveselectbackground** is empty) for background windows. Each peer text widget has its own **sel** tag which can be separately configured and set. 


The insertion cursor
--------------------

 The mark named **insert** has special significance in text widgets. It is defined automatically when a text widget is created and it may not be unset with the “*pathName* **mark unset**” widget command. The **insert** mark represents the position of the insertion cursor, and the insertion cursor will automatically be drawn at this point whenever the text widget has the input focus. The modified flag
-----------------

 The text widget can keep track of changes to the content of the widget by means of the modified flag. Inserting or deleting text will set this flag. The flag can be queried, set and cleared programmatically as well. Whenever the flag changes state a **<<Modified>>** virtual event is generated. See the *pathName* **edit modified** widget command for more details. The undo mechanism
------------------

 The text widget has an unlimited undo and redo mechanism (when the **-undo** widget option is true) which records every insert and delete action on a stack.  Boundaries (called “separators”) are inserted between edit actions. The purpose of these separators is to group inserts, deletes and replaces into one compound edit action. When undoing a change everything between two separators will be undone. The undone changes are then moved to the redo stack, so that an undone edit can be redone again. The redo stack is cleared whenever new edit actions are recorded on the undo stack. The undo and redo stacks can be cleared to keep their depth under control. 


 Separators are inserted automatically when the **-autoseparators** widget option is true. You can insert separators programmatically as well. If a separator is already present at the top of the undo stack no other will be inserted. That means that two separators on the undo stack are always separated by at least one insert or delete action. 


 The **<<UndoStack>>** virtual event is generated every time the undo stack or the redo stack becomes empty or unempty. 


 The undo mechanism is also linked to the modified flag. This means that undoing or redoing changes can take a modified text widget back to the unmodified state or vice versa. The modified flag will be set automatically to the appropriate state. This automatic coupling does not work when the modified flag has been set by the user, until the flag has been reset again. 


 See below for the *pathName* **edit** widget command that controls the undo mechanism. 


Peer widgets
------------

 The text widget has a separate store of all its data concerning each line's textual contents, marks, tags, images and windows, and the undo stack.  While this data store cannot be accessed directly (i.e. without a text widget as an intermediary), multiple text widgets can be created, each of which present different views on the same underlying data. Such text widgets are known as peer text widgets. 


 As text is added, deleted, edited and coloured in any one widget, and as images, marks, tags are adjusted, all such changes will be reflected in all peers. 


 All data and markup is shared, except for a few small details. First, the **sel** tag may be set and configured (in its display style) differently for each peer. Second, each peer has its own **insert** and **current** mark positions (but all other marks are shared). Third, embedded windows, which are arbitrary other widgets, cannot be shared between peers. This means the **-window** option of embedded windows is independently set for each peer (it is advisable to use the **-create** script capabilities to allow each peer to create its own embedded windows as needed). Fourth, all of the configuration options of each peer (e.g. **-font**, etc) can be set independently, with the exception of **-undo**, **-maxundo**, **-autoseparators** (i.e. all undo, redo and modified state issues are shared). 


 Finally any single peer need not contain all lines from the underlying data store. When creating a peer, a contiguous range of lines (e.g. only lines 52 through 125) may be specified. This allows a peer to contain just a small portion of the overall text. The range of lines will expand and contract as text is inserted or deleted. The peer will only ever display complete lines of text (one cannot share just part of a line). If the peer's contents contracts to nothing (i.e. all complete lines in the peer widget have been deleted from another widget), then it is impossible for new lines to be inserted. The peer will simply become an empty shell on which the background can be configured, but which will never show any content (without manual reconfiguration of the start and end lines). Note that a peer which does not contain all of the underlying data store still has indices numbered from “1.0” to “end”. It is simply that those indices reflect a subset of the total data, and data outside the contained range is not accessible to the peer. This means that the command *peerName* **index end** may return quite different values in different peers. Similarly, commands like *peerName* **tag ranges** will not return index ranges outside that which is meaningful to the peer. The configuration options **-startline** and **-endline** may be used to control how much of the underlying data is contained in any given text widget. 


 Note that peers are really peers. Deleting the “original” text widget will not cause any other peers to be deleted, or otherwise affected. 


 See below for the *pathName* **peer** widget command that controls the creation of peer widgets. 


Asynchronous update of line heights
-----------------------------------

 In order to maintain a responsive user-experience, the text widget calculates lines metrics (line heights in pixels) asynchronously. Because of this, some commands of the text widget may return wrong results if the asynchronous calculations are not finished at the time of calling. This applies to *pathName* **count -ypixels** and *pathName* **yview**.  Again for performance reasons, it would not be appropriate to let these commands always wait for the end of the update calculation each time they are called. In most use cases of these commands a more or less inaccurate result does not really matter compared to execution speed. 


 In case accurate result is needed (and if the text widget is managed by a geometry manager), one can resort to *pathName* **sync** and *pathName* **pendingsync** to control the synchronization of the view of text widgets. 


 The **<<WidgetViewSync>>** virtual event fires when the line heights of the text widget become obsolete (due to some editing command or configuration change), and again when the internal data of the text widget are back in sync with the widget view. The detail field (%d substitution) is either true (when the widget is in sync) or false (when it is not). 


 *pathName* **sync**, *pathName* **pendingsync** and **<<WidgetViewSync>>** apply to each text widget independently of its peers. 


 Examples of use: 



```
## Example 1:
# immediately complete line metrics at any cost (GUI unresponsive)
$w sync
$w yview moveto $fraction

## Example 2:
# synchronously wait for up-to-date line metrics (GUI responsive)
# before executing the scheduled command, but don't block execution flow
$w sync -command [list $w yview moveto $fraction]

## Example 3:
# init
set yud($w) 0
proc updateaction w {
	set ::yud($w) 1
	# any other update action here...
}
# runtime, synchronously wait for up-to-date line metrics (GUI responsive)
$w sync -command [list updateaction $w]
vwait yud($w)
$w yview moveto $fraction

## Example 4:
# init
set todo($w) {}
proc updateaction w {
	foreach cmd $::todo($w) {uplevel #0 $cmd}
	set todo($w) {}
}
# runtime
lappend todo($w) [list $w yview moveto $fraction]
$w sync -command [list updateaction $w]

## Example 5:
# init
set todo($w) {}
bind $w <<WidgetViewSync>> {
	if {%d} {
		foreach cmd $todo(%W) {eval $cmd}
		set todo(%W) {}
	}
}
# runtime
if {![$w pendingsync]} {
	$w yview moveto $fraction
} else {
	lappend todo($w) [list $w yview moveto $fraction]
}
```
 Widget command
--------------

 The **text** command creates a new Tcl command whose name is the same as the path name of the text's window. This command may be used to invoke various operations on the widget. It has the following general form: 
```
*pathName option* ?*arg arg ...*?
```
 *PathName* is the name of the command, which is the same as the text widget's path name. *Option* and the *arg*s determine the exact behavior of the command. The following commands are possible for text widgets: 
 
*pathName* **bbox** *index*

 Returns a list of four elements describing the screen area of the character given by *index*. The first two elements of the list give the x and y coordinates of the upper-left corner of the area occupied by the character, and the last two elements give the width and height of the area. If the character is only partially visible on the screen, then the return value reflects just the visible part. If the character is not visible on the screen then the return value is an empty list. 


*pathName* **cget** *option*

 Returns the current value of the configuration option given by *option*. *Option* may have any of the values accepted by the **text** command. 


*pathName* **compare** *index1 op index2*

 Compares the indices given by *index1* and *index2* according to the relational operator given by *op*, and returns 1 if the relationship is satisfied and 0 if it is not. *Op* must be one of the operators <, <=, ==, >=, >, or !=. If *op* is == then 1 is returned if the two indices refer to the same character, if *op* is < then 1 is returned if *index1* refers to an earlier character in the text than *index2*, and so on. 


*pathName* **configure** ?*option*? *?value option value ...*?
 Query or modify the configuration options of the widget. If no *option* is specified, returns a list describing all of the available options for *pathName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. *Option* may have any of the values accepted by the **text** command. 


*pathName* **count** *?options*? *index1 index2*

 Counts the number of relevant things between the two indices. If *index1* is after *index2*, the result will be a negative number (and this holds for each of the possible options). The actual items which are counted depend on the options given. The result is a list of integers, one for the result of each counting option given. Valid counting options are **-chars**, **-displaychars**, **-displayindices**, **-displaylines**, **-indices**, **-lines**, **-xpixels** and **-ypixels**. The default value, if no option is specified, is **-indices**. There is an additional possible option **-update** which is a modifier. If given (and if the text widget is managed by a geometry manager), then all subsequent options ensure that any possible out of date information is recalculated. This currently only has any effect for the **-ypixels** count (which, if **-update** is not given, will use the text widget's current cached value for each line). This **-update** option is obsoleted by *pathName* **sync**, *pathName* **pendingsync** and **<<WidgetViewSync>>**. The count options are interpreted as follows: 
 **-chars**
 count all characters, whether elided or not. Do not count embedded windows or images. 

**-displaychars**
 count all non-elided characters. 

**-displayindices**
 count all non-elided characters, windows and images. 

**-displaylines**
 count all display lines (i.e. counting one for each time a line wraps) from the line of the first index up to, but not including the display line of the second index. Therefore if they are both on the same display line, zero will be returned. By definition displaylines are visible and therefore this only counts portions of actual visible lines. 

**-indices**
 count all characters and embedded windows or images (i.e. everything which counts in text-widget index space), whether they are elided or not. 

**-lines**
 count all logical lines (irrespective of wrapping) from the line of the first index up to, but not including the line of the second index. Therefore if they are both on the same line, zero will be returned. Logical lines are counted whether they are currently visible (non-elided) or not. 

**-xpixels**
 count the number of horizontal pixels from the first pixel of the first index to (but not including) the first pixel of the second index. To count the total desired width of the text widget (assuming wrapping is not enabled), first find the longest line and then use “.text count -xpixels "${line}.0" "${line}.0 lineend"”. 

**-ypixels**
 count the number of vertical pixels from the first pixel of the first index to (but not including) the first pixel of the second index. If both indices are on the same display line, zero will be returned. To count the total number of vertical pixels in the text widget, use “.text count -ypixels 1.0 end”, and to ensure this is up to date, use “.text count -update -ypixels 1.0 end”. 

The command returns a positive or negative integer corresponding to the number of items counted between the two indices. One such integer is returned for each counting option given, so a list is returned if more than one option was supplied. For example “.text count -xpixels -ypixels 1.3 4.5” is perfectly valid and will return a list of two elements.




*pathName* **debug** ?*boolean*?
 If *boolean* is specified, then it must have one of the true or false values accepted by [Tcl\_GetBoolean](https://www.tcl.tk/man/tcl/TclLib/GetInt.htm). If the value is a true one then internal consistency checks will be turned on in the B-tree code associated with text widgets. If *boolean* has a false value then the debugging checks will be turned off. In either case the command returns an empty string. If *boolean* is not specified then the command returns **on** or **off** to indicate whether or not debugging is turned on. There is a single debugging switch shared by all text widgets: turning debugging on or off in any widget turns it on or off for all widgets. For widgets with large amounts of text, the consistency checks may cause a noticeable slow-down.  When debugging is turned on, the drawing routines of the text widget set the global variables **tk\_textRedraw** and **tk\_textRelayout** to the lists of indices that are redrawn. The values of these variables are tested by Tk's test suite. 




*pathName* **delete** *index1* ?*index2 ...*?
 Delete a range of characters from the text. If both *index1* and *index2* are specified, then delete all the characters starting with the one given by *index1* and stopping just before *index2* (i.e. the character at *index2* is not deleted). If *index2* does not specify a position later in the text than *index1* then no characters are deleted. If *index2* is not specified then the single character at *index1* is deleted. Attempts to delete characters in a way that would leave the text without a newline as the last character will be tweaked by the text widget to avoid this. In particular, deletion of complete lines of text up to the end of the text will also delete the newline character just before the deleted block so that it is replaced by the new final newline of the text widget. The command returns an empty string. If more indices are given, multiple ranges of text will be deleted. All indices are first checked for validity before any deletions are made. They are sorted and the text is removed from the last range to the first range so deleted text does not cause an undesired index shifting side-effects. If multiple ranges with the same start index are given, then the longest range is used. If overlapping ranges are given, then they will be merged into spans that do not cause deletion of text outside the given ranges due to text shifted during deletion. 


*pathName* **dlineinfo** *index*

 Returns a list with five elements describing the area occupied by the display line containing *index*. The first two elements of the list give the x and y coordinates of the upper-left corner of the area occupied by the line, the third and fourth elements give the width and height of the area, and the fifth element gives the position of the baseline for the line, measured down from the top of the area. All of this information is measured in pixels. If the current wrap mode is **none** and the line extends beyond the boundaries of the window, the area returned reflects the entire area of the line, including the portions that are out of the window. If the line is shorter than the full width of the window then the area returned reflects just the portion of the line that is occupied by characters and embedded windows. If the display line containing *index* is not visible on the screen then the return value is an empty list. 


*pathName* **dump** ?*switches*? *index1* ?*index2*?
 Return the contents of the text widget from *index1* up to, but not including *index2*, including the text and information about marks, tags, and embedded windows. If *index2* is not specified, then it defaults to one character past *index1*. The information is returned in the following format:  *key1 value1 index1 key2 value2 index2* ... 


 The possible *key* values are **text**, **mark**, **tagon**, **tagoff**, **[image](image.htm)**, and **window**. The corresponding *value* is the text, mark name, tag name, image name, or window name. The *index* information is the index of the start of the text, mark, tag transition, image or window. One or more of the following switches (or abbreviations thereof) may be specified to control the dump: 


 **-all**
 Return information about all elements: text, marks, tags, images and windows. This is the default. 


**-command** *command*

 Instead of returning the information as the result of the dump operation, invoke the *command* on each element of the text widget within the range. The command has three arguments appended to it before it is evaluated: the *key*, *value*, and *index*. 

**-image**
 Include information about images in the dump results. 

**-mark**
 Include information about marks in the dump results. 

**-tag**
 Include information about tag transitions in the dump results. Tag information is returned as **tagon** and **tagoff** elements that indicate the begin and end of each range of each tag, respectively. 

**-text**
 Include information about text in the dump results. The value is the text up to the next element or the end of range indicated by *index2*. A text element does not span newlines. A multi-line block of text that contains no marks or tag transitions will still be dumped as a set of text segments that each end with a newline. The newline is part of the value. 

**-window**
 Include information about embedded windows in the dump results. The value of a window is its Tk pathname, unless the window has not been created yet. (It must have a create script.) In this case an empty string is returned, and you must query the window by its index position to get more information. 




*pathName* **edit** *option* ?*arg arg ...*?
 This command controls the undo mechanism and the modified flag. The exact behavior of the command depends on the *option* argument that follows the **edit** argument. The following forms of the command are currently supported: 
 
*pathName* **edit canredo**

 Returns a boolean true if redo is possible, i.e. when the redo stack is not empty. Otherwise returns false. 


*pathName* **edit canundo**

 Returns a boolean true if undo is possible, i.e. when the undo stack is not empty. Otherwise returns false. 


*pathName* **edit modified** ?*boolean*?
 If *boolean* is not specified, returns the modified flag of the widget. The insert, delete, edit undo and edit redo commands or the user can set or clear the modified flag. If *boolean* is specified, sets the modified flag of the widget to *boolean*. 


*pathName* **edit redo**

 When the **-undo** option is true, reapplies the last undone edits provided no other edits were done since then. Generates an error when the redo stack is empty. Does nothing when the **-undo** option is false. 


*pathName* **edit reset**

 Clears the undo and redo stacks. 


*pathName* **edit separator**

 Inserts a separator (boundary) on the undo stack. Does nothing when the **-undo** option is false. 


*pathName* **edit undo**

 Undoes the last edit action when the **-undo** option is true. An edit action is defined as all the insert and delete commands that are recorded on the undo stack in between two separators. Generates an error when the undo stack is empty. Does nothing when the **-undo** option is false. 




*pathName* **get** ?**-displaychars**? ?**--**? *index1* ?*index2 ...*?
 Return a range of characters from the text. The return value will be all the characters in the text starting with the one whose index is *index1* and ending just before the one whose index is *index2* (the character at *index2* will not be returned). If *index2* is omitted then the single character at *index1* is returned. If there are no characters in the specified range (e.g. *index1* is past the end of the file or *index2* is less than or equal to *index1*) then an empty string is returned. If the specified range contains embedded windows, no information about them is included in the returned string. If multiple index pairs are given, multiple ranges of text will be returned in a list. Invalid ranges will not be represented with empty strings in the list. The ranges are returned in the order passed to *pathName* **get**. If the **-displaychars** option is given, then, within each range, only those characters which are not elided will be returned. This may have the effect that some of the returned ranges are empty strings. 


*pathName* **image** *option* ?*arg arg ...*?
 This command is used to manipulate embedded images. The behavior of the command depends on the *option* argument that follows the **tag** argument. The following forms of the command are currently supported: 
 
*pathName* **image cget** *index option*

 Returns the value of a configuration option for an embedded image. *Index* identifies the embedded image, and *option* specifies a particular configuration option, which must be one of the ones listed in the section **[EMBEDDED IMAGES](#M79)**. 


*pathName* **image configure** *index* ?*option value ...*?
 Query or modify the configuration options for an embedded image. If no *option* is specified, returns a list describing all of the available options for the embedded image at *index* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. See **[EMBEDDED IMAGES](#M79)** for information on the options that are supported. 


*pathName* **image create** *index* ?*option value ...*?
 This command creates a new image annotation, which will appear in the text at the position given by *index*. Any number of *option-value* pairs may be specified to configure the annotation. Returns a unique identifier that may be used as an index to refer to this image. See **[EMBEDDED IMAGES](#M79)** for information on the options that are supported, and a description of the identifier returned. 


*pathName* **image names**

 Returns a list whose elements are the names of all image instances currently embedded in *window*. 




*pathName* **index** *index*

 Returns the position corresponding to *index* in the form *line.char* where *line* is the line number and *char* is the character number. *Index* may have any of the forms described under **[INDICES](#M24)** above. 


*pathName* **insert** *index chars* ?*tagList chars tagList ...*?
 Inserts all of the *chars* arguments just before the character at *index*. If *index* refers to the end of the text (the character after the last newline) then the new text is inserted just before the last newline instead. If there is a single *chars* argument and no *tagList*, then the new text will receive any tags that are present on both the character before and the character after the insertion point; if a tag is present on only one of these characters then it will not be applied to the new text. If *tagList* is specified then it consists of a list of tag names; the new characters will receive all of the tags in this list and no others, regardless of the tags present around the insertion point. If multiple *chars*-*tagList* argument pairs are present, they produce the same effect as if a separate *pathName* **insert** widget command had been issued for each pair, in order. The last *tagList* argument may be omitted. 


*pathName* **mark** *option* ?*arg arg ...*?
 This command is used to manipulate marks. The exact behavior of the command depends on the *option* argument that follows the **mark** argument. The following forms of the command are currently supported: 
 
*pathName* **mark gravity** *markName* ?*direction*?
 If *direction* is not specified, returns **left** or **right** to indicate which of its adjacent characters *markName* is attached to. If *direction* is specified, it must be **left** or **right**; the gravity of *markName* is set to the given value. 


*pathName* **mark names**

 Returns a list whose elements are the names of all the marks that are currently set. 


*pathName* **mark next** *index*

 Returns the name of the next mark at or after *index*. If *index* is specified in numerical form, then the search for the next mark begins at that index. If *index* is the name of a mark, then the search for the next mark begins immediately after that mark. This can still return a mark at the same position if there are multiple marks at the same index. These semantics mean that the **mark next** operation can be used to step through all the marks in a text widget in the same order as the mark information returned by the *pathName* **dump** operation. If a mark has been set to the special **end** index, then it appears to be *after* **end** with respect to the *pathName* **mark next** operation. An empty string is returned if there are no marks after *index*. 


*pathName* **mark previous** *index*

 Returns the name of the mark at or before *index*. If *index* is specified in numerical form, then the search for the previous mark begins with the character just before that index. If *index* is the name of a mark, then the search for the next mark begins immediately before that mark. This can still return a mark at the same position if there are multiple marks at the same index. These semantics mean that the *pathName* **mark previous** operation can be used to step through all the marks in a text widget in the reverse order as the mark information returned by the *pathName* **dump** operation. An empty string is returned if there are no marks before *index*. 


*pathName* **mark set** *markName index*

 Sets the mark named *markName* to a position just before the character at *index*. If *markName* already exists, it is moved from its old position; if it does not exist, a new mark is created. This command returns an empty string. 


*pathName* **mark unset** *markName* ?*markName markName ...*?
 Remove the mark corresponding to each of the *markName* arguments. The removed marks will not be usable in indices and will not be returned by future calls to “*pathName* **mark names**”. This command returns an empty string. 




*pathName* **peer** *option args*

 This command is used to create and query widget peers. It has two forms, depending on *option*: 
 
*pathName* **peer create** *newPathName* ?*options*?
 Creates a peer text widget with the given *newPathName*, and any optional standard configuration options (as for the *text* command). By default the peer will have the same start and end line as the parent widget, but these can be overridden with the standard configuration options. 


*pathName* **peer names**

 Returns a list of peers of this widget (this does not include the widget itself). The order within this list is undefined. 




*pathName* **pendingsync**

 Returns 1 if the line heights calculations are not up-to-date, 0 otherwise. 


*pathName* **replace** *index1 index2 chars* ?*tagList chars tagList ...*?
 Replaces the range of characters between *index1* and *index2* with the given characters and tags. See the section on *pathName* **insert** for an explanation of the handling of the *tagList...* arguments, and the section on *pathName* **delete** for an explanation of the handling of the indices. If *index2* corresponds to an index earlier in the text than *index1*, an error will be generated.  The deletion and insertion are arranged so that no unnecessary scrolling of the window or movement of insertion cursor occurs. In addition the undo/redo stack are correctly modified, if undo operations are active in the text widget. The command returns an empty string. 




*pathName* **scan** *option args*

 This command is used to implement scanning on texts. It has two forms, depending on *option*: 
 
*pathName* **scan mark** *x y*

 Records *x* and *y* and the current view in the text window, for use in conjunction with later *pathName* **scan dragto** commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. 


*pathName* **scan dragto** *x y*

 This command computes the difference between its *x* and *y* arguments and the *x* and *y* arguments to the last *pathName* **scan mark** command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the text at high speed through the window. The return value is an empty string. 




*pathName* **search** ?*switches*? *pattern index* ?*stopIndex*?
 Searches the text in *pathName* starting at *index* for a range of characters that matches *pattern*. If a match is found, the index of the first character in the match is returned as result; otherwise an empty string is returned. One or more of the following switches (or abbreviations thereof) may be specified to control the search: 
 **-forwards**
 The search will proceed forward through the text, finding the first matching range starting at or after the position given by *index*. This is the default. 

**-backwards**
 The search will proceed backward through the text, finding the matching range closest to *index* whose first character is before *index* (it is not allowed to be at *index*). Note that, for a variety of reasons, backwards searches can be substantially slower than forwards searches (particularly when using **-regexp**), so it is recommended that performance-critical code use forward searches. 

**-exact**
 Use exact matching: the characters in the matching range must be identical to those in *pattern*. This is the default. 

**-regexp**
 Treat *pattern* as a regular expression and match it against the text using the rules for regular expressions (see the **[regexp](../tclcmd/regexp.htm)** command and the **[re\_syntax](../tclcmd/re_syntax.htm)** page for details). The default matching automatically passes both the **-lineanchor** and **-linestop** options to the regexp engine (unless **-nolinestop** is used), so that *^$* match beginning and end of line, and *.*, *[^* sequences will never match the newline character *\n*. 

**-nolinestop**
 This allows *.* and *[^* sequences to match the newline character *\n*, which they will otherwise not do (see the **[regexp](../tclcmd/regexp.htm)** command for details). This option is only meaningful if **-regexp** is also given, and an error will be thrown otherwise. For example, to match the entire text, use “*pathName* **search -nolinestop -regexp** ".\*" 1.0”. 

**-nocase**
 Ignore case differences between the pattern and the text. 


**-count** *varName*

 The argument following **-count** gives the name of a variable; if a match is found, the number of index positions between beginning and end of the matching range will be stored in the variable. If there are no embedded images or windows in the matching range (and there are no elided characters if **-elide** is not given), this is equivalent to the number of characters matched. In either case, the range *matchIdx* to *matchIdx + $count chars* will return the entire matched text. 

**-all**
 Find all matches in the given range and return a list of the indices of the first character of each match. If a **-count** *varName* switch is given, then *varName* is also set to a list containing one element for each successful match. Note that, even for exact searches, the elements of this list may be different, if there are embedded images, windows or hidden text. Searches with **-all** behave very similarly to the Tcl command **regexp -all**, in that overlapping matches are not normally returned. For example, applying an **-all** search of the pattern “\w+” against “hello there” will just match twice, once for each word, and matching “Z[a-z]+Z” against “ZooZooZoo” will just match once. 

**-overlap**
 When performing **-all** searches, the normal behaviour is that matches which overlap an already-found match will not be returned. This switch changes that behaviour so that all matches which are not totally enclosed within another match are returned. For example, applying an **-overlap** search of the pattern “\w+” against “hello there” will just match twice (i.e. no different to just **-all**), but matching “Z[a-z]+Z” against “ZooZooZoo” will now match twice. An error will be thrown if this switch is used without **-all**. 

**-strictlimits**
 When performing any search, the normal behaviour is that the start and stop limits are checked with respect to the start of the matching text. With the **-strictlimits** flag, the entire matching range must lie inside the start and stop limits specified for the match to be valid. 

**-elide**
 Find elided (hidden) text as well. By default only displayed text is searched. 

**--**
 This switch has no effect except to terminate the list of switches: the next argument will be treated as *pattern* even if it starts with **-**. 

The matching range may be within a single line of text, or run across multiple lines (if parts of the pattern can match a new-line). For regular expression matching one can use the various newline-matching features such as **$** to match the end of a line, **^** to match the beginning of a line, and to control whether **.** is allowed to match a new-line. If *stopIndex* is specified, the search stops at that index: for forward searches, no match at or after *stopIndex* will be considered; for backward searches, no match earlier in the text than *stopIndex* will be considered. If *stopIndex* is omitted, the entire text will be searched: when the beginning or end of the text is reached, the search continues at the other end until the starting location is reached again; if *stopIndex* is specified, no wrap-around will occur. This means that, for example, if the search is **-forwards** but *stopIndex* is earlier in the text than *startIndex*, nothing will ever be found. See **[KNOWN BUGS](#M196)** below for a number of minor limitations of the *pathName* **search** command.




*pathName* **see** *index*

 Adjusts the view in the window so that the character given by *index* is completely visible. If *index* is already visible then the command does nothing. If *index* is a short distance out of view, the command adjusts the view just enough to make *index* visible at the edge of the window. If *index* is far out of view, then the command centers *index* in the window. 


*pathName* **sync** ?**-command** *command*?
 Controls the synchronization of the view of the text widget. 
 
*pathName* **sync**

 Immediately brings the line metrics up-to-date by forcing computation of any outdated line heights. The command returns immediately if there is no such outdated line heights, otherwise it returns only at the end of the computation. The command returns an empty string. 


*pathName* **sync -command** *command*

 Schedules *command* to be executed (by the event loop) exactly once as soon as all line heights are up-to-date. If there are no pending line metrics calculations, the scheduling is immediate. The command returns the empty string. **[bgerror](../tclcmd/bgerror.htm)** is called on *command* failure. 




*pathName* **tag** *option* ?*arg arg ...*?
 This command is used to manipulate tags. The exact behavior of the command depends on the *option* argument that follows the **tag** argument. The following forms of the command are currently supported: 
 
*pathName* **tag add** *tagName index1* ?*index2 index1 index2 ...*?
 Associate the tag *tagName* with all of the characters starting with *index1* and ending just before *index2* (the character at *index2* is not tagged). A single command may contain any number of *index1*-*index2* pairs. If the last *index2* is omitted then the single character at *index1* is tagged. If there are no characters in the specified range (e.g. *index1* is past the end of the file or *index2* is less than or equal to *index1*) then the command has no effect. 


*pathName* **tag bind** *tagName* ?*sequence*? ?*script*?
 This command associates *script* with the tag given by *tagName*. Whenever the event sequence given by *sequence* occurs for a character that has been tagged with *tagName*, the script will be invoked. This widget command is similar to the **[bind](bind.htm)** command except that it operates on characters in a text rather than entire widgets. See the **[bind](bind.htm)** manual entry for complete details on the syntax of *sequence* and the substitutions performed on *script* before invoking it. If all arguments are specified then a new binding is created, replacing any existing binding for the same *sequence* and *tagName* (if the first character of *script* is “+” then *script* augments an existing binding rather than replacing it). In this case the return value is an empty string. If *script* is omitted then the command returns the *script* associated with *tagName* and *sequence* (an error occurs if there is no such binding). If both *script* and *sequence* are omitted then the command returns a list of all the sequences for which bindings have been defined for *tagName*.  The only events for which bindings may be specified are those related to the mouse and keyboard (such as **Enter**, **Leave**, **ButtonPress**, **Motion**, and **KeyPress**) or virtual events. Event bindings for a text widget use the **current** mark described under **[MARKS](#M71)** above. An **Enter** event triggers for a tag when the tag first becomes present on the current character, and a **Leave** event triggers for a tag when it ceases to be present on the current character. **Enter** and **Leave** events can happen either because the **current** mark moved or because the character at that position changed. Note that these events are different than **Enter** and **Leave** events for windows. Mouse and keyboard events are directed to the current character. If a virtual event is used in a binding, that binding can trigger only if the virtual event is defined by an underlying mouse-related or keyboard-related event. 


 It is possible for the current character to have multiple tags, and for each of them to have a binding for a particular event sequence. When this occurs, one binding is invoked for each tag, in order from lowest-priority to highest priority. If there are multiple matching bindings for a single tag, then the most specific binding is chosen (see the manual entry for the **[bind](bind.htm)** command for details). **[continue](../tclcmd/continue.htm)** and **[break](../tclcmd/break.htm)** commands within binding scripts are processed in the same way as for bindings created with the **[bind](bind.htm)** command. 


If bindings are created for the widget as a whole using the **[bind](bind.htm)** command, then those bindings will supplement the tag bindings. The tag bindings will be invoked first, followed by bindings for the window as a whole. 




*pathName* **tag cget** *tagName option*

 This command returns the current value of the option named *option* associated with the tag given by *tagName*. *Option* may have any of the values accepted by the *pathName* **tag configure** widget command. 


*pathName* **tag configure** *tagName* ?*option*? ?*value*? ?*option value ...*?
 This command is similar to the *pathName* **configure** widget command except that it modifies options associated with the tag given by *tagName* instead of modifying options for the overall text widget. If no *option* is specified, the command returns a list describing all of the available options for *tagName* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given option(s) to have the given value(s) in *tagName*; in this case the command returns an empty string. See **[TAGS](#M43)** above for details on the options available for tags. 


*pathName* **tag delete** *tagName* ?*tagName ...*?
 Deletes all tag information for each of the *tagName* arguments. The command removes the tags from all characters in the file and also deletes any other information associated with the tags, such as bindings and display information. The command returns an empty string. 


*pathName* **tag lower** *tagName* ?*belowThis*?
 Changes the priority of tag *tagName* so that it is just lower in priority than the tag whose name is *belowThis*. If *belowThis* is omitted, then *tagName*'s priority is changed to make it lowest priority of all tags. 


*pathName* **tag names** ?*index*?
 Returns a list whose elements are the names of all the tags that are active at the character position given by *index*. If *index* is omitted, then the return value will describe all of the tags that exist for the text (this includes all tags that have been named in a “*pathName* **tag**” widget command but have not been deleted by a “*pathName* **tag delete**” widget command, even if no characters are currently marked with the tag). The list will be sorted in order from lowest priority to highest priority. 


*pathName* **tag nextrange** *tagName index1* ?*index2*?
 This command searches the text for a range of characters tagged with *tagName* where the first character of the range is no earlier than the character at *index1* and no later than the character just before *index2* (a range starting at *index2* will not be considered). If several matching ranges exist, the first one is chosen. The command's return value is a list containing two elements, which are the index of the first character of the range and the index of the character just after the last one in the range. If no matching range is found then the return value is an empty string. If *index2* is not given then it defaults to the end of the text. 


*pathName* **tag prevrange** *tagName index1* ?*index2*?
 This command searches the text for a range of characters tagged with *tagName* where the first character of the range is before the character at *index1* and no earlier than the character at *index2* (a range starting at *index2* will be considered). If several matching ranges exist, the one closest to *index1* is chosen. The command's return value is a list containing two elements, which are the index of the first character of the range and the index of the character just after the last one in the range. If no matching range is found then the return value is an empty string. If *index2* is not given then it defaults to the beginning of the text. 


*pathName* **tag raise** *tagName* ?*aboveThis*?
 Changes the priority of tag *tagName* so that it is just higher in priority than the tag whose name is *aboveThis*. If *aboveThis* is omitted, then *tagName*'s priority is changed to make it highest priority of all tags. 


*pathName* **tag ranges** *tagName*

 Returns a list describing all of the ranges of text that have been tagged with *tagName*. The first two elements of the list describe the first tagged range in the text, the next two elements describe the second range, and so on. The first element of each pair contains the index of the first character of the range, and the second element of the pair contains the index of the character just after the last one in the range. If there are no characters tagged with *tag* then an empty string is returned. 


*pathName* **tag remove** *tagName index1* ?*index2 index1 index2 ...*?
 Remove the tag *tagName* from all of the characters starting at *index1* and ending just before *index2* (the character at *index2* is not affected). A single command may contain any number of *index1*-*index2* pairs. If the last *index2* is omitted then the tag is removed from the single character at *index1*. If there are no characters in the specified range (e.g. *index1* is past the end of the file or *index2* is less than or equal to *index1*) then the command has no effect. This command returns an empty string. 




*pathName* **window** *option* ?*arg arg ...*?
 This command is used to manipulate embedded windows. The behavior of the command depends on the *option* argument that follows the **window** argument. The following forms of the command are currently supported: 
 
*pathName* **window cget** *index option*

 Returns the value of a configuration option for an embedded window. *Index* identifies the embedded window, and *option* specifies a particular configuration option, which must be one of the ones listed in the section **[EMBEDDED WINDOWS](#M72)**. 


*pathName* **window configure** *index* ?*option value ...*?
 Query or modify the configuration options for an embedded window. If no *option* is specified, returns a list describing all of the available options for the embedded window at *index* (see **[Tk\_ConfigureInfo](https://www.tcl.tk/man/tcl/TkLib/ConfigWidg.htm)** for information on the format of this list). If *option* is specified with no *value*, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no *option* is specified). If one or more *option-value* pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. See **[EMBEDDED WINDOWS](#M72)** for information on the options that are supported. 


*pathName* **window create** *index* ?*option value ...*?
 This command creates a new window annotation, which will appear in the text at the position given by *index*. Any number of *option-value* pairs may be specified to configure the annotation. See **[EMBEDDED WINDOWS](#M72)** for information on the options that are supported. Returns an empty string. 


*pathName* **window names**

 Returns a list whose elements are the names of all windows currently embedded in *window*. 




*pathName* **xview** *option args*

 This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: 
 
*pathName* **xview**

 Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the portion of the document's horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. The fractions refer only to the lines that are actually visible in the window: if the lines in the window are all very short, so that they are entirely visible, the returned fractions will be 0 and 1, even if there are other lines in the text that are much wider than the window. These are the same values passed to scrollbars via the **-xscrollcommand** option. 


*pathName* **xview moveto** *fraction*

 Adjusts the view in the window so that *fraction* of the horizontal span of the text is off-screen to the left. *Fraction* is a fraction between 0 and 1. 


*pathName* **xview scroll** *number what*

 This command shifts the view in the window left or right according to *number* and *what*. *What* must be **units**, **pages** or **pixels**. If *what* is **units** or **pages** then *number* must be an integer, otherwise number may be specified in any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**, such as “2.0c” or “1i” (the result is rounded to the nearest integer value. If no units are given, pixels are assumed). If *what* is **units**, the view adjusts left or right by *number* average-width characters on the display; if it is **pages** then the view adjusts by *number* screenfuls; if it is **pixels** then the view adjusts by *number* pixels. If *number* is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. 




*pathName* **yview** ?*args*?
 This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms: 
 
*pathName* **yview**

 Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the first visible pixel of the first character (or image, etc) in the top line in the window, relative to the text as a whole (0.5 means it is halfway through the text, for example). The second element gives the position of the first pixel just after the last visible one in the bottom line of the window, relative to the text as a whole. These are the same values passed to scrollbars via the **-yscrollcommand** option. 


*pathName* **yview moveto** *fraction*

 Adjusts the view in the window so that the pixel given by *fraction* appears at the top of the top line of the window. *Fraction* is a fraction between 0 and 1; 0 indicates the first pixel of the first character in the text, 0.33 indicates the pixel that is one-third the way through the text; and so on. Values close to 1 will indicate values close to the last pixel in the text (1 actually refers to one pixel beyond the last pixel), but in such cases the widget will never scroll beyond the last pixel, and so a value of 1 will effectively be rounded back to whatever fraction ensures the last pixel is at the bottom of the window, and some other pixel is at the top. 


*pathName* **yview scroll** *number what*

 This command adjust the view in the window up or down according to *number* and *what*. *What* must be **units**, **pages** or **pixels**. If *what* is **units** or **pages** then *number* must be an integer, otherwise number may be specified in any of the forms acceptable to **[Tk\_GetPixels](https://www.tcl.tk/man/tcl/TkLib/GetPixels.htm)**, such as “2.0c” or “1i” (the result is rounded to the nearest integer value. If no units are given, pixels are assumed). If *what* is **units**, the view adjusts up or down by *number* lines on the display; if it is **pages** then the view adjusts by *number* screenfuls; if it is **pixels** then the view adjusts by *number* pixels. If *number* is negative then earlier positions in the text become visible; if it is positive then later positions in the text become visible. 


*pathName* **yview** ?**-pickplace**? *index*

 Changes the view in the widget's window to make *index* visible. If the **-pickplace** option is not specified then *index* will appear at the top of the window. If **-pickplace** is specified then the widget chooses where *index* appears in the window: 
1. If *index* is already visible somewhere in the window then the command does nothing.
2. If *index* is only a few lines off-screen above the window then it will be positioned at the top of the window.
3. If *index* is only a few lines off-screen below the window then it will be positioned at the bottom of the window.
4. Otherwise, *index* will be centered in the window.


The **-pickplace** option has been obsoleted by the *pathName* **see** widget command (*pathName* **see** handles both x- and y-motion to make a location visible, whereas the **-pickplace** mode only handles motion in y).




*pathName* **yview** *number*

 This command makes the first character on the line after the one given by *number* visible at the top of the window. *Number* must be an integer. This command used to be used for scrolling, but now it is obsolete. 



 Bindings
--------

 Tk automatically creates class bindings for texts that give them the following default behavior. In the descriptions below, “word” is dependent on the value of the **[tcl\_wordchars](../tclcmd/tclvars.htm)** variable. See **[tclvars](../tclcmd/tclvars.htm)**(n). 
1. Clicking mouse button 1 positions the insertion cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse.
2. Double-clicking with mouse button 1 selects the word under the mouse and positions the insertion cursor at the start of the word. Dragging after a double click will stroke out a selection consisting of whole words.
3. Triple-clicking with mouse button 1 selects the line under the mouse and positions the insertion cursor at the start of the line. Dragging after a triple click will stroke out a selection consisting of whole lines.
4. The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down; this will adjust the end of the selection that was nearest to the mouse cursor when button 1 was pressed. If the button is double-clicked before dragging then the selection will be adjusted in units of whole words; if it is triple-clicked then the selection will be adjusted in units of whole lines.
5. Clicking mouse button 1 with the Control key down will reposition the insertion cursor without affecting the selection.
6. If any normal printing characters are typed, they are inserted at the point of the insertion cursor.
7. The view in the widget can be adjusted by dragging with mouse button 2. If mouse button 2 is clicked without moving the mouse, the selection is copied into the text at the position of the mouse cursor. The Insert key also inserts the selection, but at the position of the insertion cursor.
8. If the mouse is dragged out of the widget while button 1 is pressed, the entry will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window).
9. The Left and Right keys move the insertion cursor one character to the left or right; they also clear any selection in the text. If Left or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Left and Control-Right move the insertion cursor by words, and Control-Shift-Left and Control-Shift-Right move the insertion cursor by words and also extend the selection. Control-b and Control-f behave the same as Left and Right, respectively. Meta-b and Meta-f behave the same as Control-Left and Control-Right, respectively.
10. The Up and Down keys move the insertion cursor one line up or down and clear any selection in the text. If Up or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Up and Control-Down move the insertion cursor by paragraphs (groups of lines separated by blank lines), and Control-Shift-Up and Control-Shift-Down move the insertion cursor by paragraphs and also extend the selection. Control-p and Control-n behave the same as Up and Down, respectively.
11. The Next and Prior keys move the insertion cursor forward or backwards by one screenful and clear any selection in the text. If the Shift key is held down while Next or Prior is typed, then the selection is extended to include the new character.
12. Control-Next and Control-Prior scroll the view right or left by one page without moving the insertion cursor or affecting the selection.
13. Home and Control-a move the insertion cursor to the beginning of its display line and clear any selection in the widget. Shift-Home moves the insertion cursor to the beginning of the display line and also extends the selection to that point.
14. End and Control-e move the insertion cursor to the end of the display line and clear any selection in the widget. Shift-End moves the cursor to the end of the display line and extends the selection to that point.
15. Control-Home and Meta-< move the insertion cursor to the beginning of the text and clear any selection in the widget. Control-Shift-Home moves the insertion cursor to the beginning of the text and also extends the selection to that point.
16. Control-End and Meta-> move the insertion cursor to the end of the text and clear any selection in the widget. Control-Shift-End moves the cursor to the end of the text and extends the selection to that point.
17. The Select key and Control-Space set the selection anchor to the position of the insertion cursor. They do not affect the current selection. Shift-Select and Control-Shift-Space adjust the selection to the current position of the insertion cursor, selecting from the anchor to the insertion cursor if there was not any selection previously.
18. Control-/ selects the entire contents of the widget.
19. Control-\ clears any selection in the widget.
20. The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection. This action is carried out by the command **tk\_textCopy**.
21. The F20 key (labelled Cut on many Sun workstations) or Control-w copies the selection in the widget to the clipboard and deletes the selection. This action is carried out by the command **tk\_textCut**. If there is no selection in the widget then these keys have no effect.
22. The F18 key (labelled Paste on many Sun workstations) or Control-y inserts the contents of the clipboard at the position of the insertion cursor. This action is carried out by the command **tk\_textPaste**.
23. The Delete key deletes the selection, if there is one in the widget. If there is no selection, it deletes the character to the right of the insertion cursor.
24. Backspace and Control-h delete the selection, if there is one in the widget. If there is no selection, they delete the character to the left of the insertion cursor.
25. Control-d deletes the character to the right of the insertion cursor.
26. Meta-d deletes the word to the right of the insertion cursor.
27. Control-k deletes from the insertion cursor to the end of its line; if the insertion cursor is already at the end of a line, then Control-k deletes the newline character.
28. Control-o opens a new line by inserting a newline character in front of the insertion cursor without moving the insertion cursor.
29. Meta-backspace and Meta-Delete delete the word to the left of the insertion cursor.
30. Control-x deletes whatever is selected in the text widget after copying it to the clipboard.
31. Control-t reverses the order of the two characters to the right of the insertion cursor.
32. Control-z undoes the last edit action if the **-undo** option is true. Does nothing otherwise.
33. Control-Z (or Control-y on Windows) reapplies the last undone edit action if the **-undo** option is true. Does nothing otherwise.

  If the widget is disabled using the **-state** option, then its view can still be adjusted and text can still be selected, but no insertion cursor will be displayed and no text modifications will take place. 


 The behavior of texts can be changed by defining new bindings for individual widgets or by redefining the class bindings. 


Known issues
------------

 ### Issues concerning chars and indices

 Before Tk 8.5, the widget used the string “chars” to refer to index positions (which included characters, embedded windows and embedded images). As of Tk 8.5 the text widget deals separately and correctly with “chars” and “indices”. For backwards compatibility, however, the index modifiers “+N chars” and “-N chars” continue to refer to indices. One must use any of the full forms “+N any chars” or “-N any chars” etc. to refer to actual character indices. This confusion may be fixed in a future release by making the widget correctly interpret “+N chars” as a synonym for “+N any chars”. ### Performance issues

 Text widgets should run efficiently under a variety of conditions. The text widget uses about 2-3 bytes of main memory for each byte of text, so texts containing a megabyte or more should be practical on most workstations. Text is represented internally with a modified B-tree structure that makes operations relatively efficient even with large texts. Tags are included in the B-tree structure in a way that allows tags to span large ranges or have many disjoint smaller ranges without loss of efficiency. Marks are also implemented in a way that allows large numbers of marks. In most cases it is fine to have large numbers of unique tags, or a tag that has many distinct ranges.  One performance problem can arise if you have hundreds or thousands of different tags that all have the following characteristics: the first and last ranges of each tag are near the beginning and end of the text, respectively, or a single tag range covers most of the text widget. The cost of adding and deleting tags like this is proportional to the number of other tags with the same properties. In contrast, there is no problem with having thousands of distinct tags if their overall ranges are localized and spread uniformly throughout the text. 


 Very long text lines can be expensive, especially if they have many marks and tags within them. 


 The display line with the insert cursor is redrawn each time the cursor blinks, which causes a steady stream of graphics traffic. Set the **-insertofftime** attribute to 0 avoid this. 


### Known bugs

 The *pathName* **search -regexp** sub-command attempts to perform sophisticated regexp matching across multiple lines in an efficient fashion (since Tk 8.5), examining each line individually, and then in small groups of lines, whether searching forwards or backwards. Under certain conditions the search result might differ from that obtained by applying the same regexp to the entire text from the widget in one go. For example, when searching with a greedy regexp, the widget will continue to attempt to add extra lines to the match as long as one of two conditions are true: either Tcl's regexp library returns a code to indicate a longer match is possible (but there are known bugs in Tcl which mean this code is not always correctly returned); or if each extra line added results in at least a partial match with the pattern. This means in the case where the first extra line added results in no match and Tcl's regexp system returns the incorrect code and adding a second extra line would actually match, the text widget will return the wrong result. In practice this is a rare problem, but it can occur, for example: 
```
pack [**text** .t]
	.t insert 1.0 "aaaa\nbbbb\ncccc\nbbbb\naaaa\n"
	.t search -regexp -- {(a+|b+\nc+\nb+)+\na+} 1.0
```
 will not find a match when one exists of 19 characters starting from the first “b”.  Whenever one possible match is fully enclosed in another, the search command will attempt to ensure only the larger match is returned. When performing backwards regexp searches it is possible that Tcl will not always achieve this, in the case where a match is preceded by one or more short, non-overlapping matches, all of which are preceded by a large match which actually encompasses all of them. The search algorithm used by the widget does not look back arbitrarily far for a possible match which might cover large portions of the widget. For example: 



```
pack [**text** .t]
	.t insert 1.0 "aaaa\nbbbb\nbbbb\nbbbb\nbbbb\n"
	.t search -regexp -backward -- {b+\n|a+\n(b+\n)+} end
```
 matches at “5.0” when a true greedy match would match at “1.0”. Similarly if we add **-all** to this case, it matches at all of “5.0”, “4.0”, “3.0” and “1.0”, when really it should only match at “1.0” since that match encloses all the others. See also
--------

 **[entry](entry.htm)**, **[scrollbar](scrollbar.htm)** Copyright © 1992 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TkCmd/text.htm>

socket
======

  
[NAME](socket.htm#M2) socket — Open a TCP network connection 
[SYNOPSIS](socket.htm#M3) 
[DESCRIPTION](socket.htm#M4) 
[CLIENT SOCKETS](socket.htm#M5)  
[**-myaddr** *addr*](socket.htm#M6) 
[**-myport** *port*](socket.htm#M7) 
[**-async**](socket.htm#M8) 


 
[SERVER SOCKETS](socket.htm#M9)  
[**-myaddr** *addr*](socket.htm#M10) 
 
[CONFIGURATION OPTIONS](socket.htm#M11)  
[**-error**](socket.htm#M12) 
[**-sockname**](socket.htm#M13) 
[**-peername**](socket.htm#M14) 
[**-connecting**](socket.htm#M15) 



 
[EXAMPLES](socket.htm#M16) 
[HISTORY](socket.htm#M17) 
[SEE ALSO](socket.htm#M18) 
[KEYWORDS](socket.htm#M19) 









 Name
----

 socket — Open a TCP network connection Synopsis
--------

 **socket** ?*options*? *host port*  
 **socket** **-server** *command* ?*options*? *port*  
 Description
-----------

 This command opens a network socket and returns a channel identifier that may be used in future invocations of commands like **[read](read.htm)**, **[puts](puts.htm)** and **[flush](flush.htm)**. At present only the TCP network protocol is supported over IPv4 and IPv6; future releases may include support for additional protocols. The **socket** command may be used to open either the client or server side of a connection, depending on whether the **-server** switch is specified.  Note that the default encoding for *all* sockets is the system encoding, as returned by **[encoding system](encoding.htm)**. Most of the time, you will need to use **[chan configure](chan.htm)** to alter this to something else, such as *utf-8* (ideal for communicating with other Tcl processes) or *iso8859-1* (useful for many network protocols, especially the older ones). 


Client sockets
--------------

 If the **-server** option is not specified, then the client side of a connection is opened and the command returns a channel identifier that can be used for both reading and writing. *Port* and *host* specify a port to connect to; there must be a server accepting connections on this port. *Port* is an integer port number (or service name, where supported and understood by the host operating system) and *host* is either a domain-style name such as **www.tcl.tk** or a numerical IPv4 or IPv6 address such as **127.0.0.1** or **2001:DB8::1**. Use *localhost* to refer to the host on which the command is invoked.  The following options may also be present before *host* to specify additional information about the connection: 


 
**-myaddr** *addr*

 *Addr* gives the domain-style name or numerical IP address of the client-side network interface to use for the connection. This option may be useful if the client machine has multiple network interfaces. If the option is omitted then the client-side interface will be chosen by the system software. 


**-myport** *port*

 *Port* specifies an integer port number (or service name, where supported and understood by the host operating system) to use for the client's side of the connection. If this option is omitted, the client's port number will be chosen at random by the system software. 

**-async**
 This option will cause the client socket to be connected asynchronously. This means that the socket will be created immediately but may not yet be connected to the server, when the call to **socket** returns.  When a **[gets](gets.htm)** or **[flush](flush.htm)** is done on the socket before the connection attempt succeeds or fails, if the socket is in blocking mode, the operation will wait until the connection is completed or fails. If the socket is in nonblocking mode and a **[gets](gets.htm)** or **[flush](flush.htm)** is done on the socket before the connection attempt succeeds or fails, the operation returns immediately and **[fblocked](fblocked.htm)** on the socket returns 1. Synchronous client sockets may be switched (after they have connected) to operating in asynchronous mode using: 



```
**chan configure** *chan* **-blocking 0**
```
  See the **[chan configure](chan.htm)** command for more details. 


 The Tcl event loop should be running while an asynchronous connection is in progress, because it may have to do several connection attempts in the background. Running the event loop also allows you to set up a writable channel event on the socket to get notified when the asynchronous connection has succeeded or failed. See the **[vwait](vwait.htm)** and the **[chan](chan.htm)** commands for more details on the event loop and channel events. 


 The **[chan configure](chan.htm)** option **-connecting** may be used to check if the connect is still running. To verify a successful connect, the option **-error** may be checked when **-connecting** returned 0. 


Operation without the event queue requires at the moment calls to **[chan configure](chan.htm)** to advance the internal state machine. 



 Server sockets
--------------

 If the **-server** option is specified then the new socket will be a server that listens on the given *port* (either an integer or a service name, where supported and understood by the host operating system; if *port* is zero, the operating system will allocate a free port to the server socket which may be discovered by using **[chan configure](chan.htm)** to read the **-sockname** option). If the host supports both, IPv4 and IPv6, the socket will listen on both address families. Tcl will automatically accept connections to the given port. For each connection Tcl will create a new channel that may be used to communicate with the client. Tcl then invokes *command* (properly a command prefix list, see the **[EXAMPLES](#M16)** below) with three additional arguments: the name of the new channel, the address, in network address notation, of the client's host, and the client's port number.  The following additional option may also be specified before *port*: 


 
**-myaddr** *addr*

 *Addr* gives the domain-style name or numerical IP address of the server-side network interface to use for the connection. This option may be useful if the server machine has multiple network interfaces. If the option is omitted then the server socket is bound to the wildcard address so that it can accept connections from any interface. If *addr* is a domain name that resolves to multiple IP addresses that are available on the local machine, the socket will listen on all of them. 

  Server channels cannot be used for input or output; their sole use is to accept new client connections. The channels created for each incoming client connection are opened for input and output. Closing the server channel shuts down the server so that no new connections will be accepted; however, existing connections will be unaffected. 


 Server sockets depend on the Tcl event mechanism to find out when new connections are opened. If the application does not enter the event loop, for example by invoking the **[vwait](vwait.htm)** command or calling the C procedure **[Tcl\_DoOneEvent](https://www.tcl.tk/man/tcl/TclLib/DoOneEvent.htm)**, then no connections will be accepted. 


 If *port* is specified as zero, the operating system will allocate an unused port for use as a server socket. The port number actually allocated may be retrieved from the created server socket using the **[chan configure](chan.htm)** command to retrieve the **-sockname** option as described below. 


Configuration options
---------------------

 The **[chan configure](chan.htm)** command can be used to query several readonly configuration options for socket channels: 
 **-error**
 This option gets the current error status of the given socket. This is useful when you need to determine if an asynchronous connect operation succeeded. If there was an error, the error message is returned. If there was no error, an empty string is returned.  Note that the error status is reset by the read operation; this mimics the underlying getsockopt(SO\_ERROR) call. 



**-sockname**
 For client sockets (including the channels that get created when a client connects to a server socket) this option returns a list of three elements, the address, the host name and the port number for the socket. If the host name cannot be computed, the second element is identical to the address, the first element of the list.  For server sockets this option returns a list of a multiple of three elements each group of which have the same meaning as described above. The list contains more than one group when the server socket was created without **-myaddr** or with the argument to **-myaddr** being a domain name that resolves multiple IP addresses that are local to the invoking host. 



**-peername**
 This option is not supported by server sockets. For client and accepted sockets, this option returns a list of three elements; these are the address, the host name and the port to which the peer socket is connected or bound. If the host name cannot be computed, the second element of the list is identical to the address, its first element. 

**-connecting**
 This option is not supported by server sockets. For client sockets, this option returns 1 if an asyncroneous connect is still in progress, 0 otherwise. 


Examples
--------

 Here is a very simple time server: 

```
proc Server {startTime channel clientaddr clientport} {
    puts "Connection from $clientaddr registered"
    set now [clock seconds]
    puts $channel [clock format $now]
    puts $channel "[expr {$now - $startTime}] since start"
    close $channel
}

**socket -server** [list Server [clock seconds]] 9900
vwait forever
```
  And here is the corresponding client to talk to the server and extract some information: 



```
set server localhost
set sockChan [**socket** $server 9900]
gets $sockChan line1
gets $sockChan line2
close $sockChan
puts "The time on $server is $line1"
puts "That is [lindex $line2 0]s since the server started"
```
 History
-------

 Support for IPv6 was added in Tcl 8.6. See also
--------

 **[chan](chan.htm)**, **[flush](flush.htm)**, **[open](open.htm)**, **[read](read.htm)** Copyright © 1996 Sun Microsystems, Inc.  
 Copyright © 1998-1999 by Scriptics Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/socket.htm>

copy
====

 Name
----

 oo::copy — create copies of objects and classes Synopsis
--------

 package require TclOO  
   
 **oo::copy** *sourceObject* ?*targetObject*?  
 Description
-----------

 The **oo::copy** command creates a copy of an object or class. It takes the name of the object or class to be copied, *sourceObject*, and optionally the name of the object or class to create, *targetObject*, which will be resolved relative to the current namespace if not an absolute qualified name. If *targetObject* is omitted, a new name is chosen. The copied object will be of the same class as the source object, and will have all its per-object methods copied. If it is a class, it will also have all the class methods in the class copied, but it will not have any of its instances copied.  After the *targetObject* has been created and all definitions of its configuration (e.g., methods, filters, mixins) copied, the **<cloned>** method of *targetObject* will be invoked, to allow for customization of the created object such as installing related variable traces. The only argument given will be *sourceObject*. The default implementation of this method (in **[oo::object](object.htm)**) just copies the procedures and variables in the namespace of *sourceObject* to the namespace of *targetObject*. If this method call does not return a result that is successful (i.e., an error or other kind of exception) then the *targetObject* will be deleted and an error returned. 


 The result of the **oo::copy** command will be the fully-qualified name of the new object or class. 


Examples
--------

 This example creates an object, copies it, modifies the source object, and then demonstrates that the copied object is indeed a copy. 

```
oo::object create src
oo::objdefine src method msg {} {puts foo}
**oo::copy** src dst
oo::objdefine src method msg {} {puts bar}
src msg              *→ prints "bar"*
dst msg              *→ prints "foo"*
```
 See also
--------

 **[oo::class](class.htm)**, **[oo::define](define.htm)**, **[oo::object](object.htm)** Copyright © 2007 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/copy.htm>

cd
==

 Name
----

 cd — Change working directory Synopsis
--------

 **cd** ?*dirName*?  
 Description
-----------

 Change the current working directory to *dirName*, or to the home directory (as specified in the HOME environment variable) if *dirName* is not given. Returns an empty string. Note that the current working directory is a per-process resource; the **cd** command changes the working directory for all interpreters and (in a threaded environment) all threads. Examples
--------

 Change to the home directory of the user **fred**: 

```
**cd** ~fred
```
  Change to the directory **lib** that is a sibling directory of the current one: 



```
**cd** ../lib
```
 See also
--------

 **[filename](filename.htm)**, **[glob](glob.htm)**, **[pwd](pwd.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/cd.htm>

msgcat
======

  
[NAME](msgcat.htm#M2) msgcat — Tcl message catalog 
[SYNOPSIS](msgcat.htm#M3) 
[DESCRIPTION](msgcat.htm#M4) 
[COMMANDS](msgcat.htm#M5)  
[**::msgcat::mc** *src-string* ?*arg arg ...*?](msgcat.htm#M6) 
[**::msgcat::mcmax ?***src-string src-string ...*?](msgcat.htm#M7) 
[**::msgcat::mcexists** ?**-exactnamespace**? ?**-exactlocale**? *src-string*](msgcat.htm#M8) 


  
[**::msgcat::mclocale** ?*newLocale*?](msgcat.htm#M9) 
[**::msgcat::mcpreferences**](msgcat.htm#M10) 
[**::msgcat:mcloadedlocales subcommand** ?*locale*?](msgcat.htm#M11) 


  
[**::msgcat::mcload** *dirname*](msgcat.htm#M12) 
[**::msgcat::mcset** *locale src-string* ?*translate-string*?](msgcat.htm#M13) 
[**::msgcat::mcmset** *locale src-trans-list*](msgcat.htm#M14) 
[**::msgcat::mcflset** *src-string* ?*translate-string*?](msgcat.htm#M15) 
[**::msgcat::mcflmset** *src-trans-list*](msgcat.htm#M16) 
[**::msgcat::mcunknown** *locale src-string* ?*arg arg ...*?](msgcat.htm#M17) 
[**::msgcat::mcforgetpackage**](msgcat.htm#M18) 






 
[LOCALE SPECIFICATION](msgcat.htm#M19) 
[NAMESPACES AND MESSAGE CATALOGS](msgcat.htm#M20) 
[LOCATION AND FORMAT OF MESSAGE FILES](msgcat.htm#M21) 
[RECOMMENDED MESSAGE SETUP FOR PACKAGES](msgcat.htm#M22) 
[POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS](msgcat.htm#M23) 
[Package private locale](msgcat.htm#M24)  
[**::msgcat::mcpackagelocale set** ?*locale*?](msgcat.htm#M25) 
  
[**::msgcat::mcpackagelocale get**](msgcat.htm#M26) 
[**::msgcat::mcpackagelocale preferences**](msgcat.htm#M27) 
[**::msgcat::mcpackagelocale loaded**](msgcat.htm#M28) 
[**::msgcat::mcpackagelocale isset**](msgcat.htm#M29) 
[**::msgcat::mcpackagelocale unset**](msgcat.htm#M30) 
[**::msgcat::mcpackagelocale present** *locale*](msgcat.htm#M31) 
[**::msgcat::mcpackagelocale clear**](msgcat.htm#M32) 






 
[Changing package options](msgcat.htm#M33)  
[**::msgcat::mcpackageconfig get** *option*](msgcat.htm#M34) 
[**::msgcat::mcpackageconfig isset** *option*](msgcat.htm#M35) 
[**::msgcat::mcpackageconfig set** *option* *value*](msgcat.htm#M36) 
[**::msgcat::mcpackageconfig unset** *option*](msgcat.htm#M37) 



 
[Package options](msgcat.htm#M38)  
[**mcfolder**](msgcat.htm#M39) 
[**loadcmd**](msgcat.htm#M40) 

  
[**changecmd**](msgcat.htm#M41) 
  
[**unknowncmd**](msgcat.htm#M42) 
 
[Callback invocation](msgcat.htm#M43) 
[Examples](msgcat.htm#M44) 
[CREDITS](msgcat.htm#M45) 
[SEE ALSO](msgcat.htm#M46) 
[KEYWORDS](msgcat.htm#M47) 
















 Name
----

 msgcat — Tcl message catalog Synopsis
--------

 **package require Tcl 8.5**  
 **package require msgcat 1.6**  
 **::msgcat::mc** *src-string* ?*arg arg ...*?  
 **::msgcat::mcmax ?***src-string src-string ...*?  
 **::msgcat::mcexists** ?**-exactnamespace**? ?**-exactlocale**? *src-string*  
 **::msgcat::mclocale** ?*newLocale*?  
 **::msgcat::mcpreferences**  
 **::msgcat::mcloadedlocales subcommand** ?*locale*?  
 **::msgcat::mcload** *dirname*  
 **::msgcat::mcset** *locale src-string* ?*translate-string*?  
 **::msgcat::mcmset** *locale src-trans-list*  
 **::msgcat::mcflset** *src-string* ?*translate-string*?  
 **::msgcat::mcflmset** *src-trans-list*  
 **::msgcat::mcunknown** *locale src-string* ?*arg arg ...*?  
 **::msgcat::mcpackagelocale subcommand** ?*locale*?  
 **::msgcat::mcpackageconfig subcommand** *option* ?*value*?  
 **::msgcat::mcforgetpackage**  
 Description
-----------

 The **msgcat** package provides a set of functions that can be used to manage multi-lingual user interfaces. Text strings are defined in a “message catalog” which is independent from the application, and which can be edited or localized without modifying the application source code. New languages or locales may be provided by adding a new file to the message catalog.  **msgcat** distinguises packages by its namespace. Each package has its own message catalog and configuration settings in **msgcat**. 


 A *locale* is a specification string describing a user language like **de\_ch** for Swiss German. In **msgcat**, there is a global locale initialized by the system locale of the current system. Each package may decide to use the global locale or to use a package specific locale. 


 The global locale may be changed on demand, for example by a user initiated language change or within a multi user application like a web server. 


Commands
--------

  
**::msgcat::mc** *src-string* ?*arg arg ...*?
 Returns a translation of *src-string* according to the current locale. If additional arguments past *src-string* are given, the **[format](format.htm)** command is used to substitute the additional arguments in the translation of *src-string*.  **::msgcat::mc** will search the messages defined in the current namespace for a translation of *src-string*; if none is found, it will search in the parent of the current namespace, and so on until it reaches the global namespace. If no translation string exists, **::msgcat::mcunknown** is called and the string returned from **::msgcat::mcunknown** is returned. 


**::msgcat::mc** is the main function used to localize an application. Instead of using an English string directly, an application can pass the English string through **::msgcat::mc** and use the result. If an application is written for a single language in this fashion, then it is easy to add support for additional languages later simply by defining new message catalog entries. 




**::msgcat::mcmax ?***src-string src-string ...*?
 Given several source strings, **::msgcat::mcmax** returns the length of the longest translated string. This is useful when designing localized GUIs, which may require that all buttons, for example, be a fixed width (which will be the width of the widest button). 


**::msgcat::mcexists** ?**-exactnamespace**? ?**-exactlocale**? *src-string*

 Return true, if there is a translation for the given *src-string*. 


 The search may be limited by the option **-exactnamespace** to only check the current namespace and not any parent namespaces.  It may also be limited by the option **-exactlocale** to only check the first prefered locale (e.g. first element returned by **::msgcat::mcpreferences** if global locale is used). 



 
**::msgcat::mclocale** ?*newLocale*?
 This function sets the locale to *newLocale*. If *newLocale* is omitted, the current locale is returned, otherwise the current locale is set to *newLocale*. msgcat stores and compares the locale in a case-insensitive manner, and returns locales in lowercase. The initial locale is determined by the locale specified in the user's environment. See **[LOCALE SPECIFICATION](#M19)** below for a description of the locale string format.  If the locale is set, the preference list of locales is evaluated. Locales in this list are loaded now, if not jet loaded. 



**::msgcat::mcpreferences**
 Returns an ordered list of the locales preferred by the user, based on the user's language specification. The list is ordered from most specific to least preference. The list is derived from the current locale set in msgcat by **::msgcat::mclocale**, and cannot be set independently. For example, if the current locale is en\_US\_funky, then **::msgcat::mcpreferences** returns **{en\_us\_funky en\_us en {}}**. 


**::msgcat:mcloadedlocales subcommand** ?*locale*?
 This group of commands manage the list of loaded locales for packages not setting a package locale. 


 The subcommand **get** returns the list of currently loaded locales.  The subcommand **present** requires the argument *locale* and returns true, if this locale is loaded. 


 The subcommand **clear** removes all locales and their data, which are not in the current preference list. 



 
**::msgcat::mcload** *dirname*

 Searches the specified directory for files that match the language specifications returned by **::msgcat::mcloadedlocales get** (or **msgcat::mcpackagelocale preferences** if a package locale is set) (note that these are all lowercase), extended by the file extension “.msg”. Each matching file is read in order, assuming a UTF-8 encoding. The file contents are then evaluated as a Tcl script. This means that Unicode characters may be present in the message file either directly in their UTF-8 encoded form, or by use of the backslash-u quoting recognized by Tcl evaluation. The number of message files which matched the specification and were loaded is returned.  In addition, the given folder is stored in the **msgcat** package configuration option *mcfolder* to eventually load message catalog files required by a locale change. 




**::msgcat::mcset** *locale src-string* ?*translate-string*?
 Sets the translation for *src-string* to *translate-string* in the specified *locale* and the current namespace. If *translate-string* is not specified, *src-string* is used for both. The function returns *translate-string*. 


**::msgcat::mcmset** *locale src-trans-list*

 Sets the translation for multiple source strings in *src-trans-list* in the specified *locale* and the current namespace. *src-trans-list* must have an even number of elements and is in the form {*src-string translate-string* ?*src-string translate-string ...*?} **::msgcat::mcmset** can be significantly faster than multiple invocations of **::msgcat::mcset**. The function returns the number of translations set. 


**::msgcat::mcflset** *src-string* ?*translate-string*?
 Sets the translation for *src-string* to *translate-string* in the current namespace for the locale implied by the name of the message catalog being loaded via **::msgcat::mcload**. If *translate-string* is not specified, *src-string* is used for both. The function returns *translate-string*. 


**::msgcat::mcflmset** *src-trans-list*

 Sets the translation for multiple source strings in *src-trans-list* in the current namespace for the locale implied by the name of the message catalog being loaded via **::msgcat::mcload**. *src-trans-list* must have an even number of elements and is in the form {*src-string translate-string* ?*src-string translate-string ...*?} **::msgcat::mcflmset** can be significantly faster than multiple invocations of **::msgcat::mcflset**. The function returns the number of translations set. 


**::msgcat::mcunknown** *locale src-string* ?*arg arg ...*?
 This routine is called by **::msgcat::mc** in the case when a translation for *src-string* is not defined in the current locale. The default action is to return *src-string* passed by format if there are any arguments. This procedure can be redefined by the application, for example to log error messages for each unknown string. The **::msgcat::mcunknown** procedure is invoked at the same stack context as the call to **::msgcat::mc**. The return value of **::msgcat::mcunknown** is used as the return value for the call to **::msgcat::mc**.  Note that this routine is only called if the concerned package did not set a package locale unknown command name. 



**::msgcat::mcforgetpackage**
 The calling package clears all its state within the **msgcat** package including all settings and translations. 


Locale specification
--------------------

 The locale is specified to **msgcat** by a locale string passed to **::msgcat::mclocale**. The locale string consists of a language code, an optional country code, and an optional system-specific code, each separated by “\_”. The country and language codes are specified in standards ISO-639 and ISO-3166. For example, the locale “en” specifies English and “en\_US” specifies U.S. English.  When the msgcat package is first loaded, the locale is initialized according to the user's environment. The variables **env(LC\_ALL)**, **env(LC\_MESSAGES)**, and **env(LANG)** are examined in order. The first of them to have a non-empty value is used to determine the initial locale. The value is parsed according to the XPG4 pattern 



```
language[_country][.codeset][@modifier]
```
  to extract its parts. The initial locale is then set by calling **::msgcat::mclocale** with the argument 



```
language[_country][_modifier]
```
  On Windows and Cygwin, if none of those environment variables is set, msgcat will attempt to extract locale information from the registry. From Windows Vista on, the RFC4747 locale name "lang-script-country-options" is transformed to the locale as "lang\_country\_script" (Example: sr-Latn-CS -> sr\_cs\_latin). For Windows XP, the language id is transformed analoguously (Example: 0c1a -> sr\_yu\_cyrillic). If all these attempts to discover an initial locale from the user's environment fail, msgcat defaults to an initial locale of “C”. 


 When a locale is specified by the user, a “best match” search is performed during string translation. For example, if a user specifies en\_GB\_Funky, the locales “en\_gb\_funky”, “en\_gb”, “en” and “” (the empty string) are searched in order until a matching translation string is found. If no translation string is available, then the unknown handler is called. 


Namespaces and message catalogs
-------------------------------

 Strings stored in the message catalog are stored relative to the namespace from which they were added. This allows multiple packages to use the same strings without fear of collisions with other packages. It also allows the source string to be shorter and less prone to typographical error.  For example, executing the code 



```
**::msgcat::mcset** en hello "hello from ::"
namespace eval foo {
    **::msgcat::mcset** en hello "hello from ::foo"
}
puts [**::msgcat::mc** hello]
namespace eval foo {puts [**::msgcat::mc** hello]}
```
  will print 



```
hello from ::
hello from ::foo
```
  When searching for a translation of a message, the message catalog will search first the current namespace, then the parent of the current namespace, and so on until the global namespace is reached. This allows child namespaces to “inherit” messages from their parent namespace. 


 For example, executing (in the “en” locale) the code 



```
**::msgcat::mcset** en m1 ":: message1"
**::msgcat::mcset** en m2 ":: message2"
**::msgcat::mcset** en m3 ":: message3"
namespace eval ::foo {
    **::msgcat::mcset** en m2 "::foo message2"
    **::msgcat::mcset** en m3 "::foo message3"
}
namespace eval ::foo::bar {
    **::msgcat::mcset** en m3 "::foo::bar message3"
}
namespace import **::msgcat::mc**
puts "[**mc** m1]; [**mc** m2]; [**mc** m3]"
namespace eval ::foo {puts "[**mc** m1]; [**mc** m2]; [**mc** m3]"}
namespace eval ::foo::bar {puts "[**mc** m1]; [**mc** m2]; [**mc** m3]"}
```
  will print 



```
:: message1; :: message2; :: message3
:: message1; ::foo message2; ::foo message3
:: message1; ::foo message2; ::foo::bar message3
```
 Location and format of message files
------------------------------------

 Message files can be located in any directory, subject to the following conditions: 
1. All message files for a package are in the same directory.
2. The message file name is a msgcat locale specifier (all lowercase) followed by “.msg”. For example:



```
es.msg    — spanish
en_gb.msg — United Kingdom English
```
  *Exception:* The message file for the root locale “” is called “**ROOT.msg**”. This exception is made so as not to cause peculiar behavior, such as marking the message file as “hidden” on Unix file systems. 


1. The file contains a series of calls to **mcflset** and **mcflmset**, setting the necessary translation strings for the language, likely enclosed in a **[namespace eval](namespace.htm)** so that all source strings are tied to the namespace of the package. For example, a short **es.msg** might contain:



```
namespace eval ::mypackage {
    **::msgcat::mcflset** "Free Beer" "Cerveza Gratis"
}
```
 Recommended message setup for packages
--------------------------------------

 If a package is installed into a subdirectory of the **[tcl\_pkgPath](tclvars.htm)** and loaded via **[package require](package.htm)**, the following procedure is recommended. 
1. During package installation, create a subdirectory **msgs** under your package directory.
2. Copy your \*.msg files into that directory.
3. Add the following command to your package initialization script:



```
# load language files, stored in msgs subdirectory
**::msgcat::mcload** [file join [file dirname [info script]] msgs]
```
 Positional codes for format and scan commands
---------------------------------------------

 It is possible that a message string used as an argument to **[format](format.htm)** might have positionally dependent parameters that might need to be repositioned. For example, it might be syntactically desirable to rearrange the sentence structure while translating. 

```
format "We produced %d units in location %s" $num $city
format "In location %s we produced %d units" $city $num
```
  This can be handled by using the positional parameters: 



```
format "We produced %1\$d units in location %2\$s" $num $city
format "In location %2\$s we produced %1\$d units" $num $city
```
  Similarly, positional parameters can be used with **[scan](scan.htm)** to extract values from internationalized strings. Note that it is not necessary to pass the output of **::msgcat::mc** to **[format](format.htm)** directly; by passing the values to substitute in as arguments, the formatting substitution is done directly. 



```
**msgcat::mc** {Produced %1$d at %2$s} $num $city
# ... where that key is mapped to one of the
# human-oriented versions by **msgcat::mcset**
```
 Package private locale
----------------------

 A package using **msgcat** may choose to use its own package private locale and its own set of loaded locales, independent to the global locale set by **::msgcat::mclocale**.  This allows a package to change its locale without causing any locales load or removal in other packages and not to invoke the global locale change callback (see below). 


 This action is controled by the following ensemble: 


 
**::msgcat::mcpackagelocale set** ?*locale*?
 Set or change a package private locale. The package private locale is set to the given *locale* if the *locale* is given. If the option *locale* is not given, the package is set to package private locale mode, but no locale is changed (e.g. if the global locale was valid for the package before, it is copied to the package private locale). 


 This command may cause the load of locales. 
 **::msgcat::mcpackagelocale get**
 Return the package private locale or the global locale, if no package private locale is set. 

**::msgcat::mcpackagelocale preferences**
 Return the package private preferences or the global preferences, if no package private locale is set. 

**::msgcat::mcpackagelocale loaded**
 Return the list of locales loaded for this package. 

**::msgcat::mcpackagelocale isset**
 Returns true, if a package private locale is set. 

**::msgcat::mcpackagelocale unset**
 Unset the package private locale and use the globale locale. Load and remove locales to adjust the list of loaded locales for the package to the global loaded locales list. 


**::msgcat::mcpackagelocale present** *locale*

 Returns true, if the given locale is loaded for the package. 

**::msgcat::mcpackagelocale clear**
 Clear any loaded locales of the package not present in the package preferences. 


Changing package options
------------------------

 Each package using msgcat has a set of options within **msgcat**. The package options are described in the next sectionPackage options. Each package option may be set or unset individually using the following ensemble: 
 
**::msgcat::mcpackageconfig get** *option*

 Return the current value of the given *option*. This call returns an error if the option is not set for the package. 


**::msgcat::mcpackageconfig isset** *option*

 Returns 1, if the given *option* is set for the package, 0 otherwise. 


**::msgcat::mcpackageconfig set** *option* *value*

 Set the given *option* to the given *value*. This may invoke additional actions in dependency of the *option*. The return value is 0 or the number of loaded packages for the option **mcfolder**. 


**::msgcat::mcpackageconfig unset** *option*

 Unsets the given *option* for the package. No action is taken if the *option* is not set for the package. The empty string is returned. 

 ### Package options

 The following package options are available for each package: 
 **mcfolder**
 This is the message folder of the package. This option is set by mcload and by the subcommand set. Both are identical and both return the number of loaded message catalog files.  Setting or changing this value will load all locales contained in the preferences valid for the package. This implies also to invoke any set loadcmd (see below). 


Unsetting this value will disable message file load for the package. 



**loadcmd**
 This callback is invoked before a set of message catalog files are loaded for the package which has this property set. 


 This callback may be used to do any preparation work for message file load or to get the message data from another source like a data base. In this case, no message files are used (mcfolder is unset).  See section **callback invocation** below. The parameter list appended to this callback is the list of locales to load. 


 If this callback is changed, it is called with the preferences valid for the package. 



 **changecmd**
 This callback is invoked when a default local change was performed. Its purpose is to allow a package to update any dependency on the default locale like showing the GUI in another language. 


 See the callback invocation section below. The parameter list appended to this callback is **mcpreferences**. The registered callbacks are invoked in no particular order. 
 **unknowncmd**
 Use a package locale mcunknown procedure instead of the standard version supplied by the msgcat package (msgcat::mcunknown). 


 The called procedure must return the formatted message which will finally be returned by msgcat::mc.  A generic unknown handler is used if set to the empty string. This consists in returning the key if no arguments are given. With given arguments, format is used to process the arguments. 


 See section **callback invocation** below. The appended arguments are identical to **::msgcat::mcunknown**. 


 ### Callback invocation

 A package may decide to register one or multiple callbacks, as described above.  Callbacks are invoked, if: 


 1. the callback command is set, 


 2. the command is not the empty string, 


 3. the registering namespace exists. 


 If a called routine fails with an error, the **[bgerror](bgerror.htm)** routine for the interpreter is invoked after command completion. Only exception is the callback **unknowncmd**, where an error causes the invoking **mc**-command to fail with that error. 


### Examples

 Packages which display a GUI may update their widgets when the global locale changes. To register to a callback, use: 
```
namespace eval gui {
    msgcat::mcpackageconfig changecmd updateGUI

    proc updateGui args {
        puts "New locale is '[lindex $args 0]'."
    }
}
% msgcat::mclocale fr
fr
% New locale is 'fr'.
```
  If locales (or additional locales) are contained in another source like a data base, a package may use the load callback and not mcload: 



```
namespace eval db {
    msgcat::mcpackageconfig loadcmd loadMessages

    proc loadMessages args {
        foreach locale $args {
            if {[LocaleInDB $locale]} {
                msgcat::mcmset $locale [GetLocaleList $locale]
            }
        }
    }
}
```
  The **[clock](clock.htm)** command implementation uses **msgcat** with a package locale to implement the command line parameter **-locale**. Here are some sketches of the implementation: 


 First, a package locale is initialized and the generic unknown function is desactivated: 



```
msgcat::mcpackagelocale set
msgcat::mcpackageconfig unknowncmd ""
```
 As an example, the user requires the week day in a certain locale as follows: 
```
clock format clock seconds -format %A -locale fr
```
 **[clock](clock.htm)** sets the package locale to **fr** and looks for the day name as follows: 
```
msgcat::mcpackagelocale set $locale
return [lindex [msgcat::mc DAYS_OF_WEEK_FULL] $day]
### Returns "mercredi"
```
 Within **[clock](clock.htm)**, some message-catalog items are heavy in computation and thus are dynamically cached using: 
```
proc ::tcl::clock::LocalizeFormat { locale format } {
    set key FORMAT_$format
    if { [::msgcat::mcexists -exactlocale -exactnamespace $key] } {
        return [mc $key]
    }
    #...expensive computation of format clipped...
    mcset $locale $key $format
    return $format
}
```
 Credits
-------

 The message catalog code was developed by Mark Harrison. See also
--------

 **[format](format.htm)**, **[scan](scan.htm)**, **[namespace](namespace.htm)**, **[package](package.htm)** Copyright © 1998 Mark Harrison. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/msgcat.htm>

glob
====

  
[NAME](glob.htm#M2) glob — Return names of files that match patterns 
[SYNOPSIS](glob.htm#M3) 
[DESCRIPTION](glob.htm#M4) 
[OPTIONS](glob.htm#M5)  
[**-directory** *directory*](glob.htm#M6) 
[**-join**](glob.htm#M7) 
[**-nocomplain**](glob.htm#M8) 
[**-path** *pathPrefix*](glob.htm#M9) 
[**-tails**](glob.htm#M10) 
[**-types** *typeList*](glob.htm#M11) 
[**--**](glob.htm#M12) 






 
[GLOBBING PATTERNS](glob.htm#M13)  
[**?**](glob.htm#M14) 
[**\***](glob.htm#M15) 
[**[***chars***]**](glob.htm#M16) 
[**\***x*](glob.htm#M17) 
[**{***a***,***b***,***...*}](glob.htm#M18) 




 
[WINDOWS PORTABILITY ISSUES](glob.htm#M19) 
[EXAMPLES](glob.htm#M20) 
[SEE ALSO](glob.htm#M21) 
[KEYWORDS](glob.htm#M22) 








 Name
----

 glob — Return names of files that match patterns Synopsis
--------

 **glob** ?*switches*? ?*pattern ...*?  
 Description
-----------

 This command performs file name “globbing” in a fashion similar to the csh shell or bash shell. It returns a list of the files whose names match any of the *pattern* arguments. No particular order is guaranteed in the list, so if a sorted list is required the caller should use **[lsort](lsort.htm)**. ### Options

 If the initial arguments to **glob** start with **-** then they are treated as switches. The following switches are currently supported: 
 
**-directory** *directory*

 Search for files which match the given patterns starting in the given *directory*. This allows searching of directories whose name contains glob-sensitive characters without the need to quote such characters explicitly. This option may not be used in conjunction with **-path**, which is used to allow searching for complete file paths whose names may contain glob-sensitive characters. 

**-join**
 The remaining pattern arguments, after option processing, are treated as a single pattern obtained by joining the arguments with directory separators. 

**-nocomplain**
 Allows an empty list to be returned without error; without this switch an error is returned if the result list would be empty. 


**-path** *pathPrefix*

 Search for files with the given *pathPrefix* where the rest of the name matches the given patterns. This allows searching for files with names similar to a given file (as opposed to a directory) even when the names contain glob-sensitive characters. This option may not be used in conjunction with **-directory**. For example, to find all files with the same root name as $path, but differing extensions, you should use “**glob -path [file rootname $path] .\***” which will work even if **$path** contains numerous glob-sensitive characters. 

**-tails**
 Only return the part of each file found which follows the last directory named in any **-directory** or **-path** path specification. Thus “**glob -tails -directory $dir \***” is equivalent to “**set pwd [pwd]; cd $dir; glob \*; cd $pwd**”. For **-path** specifications, the returned names will include the last path segment, so “**glob -tails -path [file rootname ~/foo.tex] .\***” will return paths like **foo.aux foo.bib foo.tex** etc. 


**-types** *typeList*

 Only list files or directories which match *typeList*, where the items in the list have two forms. The first form is like the -type option of the Unix find command: *b* (block special file), *c* (character special file), *d* (directory), *f* (plain file), *l* (symbolic link), *p* (named pipe), or *s* (socket), where multiple types may be specified in the list. **Glob** will return all files which match at least one of the types given. Note that symbolic links will be returned both if **-types l** is given, or if the target of a link matches the requested type. So, a link to a directory will be returned if **-types d** was specified.  The second form specifies types where all the types given must match. These are *r*, *w*, *x* as file permissions, and *readonly*, *hidden* as special permission cases. On the Macintosh, MacOS types and creators are also supported, where any item which is four characters long is assumed to be a MacOS type (e.g. **[TEXT](../tkcmd/text.htm)**). Items which are of the form *{macintosh type XXXX}* or *{macintosh creator XXXX}* will match types or creators respectively. Unrecognized types, or specifications of multiple MacOS types/creators will signal an error. 


 The two forms may be mixed, so **-types {d f r w}** will find all regular files OR directories that have both read AND write permissions. The following are equivalent: 



```
**glob -type d \***
**glob \*/**
```
 except that the first case doesn't return the trailing “/” and is more platform independent. 



**--**
 Marks the end of switches. The argument following this one will be treated as a *pattern* even if it starts with a **-**. 

 ### Globbing patterns

 The *pattern* arguments may contain any of the following special characters, which are a superset of those supported by **[string match](string.htm)**: 
 **?**
 Matches any single character. 

**\***
 Matches any sequence of zero or more characters. 


**[***chars***]**

 Matches any single character in *chars*. If *chars* contains a sequence of the form *a***-***b* then any character between *a* and *b* (inclusive) will match. 


**\***x*

 Matches the character *x*. 


**{***a***,***b***,***...*}
 Matches any of the sub-patterns *a*, *b*, etc. 

  On Unix, as with csh, a “.” at the beginning of a file's name or just after a “/” must be matched explicitly or with a {} construct, unless the **-types hidden** flag is given (since “.” at the beginning of a file's name indicates that it is hidden). On other platforms, files beginning with a “.” are handled no differently to any others, except the special directories “.” and “..” which must be matched explicitly (this is to avoid a recursive pattern like “glob -join \* \* \* \*” from recursing up the directory hierarchy as well as down). In addition, all “/” characters must be matched explicitly. 


 If the first character in a *pattern* is “~” then it refers to the home directory for the user whose name follows the “~”. If the “~” is followed immediately by “/” then the value of the HOME environment variable is used. 


 The **glob** command differs from csh globbing in two ways. First, it does not sort its result list (use the **[lsort](lsort.htm)** command if you want the list sorted). Second, **glob** only returns the names of files that actually exist; in csh no check for existence is made unless a pattern contains a ?, \*, or [] construct. 


 When the **glob** command returns relative paths whose filenames start with a tilde “~” (for example through **glob \*** or **glob -tails**, the returned list will not quote the tilde with “./”. This means care must be taken if those names are later to be used with **[file join](file.htm)**, to avoid them being interpreted as absolute paths pointing to a given user's home directory. 


Windows portability issues
--------------------------

 For Windows UNC names, the servername and sharename components of the path may not contain ?, \*, or [] constructs. On Windows NT, if *pattern* is of the form “**~***username***@***domain*”, it refers to the home directory of the user whose account information resides on the specified NT domain server. Otherwise, user account information is obtained from the local computer.  Since the backslash character has a special meaning to the glob command, glob patterns containing Windows style path separators need special care. The pattern “*C:\\foo\\\**” is interpreted as “*C:\foo\\**” where “*\f*” will match the single character “*f*” and “*\\**” will match the single character “*\**” and will not be interpreted as a wildcard character. One solution to this problem is to use the Unix style forward slash as a path separator. Windows style paths can be converted to Unix style paths with the command “**[file join](file.htm)** **$path**” or “**[file normalize](file.htm)** **$path**”. 


Examples
--------

 Find all the Tcl files in the current directory: 

```
**glob** *.tcl
```
  Find all the Tcl files in the user's home directory, irrespective of what the current directory is: 



```
**glob** -directory ~ *.tcl
```
  Find all subdirectories of the current directory: 



```
**glob** -type d *
```
  Find all files whose name contains an “a”, a “b” or the sequence “cde”: 



```
**glob** -type f *{a,b,cde}*
```
 See also
--------

 **[file](file.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/glob.htm>

unknown
=======

 Name
----

 unknown — Handle attempts to use non-existent commands Synopsis
--------

 **unknown** *cmdName* ?*arg arg ...*?  
 Description
-----------

 This command is invoked by the Tcl interpreter whenever a script tries to invoke a command that does not exist. The default implementation of **unknown** is a library procedure defined when Tcl initializes an interpreter. You can override the default **unknown** to change its functionality, or you can register a new handler for individual namespaces using the **[namespace unknown](namespace.htm)** command. Note that there is no default implementation of **unknown** in a safe interpreter.  If the Tcl interpreter encounters a command name for which there is not a defined command (in either the current namespace, or the global namespace), then Tcl checks for the existence of an unknown handler for the current namespace. By default, this handler is a command named **::unknown**. If there is no such command, then the interpreter returns an error. If the **unknown** command exists (or a new handler has been registered for the current namespace), then it is invoked with arguments consisting of the fully-substituted name and arguments for the original non-existent command. The **unknown** command typically does things like searching through library directories for a command procedure with the name *cmdName*, or expanding abbreviated command names to full-length, or automatically executing unknown commands as sub-processes. In some cases (such as expanding abbreviations) **unknown** will change the original command slightly and then (re-)execute it. The result of the **unknown** command is used as the result for the original non-existent command. 


 The default implementation of **unknown** behaves as follows. It first calls the **[auto\_load](library.htm)** library procedure to load the command. If this succeeds, then it executes the original command with its original arguments. If the auto-load fails then **unknown** calls **[auto\_execok](library.htm)** to see if there is an executable file by the name *cmd*. If so, it invokes the Tcl **[exec](exec.htm)** command with *cmd* and all the *args* as arguments. If *cmd* cannot be auto-executed, **unknown** checks to see if the command was invoked at top-level and outside of any script. If so, then **unknown** takes two additional steps. First, it sees if *cmd* has one of the following three forms: **!!**, **!***event*, or **^***old***^***new*?**^**?. If so, then **unknown** carries out history substitution in the same way that **csh** would for these constructs. Finally, **unknown** checks to see if *cmd* is a unique abbreviation for an existing Tcl command. If so, it expands the command name and executes the command with the original arguments. If none of the above efforts has been able to execute the command, **unknown** generates an error return. If the global variable **auto\_noload** is defined, then the auto-load step is skipped. If the global variable **auto\_noexec** is defined then the auto-exec step is skipped. Under normal circumstances the return value from **unknown** is the return value from the command that was eventually executed. 


Example
-------

 Arrange for the **unknown** command to have its standard behavior except for first logging the fact that a command was not found: 

```
# Save the original one so we can chain to it
rename **unknown** _original_unknown

# Provide our own implementation
proc **unknown** args {
    puts stderr "WARNING: unknown command: $args"
    uplevel 1 [list _original_unknown {*}$args]
}
```
 See also
--------

 **[info](info.htm)**, **[proc](proc.htm)**, **[interp](interp.htm)**, **[library](library.htm)**, **[namespace](namespace.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/unknown.htm>

catch
=====

 Name
----

 catch — Evaluate script and trap exceptional returns Synopsis
--------

 **catch** *script* ?*resultVarName*? ?*optionsVarName*?  
 Description
-----------

 The **catch** command may be used to prevent errors from aborting command interpretation. The **catch** command calls the Tcl interpreter recursively to execute *script*, and always returns without raising an error, regardless of any errors that might occur while executing *script*.  If *script* raises an error, **catch** will return a non-zero integer value corresponding to the exceptional return code returned by evaluation of *script*. Tcl defines the normal return code from script evaluation to be zero (0), or **TCL\_OK**. Tcl also defines four exceptional return codes: 1 (**TCL\_ERROR**), 2 (**TCL\_RETURN**), 3 (**TCL\_BREAK**), and 4 (**TCL\_CONTINUE**). Errors during evaluation of a script are indicated by a return code of **TCL\_ERROR**. The other exceptional return codes are returned by the **[return](return.htm)**, **[break](break.htm)**, and **[continue](continue.htm)** commands and in other special situations as documented. Tcl packages can define new commands that return other integer values as return codes as well, and scripts that make use of the **return -code** command can also have return codes other than the five defined by Tcl. 


 If the *resultVarName* argument is given, then the variable it names is set to the result of the script evaluation. When the return code from the script is 1 (**TCL\_ERROR**), the value stored in *resultVarName* is an error message. When the return code from the script is 0 (**TCL\_OK**), the value stored in *resultVarName* is the value returned from *script*. 


 If the *optionsVarName* argument is given, then the variable it names is set to a dictionary of return options returned by evaluation of *script*. Tcl specifies two entries that are always defined in the dictionary: **-code** and **-level**. When the return code from evaluation of *script* is not **TCL\_RETURN**, the value of the **-level** entry will be 0, and the value of the **-code** entry will be the same as the return code. Only when the return code is **TCL\_RETURN** will the values of the **-level** and **-code** entries be something else, as further described in the documentation for the **[return](return.htm)** command. 


 When the return code from evaluation of *script* is **TCL\_ERROR**, four additional entries are defined in the dictionary of return options stored in *optionsVarName*: **-errorinfo**, **-errorcode**, **-errorline**, and **-errorstack**. The value of the **-errorinfo** entry is a formatted stack trace containing more information about the context in which the error happened. The formatted stack trace is meant to be read by a person. The value of the **-errorcode** entry is additional information about the error stored as a list. The **-errorcode** value is meant to be further processed by programs, and may not be particularly readable by people. The value of the **-errorline** entry is an integer indicating which line of *script* was being evaluated when the error occurred. The value of the **-errorstack** entry is an even-sized list made of token-parameter pairs accumulated while unwinding the stack. The token may be “**CALL**”, in which case the parameter is a list made of the proc name and arguments at the corresponding level; or it may be “**UP**”, in which case the parameter is the relative level (as in **[uplevel](uplevel.htm)**) of the previous **CALL**. The salient differences with respect to **-errorinfo** are that: 


1. it is a machine-readable form that is amenable to processing with [**[foreach](foreach.htm)** {tok prm} ...],
2. it contains the true (substituted) values passed to the functions, instead of the static text of the calling sites, and
3. it is coarser-grained, with only one element per stack frame (like procs; no separate elements for **[foreach](foreach.htm)** constructs for example).

  The values of the **-errorinfo** and **-errorcode** entries of the most recent error are also available as values of the global variables **::errorInfo** and **::errorCode** respectively. The value of the **-errorstack** entry surfaces as **[info errorstack](info.htm)**. 


 Tcl packages may provide commands that set other entries in the dictionary of return options, and the **[return](return.htm)** command may be used by scripts to set return options in addition to those defined above. 


Examples
--------

 The **catch** command may be used in an **[if](if.htm)** to branch based on the success of a script. 

```
if { [**catch** {open $someFile w} fid] } {
    puts stderr "Could not open $someFile for writing\n$fid"
    exit 1
}
```
  There are more complex examples of **catch** usage in the documentation for the **[return](return.htm)** command. 


See also
--------

 **[break](break.htm)**, **[continue](continue.htm)**, **[dict](dict.htm)**, **[error](error.htm)**, **[errorCode](tclvars.htm)**, **[errorInfo](tclvars.htm)**, **[info](info.htm)**, **[return](return.htm)** Copyright © 1993-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/catch.htm>

subst
=====

 Name
----

 subst — Perform backslash, command, and variable substitutions Synopsis
--------

 **subst** ?**-nobackslashes**? ?**-nocommands**? ?**-novariables**? *string*  
 Description
-----------

 This command performs variable substitutions, command substitutions, and backslash substitutions on its *string* argument and returns the fully-substituted result. The substitutions are performed in exactly the same way as for Tcl commands. As a result, the *string* argument is actually substituted twice, once by the Tcl parser in the usual fashion for Tcl commands, and again by the *subst* command.  If any of the **-nobackslashes**, **-nocommands**, or **-novariables** are specified, then the corresponding substitutions are not performed. For example, if **-nocommands** is specified, command substitution is not performed: open and close brackets are treated as ordinary characters with no special interpretation. 


 Note that the substitution of one kind can include substitution of other kinds. For example, even when the **-novariables** option is specified, command substitution is performed without restriction. This means that any variable substitution necessary to complete the command substitution will still take place. Likewise, any command substitution necessary to complete a variable substitution will take place, even when **-nocommands** is specified. See the **[EXAMPLES](#M5)** below. 


 If an error occurs during substitution, then **subst** will return that error. If a break exception occurs during command or variable substitution, the result of the whole substitution will be the string (as substituted) up to the start of the substitution that raised the exception. If a continue exception occurs during the evaluation of a command or variable substitution, an empty string will be substituted for that entire command or variable substitution (as long as it is well-formed Tcl.) If a return exception occurs, or any other return code is returned during command or variable substitution, then the returned value is substituted for that substitution. See the **[EXAMPLES](#M5)** below. In this way, all exceptional return codes are “caught” by **subst**. The **subst** command itself will either return an error, or will complete successfully. 


Examples
--------

 When it performs its substitutions, *subst* does not give any special treatment to double quotes or curly braces (except within command substitutions) so the script 

```
set a 44
**subst** {xyz {$a}}
```
  returns “**xyz {44}**”, not “**xyz {$a}**” and the script 



```
set a "p\} q \{r"
**subst** {xyz {$a}}
```
  returns “**xyz {p} q {r}**”, not “**xyz {p\} q \{r}**”. 


 When command substitution is performed, it includes any variable substitution necessary to evaluate the script. 



```
set a 44
**subst** -novariables {$a [format $a]}
```
  returns “**$a 44**”, not “**$a $a**”. Similarly, when variable substitution is performed, it includes any command substitution necessary to retrieve the value of the variable. 



```
proc b {} {return c}
array set a {c c [b] tricky}
**subst** -nocommands {[b] $a([b])}
```
  returns “**[b] c**”, not “**[b] tricky**”. 


 The continue and break exceptions allow command substitutions to prevent substitution of the rest of the command substitution and the rest of *string* respectively, giving script authors more options when processing text using *subst*. For example, the script 



```
**subst** {abc,[break],def}
```
  returns “**abc,**”, not “**abc,,def**” and the script 



```
**subst** {abc,[continue;expr {1+2}],def}
```
  returns “**abc,,def**”, not “**abc,3,def**”. 


 Other exceptional return codes substitute the returned value 



```
**subst** {abc,[return foo;expr {1+2}],def}
```
  returns “**abc,foo,def**”, not “**abc,3,def**” and 



```
**subst** {abc,[return -code 10 foo;expr {1+2}],def}
```
  also returns “**abc,foo,def**”, not “**abc,3,def**”. 


See also
--------

 **[Tcl](tcl.htm)**, **[eval](eval.htm)**, **[break](break.htm)**, **[continue](continue.htm)** Copyright © 1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2001 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/subst.htm>

history
=======

  
[NAME](history.htm#M2) history — Manipulate the history list 
[SYNOPSIS](history.htm#M3) 
[DESCRIPTION](history.htm#M4)  
[**history**](history.htm#M5) 
[**history add** *command* ?**exec**?](history.htm#M6) 
[**history change** *newValue* ?*event*?](history.htm#M7) 
[**history clear**](history.htm#M8) 
[**history event** ?*event*?](history.htm#M9) 
[**history info** ?*count*?](history.htm#M10) 
[**history keep** ?*count*?](history.htm#M11) 
[**history nextid**](history.htm#M12) 
[**history redo** ?*event*?](history.htm#M13) 








 
[HISTORY REVISION](history.htm#M14) 
[KEYWORDS](history.htm#M15) 




 Name
----

 history — Manipulate the history list Synopsis
--------

 **history** ?*option*? ?*arg arg ...*?  
 Description
-----------

 The **history** command performs one of several operations related to recently-executed commands recorded in a history list. Each of these recorded commands is referred to as an “event”. When specifying an event to the **history** command, the following forms may be used: 
1. A number: if positive, it refers to the event with that number (all events are numbered starting at 1). If the number is negative, it selects an event relative to the current event (**-1** refers to the previous event, **-2** to the one before that, and so on). Event **0** refers to the current event.
2. A string: selects the most recent event that matches the string. An event is considered to match the string either if the string is the same as the first characters of the event, or if the string matches the event in the sense of the **[string match](string.htm)** command.

  The **history** command can take any of the following forms: 


 **history**
 Same as **history info**, described below. 


**history add** *command* ?**exec**?
 Adds the *command* argument to the history list as a new event. If **exec** is specified (or abbreviated) then the command is also executed and its result is returned. If **exec** is not specified then an empty string is returned as result. 


**history change** *newValue* ?*event*?
 Replaces the value recorded for an event with *newValue*. *Event* specifies the event to replace, and defaults to the *current* event (not event **-1**). This command is intended for use in commands that implement new forms of history substitution and wish to replace the current event (which invokes the substitution) with the command created through substitution. The return value is an empty string. 

**history clear**
 Erase the history list. The current keep limit is retained. The history event numbers are reset. 


**history event** ?*event*?
 Returns the value of the event given by *event*. *Event* defaults to **-1**. 


**history info** ?*count*?
 Returns a formatted string (intended for humans to read) giving the event number and contents for each of the events in the history list except the current event. If *count* is specified then only the most recent *count* events are returned. 


**history keep** ?*count*?
 This command may be used to change the size of the history list to *count* events. Initially, 20 events are retained in the history list. If *count* is not specified, the current keep limit is returned. 

**history nextid**
 Returns the number of the next event to be recorded in the history list. It is useful for things like printing the event number in command-line prompts. 


**history redo** ?*event*?
 Re-executes the command indicated by *event* and returns its result. *Event* defaults to **-1**. This command results in history revision: see below for details. 

 History revision
----------------

 Pre-8.0 Tcl had a complex history revision mechanism. The current mechanism is more limited, and the old history operations **substitute** and **words** have been removed. (As a consolation, the **clear** operation was added.)  The history option **redo** results in much simpler “history revision”. When this option is invoked then the most recent event is modified to eliminate the history command and replace it with the result of the history command. If you want to redo an event without modifying history, then use the **[event](../tkcmd/event.htm)** operation to retrieve some event, and the **add** operation to add it to history and execute it. 

 Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/history.htm>

unset
=====

 Name
----

 unset — Delete variables Synopsis
--------

 **unset** ?**-nocomplain**? ?**--**? ?*name name name ...*?  
 Description
-----------

 This command removes one or more variables. Each *name* is a variable name, specified in any of the ways acceptable to the **[set](set.htm)** command. If a *name* refers to an element of an array then that element is removed without affecting the rest of the array. If a *name* consists of an array name with no parenthesized index, then the entire array is deleted. The **unset** command returns an empty string as result. If **-nocomplain** is specified as the first argument, any possible errors are suppressed. The option may not be abbreviated, in order to disambiguate it from possible variable names. The option **--** indicates the end of the options, and should be used if you wish to remove a variable with the same name as any of the options. If an error occurs during variable deletion, any variables after the named one causing the error are not deleted. An error can occur when the named variable does not exist, or the name refers to an array element but the variable is a scalar, or the name refers to a variable in a non-existent namespace. Example
-------

 Create an array containing a mapping from some numbers to their squares and remove the array elements for non-prime numbers: 

```
array set squares {
    1 1    6 36
    2 4    7 49
    3 9    8 64
    4 16   9 81
    5 25  10 100
}

puts "The squares are:"
parray squares

**unset** squares(1) squares(4) squares(6)
**unset** squares(8) squares(9) squares(10)

puts "The prime squares are:"
parray squares
```
 See also
--------

 **[set](set.htm)**, **[trace](trace.htm)**, **[upvar](upvar.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2000 Ajuba Solutions. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/unset.htm>

tailcall
========

 Name
----

 tailcall — Replace the current procedure with another command Synopsis
--------

 **tailcall** *command* ?*arg ...*?  
 Description
-----------

 The **tailcall** command replaces the currently executing procedure, lambda application, or method with another command. The *command*, which will have *arg ...* passed as arguments if they are supplied, will be looked up in the current namespace context, not in the caller's. Apart from that difference in resolution, it is equivalent to: 

```
return [uplevel 1 [list *command* ?*arg ...*?]]
```
  This command may not be invoked from within an **[uplevel](uplevel.htm)** into a procedure or inside a **[catch](catch.htm)** inside a procedure or lambda. 


Example
-------

 Compute the factorial of a number. 

```
proc factorial {n {accum 1}} {
    if {$n < 2} {
        return $accum
    }
    **tailcall** factorial [expr {$n - 1}] [expr {$accum * $n}]
}
```
  Print the elements of a list with alternating lines having different indentations. 



```
proc printList {theList} {
    if {[llength $theList]} {
        puts "> [lindex $theList 0]"
        **tailcall** printList2 [lrange $theList 1 end]
    }
}
proc printList2 {theList} {
    if {[llength $theList]} {
        puts "< [lindex $theList 0]"
        **tailcall** printList [lrange $theList 1 end]
    }
}
```
 See also
--------

 **[apply](apply.htm)**, **[proc](proc.htm)**, **[uplevel](uplevel.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/tailcall.htm>

trace
=====

  
[NAME](trace.htm#M2) trace — Monitor variable accesses, command usages and command executions 
[SYNOPSIS](trace.htm#M3) 
[DESCRIPTION](trace.htm#M4)  
[**trace add** *type name ops ?args?*](trace.htm#M5)  
[**trace add command** *name ops commandPrefix*](trace.htm#M6)  
[**rename**](trace.htm#M7) 
[**delete**](trace.htm#M8) 

 
[**trace add execution** *name ops commandPrefix*](trace.htm#M9)  
[**enter**](trace.htm#M10) 
[**leave**](trace.htm#M11) 
[**enterstep**](trace.htm#M12) 
[**leavestep**](trace.htm#M13) 



 
[**trace add variable** *name ops commandPrefix*](trace.htm#M14)  
[**array**](trace.htm#M15) 
[**read**](trace.htm#M16) 
[**write**](trace.htm#M17) 
[**unset**](trace.htm#M18) 



 


 
[**trace remove** *type name opList commandPrefix*](trace.htm#M19)  
[**trace remove command** *name opList commandPrefix*](trace.htm#M20) 
[**trace remove execution** *name opList commandPrefix*](trace.htm#M21) 
[**trace remove variable** *name opList commandPrefix*](trace.htm#M22) 


 
[**trace info** *type name*](trace.htm#M23)  
[**trace info command** *name*](trace.htm#M24) 
[**trace info execution** *name*](trace.htm#M25) 
[**trace info variable** *name*](trace.htm#M26) 


 


  
[**trace variable** *name ops command*](trace.htm#M27) 
[**trace vdelete** *name ops command*](trace.htm#M28) 
[**trace vinfo** *name*](trace.htm#M29) 


 
[EXAMPLES](trace.htm#M30) 
[SEE ALSO](trace.htm#M31) 
[KEYWORDS](trace.htm#M32) 





 Name
----

 trace — Monitor variable accesses, command usages and command executions Synopsis
--------

 **trace** *option* ?*arg arg ...*?  
 Description
-----------

 This command causes Tcl commands to be executed whenever certain operations are invoked. The legal *option*s (which may be abbreviated) are: 
 
**trace add** *type name ops ?args?*

 Where *type* is **command**, **execution**, or **[variable](variable.htm)**. 
 
**trace add command** *name ops commandPrefix*

 Arrange for *commandPrefix* to be executed (with additional arguments) whenever command *name* is modified in one of the ways given by the list *ops*. *Name* will be resolved using the usual namespace resolution rules used by commands. If the command does not exist, an error will be thrown.  *Ops* indicates which operations are of interest, and is a list of one or more of the following items: 


 **rename**
 Invoke *commandPrefix* whenever the traced command is renamed. Note that renaming to the empty string is considered deletion, and will not be traced with “**[rename](rename.htm)**”. 

**delete**
 Invoke *commandPrefix* when the traced command is deleted. Commands can be deleted explicitly by using the **[rename](rename.htm)** command to rename the command to an empty string. Commands are also deleted when the interpreter is deleted, but traces will not be invoked because there is no interpreter in which to execute them. 

  When the trace triggers, depending on the operations being traced, a number of arguments are appended to *commandPrefix* so that the actual command is as follows: 



```
*commandPrefix oldName newName op*
```
 *OldName* and *newName* give the traced command's current (old) name, and the name to which it is being renamed (the empty string if this is a “delete” operation). *Op* indicates what operation is being performed on the command, and is one of **[rename](rename.htm)** or **delete** as defined above. The trace operation cannot be used to stop a command from being deleted. Tcl will always remove the command once the trace is complete. Recursive renaming or deleting will not cause further traces of the same type to be evaluated, so a delete trace which itself deletes the command, or a rename trace which itself renames the command will not cause further trace evaluations to occur. Both *oldName* and *newName* are fully qualified with any namespace(s) in which they appear. 




**trace add execution** *name ops commandPrefix*

 Arrange for *commandPrefix* to be executed (with additional arguments) whenever command *name* is executed, with traces occurring at the points indicated by the list *ops*. *Name* will be resolved using the usual namespace resolution rules used by commands. If the command does not exist, an error will be thrown.  *Ops* indicates which operations are of interest, and is a list of one or more of the following items: 


 **enter**
 Invoke *commandPrefix* whenever the command *name* is executed, just before the actual execution takes place. 

**leave**
 Invoke *commandPrefix* whenever the command *name* is executed, just after the actual execution takes place. 

**enterstep**
 Invoke *commandPrefix* for every Tcl command which is executed from the start of the execution of the procedure *name* until that procedure finishes. *CommandPrefix* is invoked just before the actual execution of the Tcl command being reported takes place. For example if we have “proc foo {} { puts "hello" }”, then an *enterstep* trace would be invoked just before “*puts "hello"*” is executed. Setting an *enterstep* trace on a command *name* that does not refer to a procedure will not result in an error and is simply ignored. 

**leavestep**
 Invoke *commandPrefix* for every Tcl command which is executed from the start of the execution of the procedure *name* until that procedure finishes. *CommandPrefix* is invoked just after the actual execution of the Tcl command being reported takes place. Setting a *leavestep* trace on a command *name* that does not refer to a procedure will not result in an error and is simply ignored. 

  When the trace triggers, depending on the operations being traced, a number of arguments are appended to *commandPrefix* so that the actual command is as follows: 


 For **enter** and **enterstep** operations: 



```
*commandPrefix command-string op*
```
  *Command-string* gives the complete current command being executed (the traced command for a **enter** operation, an arbitrary command for a **enterstep** operation), including all arguments in their fully expanded form. *Op* indicates what operation is being performed on the command execution, and is one of **enter** or **enterstep** as defined above. The trace operation can be used to stop the command from executing, by deleting the command in question. Of course when the command is subsequently executed, an “invalid command” error will occur. 


 For **leave** and **leavestep** operations: 



```
*commandPrefix command-string code result op*
```
  *Command-string* gives the complete current command being executed (the traced command for a **enter** operation, an arbitrary command for a **enterstep** operation), including all arguments in their fully expanded form. *Code* gives the result code of that execution, and *result* the result string. *Op* indicates what operation is being performed on the command execution, and is one of **leave** or **leavestep** as defined above. Note that the creation of many **enterstep** or **leavestep** traces can lead to unintuitive results, since the invoked commands from one trace can themselves lead to further command invocations for other traces. 


 *CommandPrefix* executes in the same context as the code that invoked the traced operation: thus the *commandPrefix*, if invoked from a procedure, will have access to the same local variables as code in the procedure. This context may be different than the context in which the trace was created. If *commandPrefix* invokes a procedure (which it normally does) then the procedure will have to use **[upvar](upvar.htm)** or **[uplevel](uplevel.htm)** commands if it wishes to access the local variables of the code which invoked the trace operation. 


 While *commandPrefix* is executing during an execution trace, traces on *name* are temporarily disabled. This allows the *commandPrefix* to execute *name* in its body without invoking any other traces again. If an error occurs while executing the *commandPrefix*, then the command *name* as a whole will return that same error. 


 When multiple traces are set on *name*, then for *enter* and *enterstep* operations, the traced commands are invoked in the reverse order of how the traces were originally created; and for *leave* and *leavestep* operations, the traced commands are invoked in the original order of creation. 


The behavior of execution traces is currently undefined for a command *name* imported into another namespace. 




**trace add variable** *name ops commandPrefix*

 Arrange for *commandPrefix* to be executed whenever variable *name* is accessed in one of the ways given by the list *ops*. *Name* may refer to a normal variable, an element of an array, or to an array as a whole (i.e. *name* may be just the name of an array, with no parenthesized index). If *name* refers to a whole array, then *commandPrefix* is invoked whenever any element of the array is manipulated. If the variable does not exist, it will be created but will not be given a value, so it will be visible to **[namespace which](namespace.htm)** queries, but not to **[info exists](info.htm)** queries.  *Ops* indicates which operations are of interest, and is a list of one or more of the following items: 


 **array**
 Invoke *commandPrefix* whenever the variable is accessed or modified via the **[array](array.htm)** command, provided that *name* is not a scalar variable at the time that the **[array](array.htm)** command is invoked. If *name* is a scalar variable, the access via the **[array](array.htm)** command will not trigger the trace. 

**read**
 Invoke *commandPrefix* whenever the variable is read. 

**write**
 Invoke *commandPrefix* whenever the variable is written. 

**unset**
 Invoke *commandPrefix* whenever the variable is unset. Variables can be unset explicitly with the **[unset](unset.htm)** command, or implicitly when procedures return (all of their local variables are unset). Variables are also unset when interpreters are deleted, but traces will not be invoked because there is no interpreter in which to execute them. 

  When the trace triggers, three arguments are appended to *commandPrefix* so that the actual command is as follows: 



```
*commandPrefix name1 name2 op*
```
  *Name1* and *name2* give the name(s) for the variable being accessed: if the variable is a scalar then *name1* gives the variable's name and *name2* is an empty string; if the variable is an array element then *name1* gives the name of the array and name2 gives the index into the array; if an entire array is being deleted and the trace was registered on the overall array, rather than a single element, then *name1* gives the array name and *name2* is an empty string. *Name1* and *name2* are not necessarily the same as the name used in the **trace variable** command: the **[upvar](upvar.htm)** command allows a procedure to reference a variable under a different name. *Op* indicates what operation is being performed on the variable, and is one of **[read](read.htm)**, **write**, or **[unset](unset.htm)** as defined above. 


 *CommandPrefix* executes in the same context as the code that invoked the traced operation: if the variable was accessed as part of a Tcl procedure, then *commandPrefix* will have access to the same local variables as code in the procedure. This context may be different than the context in which the trace was created. If *commandPrefix* invokes a procedure (which it normally does) then the procedure will have to use **[upvar](upvar.htm)** or **[uplevel](uplevel.htm)** if it wishes to access the traced variable. Note also that *name1* may not necessarily be the same as the name used to set the trace on the variable; differences can occur if the access is made through a variable defined with the **[upvar](upvar.htm)** command. 


 For read and write traces, *commandPrefix* can modify the variable to affect the result of the traced operation. If *commandPrefix* modifies the value of a variable during a read or write trace, then the new value will be returned as the result of the traced operation. The return value from *commandPrefix* is ignored except that if it returns an error of any sort then the traced operation also returns an error with the same error message returned by the trace command (this mechanism can be used to implement read-only variables, for example). For write traces, *commandPrefix* is invoked after the variable's value has been changed; it can write a new value into the variable to override the original value specified in the write operation. To implement read-only variables, *commandPrefix* will have to restore the old value of the variable. 


 While *commandPrefix* is executing during a read or write trace, traces on the variable are temporarily disabled. This means that reads and writes invoked by *commandPrefix* will occur directly, without invoking *commandPrefix* (or any other traces) again. However, if *commandPrefix* unsets the variable then unset traces will be invoked. 


 When an unset trace is invoked, the variable has already been deleted: it will appear to be undefined with no traces. If an unset occurs because of a procedure return, then the trace will be invoked in the variable context of the procedure being returned to: the stack frame of the returning procedure will no longer exist. Traces are not disabled during unset traces, so if an unset trace command creates a new trace and accesses the variable, the trace will be invoked. Any errors in unset traces are ignored. 


 If there are multiple traces on a variable they are invoked in order of creation, most-recent first. If one trace returns an error, then no further traces are invoked for the variable. If an array element has a trace set, and there is also a trace set on the array as a whole, the trace on the overall array is invoked before the one on the element. 


 Once created, the trace remains in effect either until the trace is removed with the **trace remove variable** command described below, until the variable is unset, or until the interpreter is deleted. Unsetting an element of array will remove any traces on that element, but will not remove traces on the overall array. 


This command returns an empty string. 






**trace remove** *type name opList commandPrefix*

 Where *type* is either **command**, **execution** or **[variable](variable.htm)**. 
 
**trace remove command** *name opList commandPrefix*

 If there is a trace set on command *name* with the operations and command given by *opList* and *commandPrefix*, then the trace is removed, so that *commandPrefix* will never again be invoked. Returns an empty string. If *name* does not exist, the command will throw an error. 


**trace remove execution** *name opList commandPrefix*

 If there is a trace set on command *name* with the operations and command given by *opList* and *commandPrefix*, then the trace is removed, so that *commandPrefix* will never again be invoked. Returns an empty string. If *name* does not exist, the command will throw an error. 


**trace remove variable** *name opList commandPrefix*

 If there is a trace set on variable *name* with the operations and command given by *opList* and *commandPrefix*, then the trace is removed, so that *commandPrefix* will never again be invoked. Returns an empty string. 




**trace info** *type name*

 Where *type* is either **command**, **execution** or **[variable](variable.htm)**. 
 
**trace info command** *name*

 Returns a list containing one element for each trace currently set on command *name*. Each element of the list is itself a list containing two elements, which are the *opList* and *commandPrefix* associated with the trace. If *name* does not have any traces set, then the result of the command will be an empty string. If *name* does not exist, the command will throw an error. 


**trace info execution** *name*

 Returns a list containing one element for each trace currently set on command *name*. Each element of the list is itself a list containing two elements, which are the *opList* and *commandPrefix* associated with the trace. If *name* does not have any traces set, then the result of the command will be an empty string. If *name* does not exist, the command will throw an error. 


**trace info variable** *name*

 Returns a list containing one element for each trace currently set on variable *name*. Each element of the list is itself a list containing two elements, which are the *opList* and *commandPrefix* associated with the trace. If *name* does not exist or does not have any traces set, then the result of the command will be an empty string. 



  For backwards compatibility, three other subcommands are available: 


 
**trace variable** *name ops command*

 This is equivalent to **trace add variable** *name ops command*. 


**trace vdelete** *name ops command*

 This is equivalent to **trace remove variable** *name ops command*


**trace vinfo** *name*

 This is equivalent to **trace info variable** *name*

  These subcommands are deprecated and will likely be removed in a future version of Tcl. They use an older syntax in which **[array](array.htm)**, **[read](read.htm)**, **write**, **[unset](unset.htm)** are replaced by **a**, **r**, **w** and **u** respectively, and the *ops* argument is not a list, but simply a string concatenation of the operations, such as **rwua**. 


Examples
--------

 Print a message whenever either of the global variables **foo** and **bar** are updated, even if they have a different local name at the time (which can be done with the **[upvar](upvar.htm)** command): 

```
proc tracer {varname args} {
    upvar #0 $varname var
    puts "$varname was updated to be \"$var\""
}
**trace add** variable foo write "tracer foo"
**trace add** variable bar write "tracer bar"
```
  Ensure that the global variable **foobar** always contains the product of the global variables **foo** and **bar**: 



```
proc doMult args {
    global foo bar foobar
    set foobar [expr {$foo * $bar}]
}
**trace add** variable foo write doMult
**trace add** variable bar write doMult
```
  Print a trace of what commands are executed during the processing of a Tcl procedure: 



```
proc x {} { y }
proc y {} { z }
proc z {} { puts hello }
proc report args {puts [info level 0]}
**trace add** execution x enterstep report
x
  → *report y enterstep*
    *report z enterstep*
    *report {puts hello} enterstep*
    *hello*
```
 See also
--------

 **[set](set.htm)**, **[unset](unset.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2000 Ajuba Solutions. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/trace.htm>

unload
======

  
[NAME](unload.htm#M2) unload — Unload machine code 
[SYNOPSIS](unload.htm#M3) 
[DESCRIPTION](unload.htm#M4)  
[**-nocomplain**](unload.htm#M5) 
[**-keeplibrary**](unload.htm#M6) 
[**--**](unload.htm#M7) 


 
[UNLOAD OPERATION](unload.htm#M8) 
[UNLOAD HOOK PROTOTYPE](unload.htm#M9) 
[NOTES](unload.htm#M10) 
[PORTABILITY ISSUES](unload.htm#M11)  
[**Unix**](unload.htm#M12) 
 
[BUGS](unload.htm#M13) 
[EXAMPLE](unload.htm#M14) 
[SEE ALSO](unload.htm#M15) 
[KEYWORDS](unload.htm#M16) 










 Name
----

 unload — Unload machine code Synopsis
--------

 **unload** ?*switches*? *fileName*  
 **unload** ?*switches*? *fileName packageName*  
 **unload** ?*switches*? *fileName packageName interp*  
 Description
-----------

 This command tries to unload shared libraries previously loaded with **[load](load.htm)** from the application's address space. *fileName* is the name of the file containing the library file to be unload; it must be the same as the filename provided to **[load](load.htm)** for loading the library. The *packageName* argument is the name of the package (as determined by or passed to **[load](load.htm)**), and is used to compute the name of the unload procedure; if not supplied, it is computed from *fileName* in the same manner as **[load](load.htm)**. The *interp* argument is the path name of the interpreter from which to unload the package (see the **[interp](interp.htm)** manual entry for details); if *interp* is omitted, it defaults to the interpreter in which the **unload** command was invoked.  If the initial arguments to **unload** start with **-** then they are treated as switches. The following switches are currently supported: 


 **-nocomplain**
 Suppresses all error messages. If this switch is given, **unload** will never report an error. 

**-keeplibrary**
 This switch will prevent **unload** from issuing the operating system call that will unload the library from the process. 

**--**
 Marks the end of switches. The argument following this one will be treated as a *fileName* even if it starts with a **-**. 

 ### Unload operation

 When a file containing a shared library is loaded through the **[load](load.htm)** command, Tcl associates two reference counts to the library file. The first counter shows how many times the library has been loaded into normal (trusted) interpreters while the second describes how many times the library has been loaded into safe interpreters. As a file containing a shared library can be loaded only once by Tcl (with the first **[load](load.htm)** call on the file), these counters track how many interpreters use the library. Each subsequent call to **[load](load.htm)** after the first simply increments the proper reference count.  **unload** works in the opposite direction. As a first step, **unload** will check whether the library is unloadable: an unloadable library exports a special unload procedure. The name of the unload procedure is determined by *packageName* and whether or not the target interpreter is a safe one. For normal interpreters the name of the initialization procedure will have the form *pkg***\_Unload**, where *pkg* is the same as *packageName* except that the first letter is converted to upper case and all other letters are converted to lower case. For example, if *packageName* is **foo** or **FOo**, the initialization procedure's name will be **Foo\_Unload**. If the target interpreter is a safe interpreter, then the name of the initialization procedure will be *pkg***\_SafeUnload** instead of *pkg***\_Unload**. 


 If **unload** determines that a library is not unloadable (or unload functionality has been disabled during compilation), an error will be returned. If the library is unloadable, then **unload** will call the unload procedure. If the unload procedure returns **[TCL\_OK](catch.htm)**, **unload** will proceed and decrease the proper reference count (depending on the target interpreter type). When both reference counts have reached 0, the library will be detached from the process. 


### Unload hook prototype

 The unload procedure must match the following prototype: 

```
typedef int **Tcl\_PackageUnloadProc**(
        [Tcl\_Interp](https://www.tcl.tk/man/tcl/TclLib/Interp.htm) **interp*,
        int *flags*);
```
  The *interp* argument identifies the interpreter from which the library is to be unloaded. The unload procedure must return **[TCL\_OK](catch.htm)** or **[TCL\_ERROR](catch.htm)** to indicate whether or not it completed successfully; in the event of an error it should set the interpreter's result to point to an error message. In this case, the result of the **unload** command will be the result returned by the unload procedure. 


 The *flags* argument can be either **TCL\_UNLOAD\_DETACH\_FROM\_INTERPRETER** or **TCL\_UNLOAD\_DETACH\_FROM\_PROCESS**. In case the library will remain attached to the process after the unload procedure returns (i.e. because the library is used by other interpreters), **TCL\_UNLOAD\_DETACH\_FROM\_INTERPRETER** will be defined. However, if the library is used only by the target interpreter and the library will be detached from the application as soon as the unload procedure returns, the *flags* argument will be set to **TCL\_UNLOAD\_DETACH\_FROM\_PROCESS**. 


### Notes

 The **unload** command cannot unload libraries that are statically linked with the application. If *fileName* is an empty string, then the *packageName* argument must be specified.  If *packageName* is omitted or specified as an empty string, Tcl tries to guess the name of the package. This may be done differently on different platforms. The default guess, which is used on most UNIX platforms, is to take the last element of *fileName*, strip off the first three characters if they are **lib**, and use any following alphabetic and underline characters as the module name. For example, the command **unload libxyz4.2.so** uses the module name **xyz** and the command **unload bin/last.so {}** uses the module name **last**. 


Portability issues
------------------

  **Unix**
 Not all unix operating systems support library unloading. Under such an operating system **unload** returns an error (unless **-nocomplain** has been specified). 

 Bugs
----

 If the same file is **[load](load.htm)**ed by different *fileName*s, it will be loaded into the process's address space multiple times. The behavior of this varies from system to system (some systems may detect the redundant loads, others may not). In case a library has been silently detached by the operating system (and as a result Tcl thinks the library is still loaded), it may be dangerous to use **unload** on such a library (as the library will be completely detached from the application while some interpreters will continue to use it). Example
-------

 If an unloadable module in the file **foobar.dll** had been loaded using the **[load](load.htm)** command like this (on Windows): 

```
load c:/some/dir/foobar.dll
```
  then it would be unloaded like this: 



```
**unload** c:/some/dir/foobar.dll
```
  This allows a C code module to be installed temporarily into a long-running Tcl program and then removed again (either because it is no longer needed or because it is being updated with a new version) without having to shut down the overall Tcl process. 


See also
--------

 **[info sharedlibextension](info.htm)**, **[load](load.htm)**, **[safe](safe.htm)** Copyright © 2003 George Petasis <petasis(at)iit.demokritos.gr>. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/unload.htm>

update
======

 Name
----

 update — Process pending events and idle callbacks Synopsis
--------

 **update** ?**idletasks**?  
 Description
-----------

 This command is used to bring the application “up to date” by entering the event loop repeatedly until all pending events (including idle callbacks) have been processed.  If the **idletasks** keyword is specified as an argument to the command, then no new events or errors are processed; only idle callbacks are invoked. This causes operations that are normally deferred, such as display updates and window layout calculations, to be performed immediately. 


 The **update idletasks** command is useful in scripts where changes have been made to the application's state and you want those changes to appear on the display immediately, rather than waiting for the script to complete. Most display updates are performed as idle callbacks, so **update idletasks** will cause them to run. However, there are some kinds of updates that only happen in response to events, such as those triggered by window size changes; these updates will not occur in **update idletasks**. 


 The **update** command with no options is useful in scripts where you are performing a long-running computation but you still want the application to respond to events such as user interactions; if you occasionally call **update** then user input will be processed during the next call to **update**. 


Example
-------

 Run computations for about a second and then finish: 

```
set x 1000
set done 0
after 1000 set done 1
while {!$done} {
    # A very silly example!
    set x [expr {log($x) ** 2.8}]

    # Test to see if our time-limit has been hit.  This would
    # also give a chance for serving network sockets and, if
    # the Tk package is loaded, updating a user interface.
    **update**
}
```
 See also
--------

 **[after](after.htm)**, **[interp](interp.htm)** Copyright © 1990-1992 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/update.htm>

switch
======

  
[NAME](switch.htm#M2) switch — Evaluate one of several scripts, depending on a given value 
[SYNOPSIS](switch.htm#M3) 
[DESCRIPTION](switch.htm#M4)  
[**-exact**](switch.htm#M5) 
[**-glob**](switch.htm#M6) 
[**-regexp**](switch.htm#M7) 
[**-nocase**](switch.htm#M8) 
[**-matchvar** *varName*](switch.htm#M9) 
[**-indexvar** *varName*](switch.htm#M10) 
[**--**](switch.htm#M11) 






 
[EXAMPLES](switch.htm#M12) 
[SEE ALSO](switch.htm#M13) 
[KEYWORDS](switch.htm#M14) 





 Name
----

 switch — Evaluate one of several scripts, depending on a given value Synopsis
--------

 **switch** ?*options*? *string pattern body* ?*pattern body* ...?  
 **switch** ?*options*? *string* {*pattern body* ?*pattern body* ...?}  
 Description
-----------

 The **switch** command matches its *string* argument against each of the *pattern* arguments in order. As soon as it finds a *pattern* that matches *string* it evaluates the following *body* argument by passing it recursively to the Tcl interpreter and returns the result of that evaluation. If the last *pattern* argument is **default** then it matches anything. If no *pattern* argument matches *string* and no default is given, then the **switch** command returns an empty string.  If the initial arguments to **switch** start with **-** then they are treated as options unless there are exactly two arguments to **switch** (in which case the first must the *string* and the second must be the *pattern*/*body* list). The following options are currently supported: 


 **-exact**
 Use exact matching when comparing *string* to a pattern. This is the default. 

**-glob**
 When matching *string* to the patterns, use glob-style matching (i.e. the same as implemented by the **[string match](string.htm)** command). 

**-regexp**
 When matching *string* to the patterns, use regular expression matching (as described in the **[re\_syntax](re_syntax.htm)** reference page). 

**-nocase**
 Causes comparisons to be handled in a case-insensitive manner. 


**-matchvar** *varName*

 This option (only legal when **-regexp** is also specified) specifies the name of a variable into which the list of matches found by the regular expression engine will be written. The first element of the list written will be the overall substring of the input string (i.e. the *string* argument to **switch**) matched, the second element of the list will be the substring matched by the first capturing parenthesis in the regular expression that matched, and so on. When a **default** branch is taken, the variable will have the empty list written to it. This option may be specified at the same time as the **-indexvar** option. 


**-indexvar** *varName*

 This option (only legal when **-regexp** is also specified) specifies the name of a variable into which the list of indices referring to matching substrings found by the regular expression engine will be written. The first element of the list written will be a two-element list specifying the index of the start and index of the first character after the end of the overall substring of the input string (i.e. the *string* argument to **switch**) matched, in a similar way to the **-indices** option to the **[regexp](regexp.htm)** can obtain. Similarly, the second element of the list refers to the first capturing parenthesis in the regular expression that matched, and so on. When a **default** branch is taken, the variable will have the empty list written to it. This option may be specified at the same time as the **-matchvar** option. 

**--**
 Marks the end of options. The argument following this one will be treated as *string* even if it starts with a **-**. This is not required when the matching patterns and bodies are grouped together in a single argument. 

  Two syntaxes are provided for the *pattern* and *body* arguments. The first uses a separate argument for each of the patterns and commands; this form is convenient if substitutions are desired on some of the patterns or commands. The second form places all of the patterns and commands together into a single argument; the argument must have proper list structure, with the elements of the list being the patterns and commands. The second form makes it easy to construct multi-line switch commands, since the braces around the whole list make it unnecessary to include a backslash at the end of each line. Since the *pattern* arguments are in braces in the second form, no command or variable substitutions are performed on them; this makes the behavior of the second form different than the first form in some cases. 


 If a *body* is specified as “**-**” it means that the *body* for the next pattern should also be used as the body for this pattern (if the next pattern also has a body of “**-**” then the body after that is used, and so on). This feature makes it possible to share a single *body* among several patterns. 


 Beware of how you place comments in **switch** commands. Comments should only be placed **inside** the execution body of one of the patterns, and not intermingled with the patterns. 


Examples
--------

 The **switch** command can match against variables and not just literals, as shown here (the result is *2*): 

```
set foo "abc"
**switch** abc a - b {expr {1}} $foo {expr {2}} default {expr {3}}
```
  Using glob matching and the fall-through body is an alternative to writing regular expressions with alternations, as can be seen here (this returns *1*): 



```
**switch** -glob aaab {
    a*b     -
    b       {expr {1}}
    a*      {expr {2}}
    default {expr {3}}
}
```
  Whenever nothing matches, the **default** clause (which must be last) is taken. This example has a result of *3*: 



```
**switch** xyz {
    a -
    b {
        # Correct Comment Placement
        expr {1}
    }
    c {
        expr {2}
    }
    default {
        expr {3}
    }
}
```
  When matching against regular expressions, information about what exactly matched is easily obtained using the **-matchvar** option: 



```
**switch** -regexp -matchvar foo -- $bar {
    a(b*)c {
        puts "Found [string length [lindex $foo 1]] 'b's"
    }
    d(e*)f(g*)h {
        puts "Found [string length [lindex $foo 1]] 'e's and\
                [string length [lindex $foo 2]] 'g's"
    }
}
```
 See also
--------

 **[for](for.htm)**, **[if](if.htm)**, **[regexp](regexp.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/switch.htm>

if
==

 Name
----

 if — Execute scripts conditionally Synopsis
--------

 **if** *expr1* ?**then**? *body1* **elseif** *expr2* ?**then**? *body2* **elseif** ... ?**else**? ?*bodyN*?  
 Description
-----------

 The *if* command evaluates *expr1* as an expression (in the same way that **[expr](expr.htm)** evaluates its argument). The value of the expression must be a boolean (a numeric value, where 0 is false and anything is true, or a string value such as **true** or **yes** for true and **false** or **no** for false); if it is true then *body1* is executed by passing it to the Tcl interpreter. Otherwise *expr2* is evaluated as an expression and if it is true then **body2** is executed, and so on. If none of the expressions evaluates to true then *bodyN* is executed. The **then** and **else** arguments are optional “noise words” to make the command easier to read. There may be any number of **elseif** clauses, including zero. *BodyN* may also be omitted as long as **else** is omitted too. The return value from the command is the result of the body script that was executed, or an empty string if none of the expressions was non-zero and there was no *bodyN*. Examples
--------

 A simple conditional: 

```
**if** {$vbl == 1} { puts "vbl is one" }
```
  With an **else**-clause: 



```
**if** {$vbl == 1} {
    puts "vbl is one"
} **else** {
    puts "vbl is not one"
}
```
  With an **elseif**-clause too: 



```
**if** {$vbl == 1} {
    puts "vbl is one"
} **elseif** {$vbl == 2} {
    puts "vbl is two"
} **else** {
    puts "vbl is not one or two"
}
```
  Remember, expressions can be multi-line, but in that case it can be a good idea to use the optional **then** keyword for clarity: 



```
**if** {
    $vbl == 1
    || $vbl == 2
    || $vbl == 3
} **then** {
    puts "vbl is one, two or three"
}
```
 See also
--------

 **[expr](expr.htm)**, **[for](for.htm)**, **[foreach](foreach.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/if.htm>

object
======

  
[NAME](object.htm#M2) oo::object — root class of the class hierarchy 
[SYNOPSIS](object.htm#M3) 
[CLASS HIERARCHY](object.htm#M4) 
[DESCRIPTION](object.htm#M5) 
[CONSTRUCTOR](object.htm#M6) 
[DESTRUCTOR](object.htm#M7) 
[EXPORTED METHODS](object.htm#M8)  
[*obj* **destroy**](object.htm#M9) 
 
[NON-EXPORTED METHODS](object.htm#M10)  
[*obj* **eval** ?*arg ...*?](object.htm#M11) 
[*obj* **unknown ?***methodName*? ?*arg ...*?](object.htm#M12) 
[*obj* **variable** ?*varName ...*?](object.htm#M13) 
[*obj* **varname** *varName*](object.htm#M14) 
[*obj* **<cloned>** *sourceObjectName*](object.htm#M15) 




 
[EXAMPLES](object.htm#M16) 
[SEE ALSO](object.htm#M17) 
[KEYWORDS](object.htm#M18) 










 Name
----

 oo::object — root class of the class hierarchy Synopsis
--------

 package require TclOO  
   
 **oo::object** *method* ?*arg ...*?  
 Class hierarchy
---------------

 **oo::object**  
 Description
-----------

 The **oo::object** class is the root class of the object hierarchy; every object is an instance of this class. Since classes are themselves objects, they are instances of this class too. Objects are always referred to by their name, and may be **[rename](rename.htm)**d while maintaining their identity.  Instances of objects may be made with either the **create** or **new** methods of the **oo::object** object itself, or by invoking those methods on any of the subclass objects; see **[oo::class](class.htm)** for more details. The configuration of individual objects (i.e., instance-specific methods, mixed-in classes, etc.) may be controlled with the **[oo::objdefine](define.htm)** command. 


 Each object has a unique namespace associated with it, the instance namespace. This namespace holds all the instance variables of the object, and will be the current namespace whenever a method of the object is invoked (including a method of the class of the object). When the object is destroyed, its instance namespace is deleted. The instance namespace contains the object's **[my](my.htm)** command, which may be used to invoke non-exported methods of the object or to create a reference to the object for the purpose of invocation which persists across renamings of the object. 


### Constructor

 The **oo::object** class does not define an explicit constructor. ### Destructor

 The **oo::object** class does not define an explicit destructor. ### Exported methods

 The **oo::object** class supports the following exported methods: 
 
*obj* **destroy**

 This method destroys the object, *obj*, that it is invoked upon, invoking any destructors on the object's class in the process. It is equivalent to using **[rename](rename.htm)** to delete the object command. The result of this method is always the empty string. 

 ### Non-exported methods

 The **oo::object** class supports the following non-exported methods: 
 
*obj* **eval** ?*arg ...*?
 This method concatenates the arguments, *arg*, as if with **[concat](concat.htm)**, and then evaluates the resulting script in the namespace that is uniquely associated with *obj*, returning the result of the evaluation. 


*obj* **unknown ?***methodName*? ?*arg ...*?
 This method is called when an attempt to invoke the method *methodName* on object *obj* fails. The arguments that the user supplied to the method are given as *arg* arguments. If *methodName* is absent, the object was invoked with no method name at all (or any other arguments). The default implementation (i.e., the one defined by the **oo::object** class) generates a suitable error, detailing what methods the object supports given whether the object was invoked by its public name or through the **[my](my.htm)** command. 


*obj* **variable** ?*varName ...*?
 This method arranges for each variable called *varName* to be linked from the object *obj*'s unique namespace into the caller's context. Thus, if it is invoked from inside a procedure then the namespace variable in the object is linked to the local variable in the procedure. Each *varName* argument must not have any namespace separators in it. The result is the empty string. 


*obj* **varname** *varName*

 This method returns the globally qualified name of the variable *varName* in the unique namespace for the object *obj*. 


*obj* **<cloned>** *sourceObjectName*

 This method is used by the **oo::object** command to copy the state of one object to another. It is responsible for copying the procedures and variables of the namespace of the source object (*sourceObjectName*) to the current object. It does not copy any other types of commands or any traces on the variables; that can be added if desired by overriding this method in a subclass. 

 Examples
--------

 This example demonstrates basic use of an object. 

```
set obj [**oo::object** new]
$obj foo             *→ error "unknown method foo"*
oo::objdefine $obj method foo {} {
    my **[variable](variable.htm)** count
    puts "bar[incr count]"
}
$obj foo             *→ prints "bar1"*
$obj foo             *→ prints "bar2"*
$obj variable count  *→ error "unknown method variable"*
$obj **[destroy](../tkcmd/destroy.htm)**
$obj foo             *→ error "unknown command obj"*
```
 See also
--------

 **[my](my.htm)**, **[oo::class](class.htm)** Copyright © 2007-2008 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/object.htm>

incr
====

 Name
----

 incr — Increment the value of a variable Synopsis
--------

 **incr** *varName* ?*increment*?  
 Description
-----------

 Increments the value stored in the variable whose name is *varName*. The value of the variable must be an integer. If *increment* is supplied then its value (which must be an integer) is added to the value of variable *varName*; otherwise 1 is added to *varName*. The new value is stored as a decimal string in variable *varName* and also returned as result.  Starting with the Tcl 8.5 release, the variable *varName* passed to **incr** may be unset, and in that case, it will be set to the value *increment* or to the default increment value of **1**. 


Examples
--------

 Add one to the contents of the variable *x*: 

```
**incr** x
```
  Add 42 to the contents of the variable *x*: 



```
**incr** x 42
```
  Add the contents of the variable *y* to the contents of the variable *x*: 



```
**incr** x $y
```
  Add nothing at all to the variable *x* (often useful for checking whether an argument to a procedure is actually integral and generating an error if it is not): 



```
**incr** x 0
```
 See also
--------

 **[expr](expr.htm)**, **[set](set.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/incr.htm>

concat
======

 Name
----

 concat — Join lists together Synopsis
--------

 **concat**?*arg arg ...*?  
 Description
-----------

 This command joins each of its arguments together with spaces after trimming leading and trailing white-space from each of them. If all of the arguments are lists, this has the same effect as concatenating them into a single list. It permits any number of arguments; if no *arg*s are supplied, the result is an empty string. Examples
--------

 Although **concat** will concatenate lists, flattening them in the process (so giving the following interactive session): 

```
*%* **concat** a b {c d e} {f {g h}}
*a b c d e f {g h}*
```
  it will also concatenate things that are not lists, as can be seen from this session: 



```
*%* **concat** " a b {c   " d "  e} f"
*a b {c d e} f*
```
  Note also that the concatenation does not remove spaces from the middle of values, as can be seen here: 



```
*%* **concat** "a   b   c" { d e f }
*a b c d e f*
```
  (i.e., there are three spaces between each of the **a**, the **b** and the **c**). 


See also
--------

 **[append](append.htm)**, **[eval](eval.htm)**, **[join](join.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/concat.htm>

define
======

  
[NAME](define.htm#M2) oo::define, oo::objdefine — define and configure classes and objects 
[SYNOPSIS](define.htm#M3) 
[DESCRIPTION](define.htm#M4) 
[CONFIGURING CLASSES](define.htm#M5)  
[**constructor** *argList bodyScript*](define.htm#M6) 
[**deletemethod** *name* ?*name ...*](define.htm#M7) 
[**destructor** *bodyScript*](define.htm#M8) 
[**export** *name* ?*name ...*?](define.htm#M9) 
[**filter** ?*-slotOperation*? ?*methodName ...*?](define.htm#M10) 
[**forward** *name cmdName* ?*arg ...*?](define.htm#M11) 
[**method** *name argList bodyScript*](define.htm#M12) 
[**mixin** ?*-slotOperation*? ?*className ...*?](define.htm#M13) 
[**renamemethod** *fromName toName*](define.htm#M14) 
[**self** *subcommand arg ...*](define.htm#M15) 
[**self** *script*](define.htm#M16) 
[**superclass** ?*-slotOperation*? ?*className ...*?](define.htm#M17) 
[**unexport** *name* ?*name ...*?](define.htm#M18) 
[**variable** ?*-slotOperation*? ?*name ...*?](define.htm#M19) 













 
[CONFIGURING OBJECTS](define.htm#M20)  
[**class** *className*](define.htm#M21) 
[**deletemethod** *name* ?*name ...*](define.htm#M22) 
[**export** *name* ?*name ...*?](define.htm#M23) 
[**filter** ?*-slotOperation*? ?*methodName ...*?](define.htm#M24) 
[**forward** *name cmdName* ?*arg ...*?](define.htm#M25) 
[**method** *name argList bodyScript*](define.htm#M26) 
[**mixin** ?*-slotOperation*? ?*className ...*?](define.htm#M27) 
[**renamemethod** *fromName toName*](define.htm#M28) 
[**unexport** *name* ?*name ...*?](define.htm#M29) 
[**variable** ?*-slotOperation*? ?*name ...*?](define.htm#M30) 









 
[SLOTTED DEFINITIONS](define.htm#M31)  
[*slot* **-append** ?*member ...*?](define.htm#M32) 
[*slot* **-clear**](define.htm#M33) 
[*slot* **-set** ?*member ...*?](define.htm#M34) 


 
[SLOT IMPLEMENTATION](define.htm#M35)  
[*slot* **Get**](define.htm#M36) 
[*slot* **Set** *elementList*](define.htm#M37) 

 
[EXAMPLES](define.htm#M38) 
[SEE ALSO](define.htm#M39) 
[KEYWORDS](define.htm#M40) 









 Name
----

 oo::define, oo::objdefine — define and configure classes and objects Synopsis
--------

 package require TclOO  
   
 **oo::define** *class defScript*  
 **oo::define** *class subcommand arg* ?*arg ...*?  
 **oo::objdefine** *object defScript*  
 **oo::objdefine** *object subcommand arg* ?*arg ...*?  
 Description
-----------

 The **oo::define** command is used to control the configuration of classes, and the **oo::objdefine** command is used to control the configuration of objects (including classes as instance objects), with the configuration being applied to the entity named in the *class* or the *object* argument. Configuring a class also updates the configuration of all subclasses of the class and all objects that are instances of that class or which mix it in (as modified by any per-instance configuration). The way in which the configuration is done is controlled by either the *defScript* argument or by the *subcommand* and following *arg* arguments; when the second is present, it is exactly as if all the arguments from *subcommand* onwards are made into a list and that list is used as the *defScript* argument. ### Configuring classes

 The following commands are supported in the *defScript* for **oo::define**, each of which may also be used in the *subcommand* form: 
 
**constructor** *argList bodyScript*

 This creates or updates the constructor for a class. The formal arguments to the constructor (defined using the same format as for the Tcl **[proc](proc.htm)** command) will be *argList*, and the body of the constructor will be *bodyScript*. When the body of the constructor is evaluated, the current namespace of the constructor will be a namespace that is unique to the object being constructed. Within the constructor, the **[next](next.htm)** command should be used to call the superclasses' constructors. If *bodyScript* is the empty string, the constructor will be deleted. 


**deletemethod** *name* ?*name ...*

 This deletes each of the methods called *name* from a class. The methods must have previously existed in that class. Does not affect the superclasses of the class, nor does it affect the subclasses or instances of the class (except when they have a call chain through the class being modified). 


**destructor** *bodyScript*

 This creates or updates the destructor for a class. Destructors take no arguments, and the body of the destructor will be *bodyScript*. The destructor is called when objects of the class are deleted, and when called will have the object's unique namespace as the current namespace. Destructors should use the **[next](next.htm)** command to call the superclasses' destructors. Note that destructors are not called in all situations (e.g. if the interpreter is destroyed). If *bodyScript* is the empty string, the destructor will be deleted.  Note that errors during the evaluation of a destructor *are not returned* to the code that causes the destruction of an object. Instead, they are passed to the currently-defined **[bgerror](bgerror.htm)** handler. 


**export** *name* ?*name ...*?
 This arranges for each of the named methods, *name*, to be exported (i.e. usable outside an instance through the instance object's command) by the class being defined. Note that the methods themselves may be actually defined by a superclass; subclass exports override superclass visibility, and may in turn be overridden by instances. 


**filter** ?*-slotOperation*? ?*methodName ...*?
 This slot (see **[SLOTTED DEFINITIONS](#M31)** below) sets or updates the list of method names that are used to guard whether method call to instances of the class may be called and what the method's results are. Each *methodName* names a single filtering method (which may be exposed or not exposed); it is not an error for a non-existent method to be named since they may be defined by subclasses. By default, this slot works by appending. 


**forward** *name cmdName* ?*arg ...*?
 This creates or updates a forwarded method called *name*. The method is defined be forwarded to the command called *cmdName*, with additional arguments, *arg* etc., added before those arguments specified by the caller of the method. The *cmdName* will always be resolved using the rules of the invoking objects' namespaces, i.e., when *cmdName* is not fully-qualified, the command will be searched for in each object's namespace, using the instances' namespace's path, or by looking in the global namespace. The method will be exported if *name* starts with a lower-case letter, and non-exported otherwise. 


**method** *name argList bodyScript*

 This creates or updates a method that is implemented as a procedure-like script. The name of the method is *name*, the formal arguments to the method (defined using the same format as for the Tcl **[proc](proc.htm)** command) will be *argList*, and the body of the method will be *bodyScript*. When the body of the method is evaluated, the current namespace of the method will be a namespace that is unique to the current object. The method will be exported if *name* starts with a lower-case letter, and non-exported otherwise; this behavior can be overridden via **export** and **unexport**. 


**mixin** ?*-slotOperation*? ?*className ...*?
 This slot (see **[SLOTTED DEFINITIONS](#M31)** below) sets or updates the list of additional classes that are to be mixed into all the instances of the class being defined. Each *className* argument names a single class that is to be mixed in. By default, this slot works by replacement. 


**renamemethod** *fromName toName*

 This renames the method called *fromName* in a class to *toName*. The method must have previously existed in the class, and *toName* must not previously refer to a method in that class. Does not affect the superclasses of the class, nor does it affect the subclasses or instances of the class (except when they have a call chain through the class being modified). Does not change the export status of the method; if it was exported before, it will be afterwards. 


**self** *subcommand arg ...*


**self** *script*

 This command is equivalent to calling **oo::objdefine** on the class being defined (see **[CONFIGURING OBJECTS](#M20)** below for a description of the supported values of *subcommand*). It follows the same general pattern of argument handling as the **oo::define** and **oo::objdefine** commands, and “**oo::define** *cls* **[self](self.htm)** *subcommand ...*” operates identically to “**oo::objdefine** *cls subcommand ...*”. 


**superclass** ?*-slotOperation*? ?*className ...*?
 This slot (see **[SLOTTED DEFINITIONS](#M31)** below) allows the alteration of the superclasses of the class being defined. Each *className* argument names one class that is to be a superclass of the defined class. Note that objects must not be changed from being classes to being non-classes or vice-versa, that an empty parent class is equivalent to **[oo::object](object.htm)**, and that the parent classes of **[oo::object](object.htm)** and **[oo::class](class.htm)** may not be modified. By default, this slot works by replacement. 


**unexport** *name* ?*name ...*?
 This arranges for each of the named methods, *name*, to be not exported (i.e. not usable outside the instance through the instance object's command, but instead just through the **[my](my.htm)** command visible in each object's context) by the class being defined. Note that the methods themselves may be actually defined by a superclass; subclass unexports override superclass visibility, and may be overridden by instance unexports. 


**variable** ?*-slotOperation*? ?*name ...*?
 This slot (see **[SLOTTED DEFINITIONS](#M31)** below) arranges for each of the named variables to be automatically made available in the methods, constructor and destructor declared by the class being defined. Each variable name must not have any namespace separators and must not look like an array access. All variables will be actually present in the instance object on which the method is executed. Note that the variable lists declared by a superclass or subclass are completely disjoint, as are variable lists declared by instances; the list of variable names is just for methods (and constructors and destructors) declared by this class. By default, this slot works by appending. 

 ### Configuring objects

 The following commands are supported in the *defScript* for **oo::objdefine**, each of which may also be used in the *subcommand* form: 
 
**class** *className*

 This allows the class of an object to be changed after creation. Note that the class's constructors are not called when this is done, and so the object may well be in an inconsistent state unless additional configuration work is done. 


**deletemethod** *name* ?*name ...*

 This deletes each of the methods called *name* from an object. The methods must have previously existed in that object. Does not affect the classes that the object is an instance of. 


**export** *name* ?*name ...*?
 This arranges for each of the named methods, *name*, to be exported (i.e. usable outside the object through the object's command) by the object being defined. Note that the methods themselves may be actually defined by a class or superclass; object exports override class visibility. 


**filter** ?*-slotOperation*? ?*methodName ...*?
 This slot (see **[SLOTTED DEFINITIONS](#M31)** below) sets or updates the list of method names that are used to guard whether a method call to the object may be called and what the method's results are. Each *methodName* names a single filtering method (which may be exposed or not exposed); it is not an error for a non-existent method to be named. Note that the actual list of filters also depends on the filters set upon any classes that the object is an instance of. By default, this slot works by appending. 


**forward** *name cmdName* ?*arg ...*?
 This creates or updates a forwarded object method called *name*. The method is defined be forwarded to the command called *cmdName*, with additional arguments, *arg* etc., added before those arguments specified by the caller of the method. Forwarded methods should be deleted using the **method** subcommand. The method will be exported if *name* starts with a lower-case letter, and non-exported otherwise. 


**method** *name argList bodyScript*

 This creates, updates or deletes an object method. The name of the method is *name*, the formal arguments to the method (defined using the same format as for the Tcl **[proc](proc.htm)** command) will be *argList*, and the body of the method will be *bodyScript*. When the body of the method is evaluated, the current namespace of the method will be a namespace that is unique to the object. The method will be exported if *name* starts with a lower-case letter, and non-exported otherwise. 


**mixin** ?*-slotOperation*? ?*className ...*?
 This slot (see **[SLOTTED DEFINITIONS](#M31)** below) sets or updates a per-object list of additional classes that are to be mixed into the object. Each argument, *className*, names a single class that is to be mixed in. By default, this slot works by replacement. 


**renamemethod** *fromName toName*

 This renames the method called *fromName* in an object to *toName*. The method must have previously existed in the object, and *toName* must not previously refer to a method in that object. Does not affect the classes that the object is an instance of. Does not change the export status of the method; if it was exported before, it will be afterwards. 


**unexport** *name* ?*name ...*?
 This arranges for each of the named methods, *name*, to be not exported (i.e. not usable outside the object through the object's command, but instead just through the **[my](my.htm)** command visible in the object's context) by the object being defined. Note that the methods themselves may be actually defined by a class; instance unexports override class visibility. 


**variable** ?*-slotOperation*? ?*name ...*?
 This slot (see **[SLOTTED DEFINITIONS](#M31)** below) arranges for each of the named variables to be automatically made available in the methods declared by the object being defined. Each variable name must not have any namespace separators and must not look like an array access. All variables will be actually present in the object on which the method is executed. Note that the variable lists declared by the classes and mixins of which the object is an instance are completely disjoint; the list of variable names is just for methods declared by this object. By default, this slot works by appending. 

 Slotted definitions
-------------------

 Some of the configurable definitions of a class or object are *slotted definitions*. This means that the configuration is implemented by a slot object, that is an instance of the class **oo::Slot**, which manages a list of values (class names, variable names, etc.) that comprises the contents of the slot. The class defines three operations (as methods) that may be done on the slot: 
 
*slot* **-append** ?*member ...*?
 This appends the given *member* elements to the slot definition. 


*slot* **-clear**

 This sets the slot definition to the empty list. 


*slot* **-set** ?*member ...*?
 This replaces the slot definition with the given *member* elements. 

  A consequence of this is that any use of a slot's default operation where the first member argument begins with a hyphen will be an error. One of the above operations should be used explicitly in those circumstances. 


### Slot implementation

 Internally, slot objects also define a method **--default-operation** which is forwarded to the default operation of the slot (thus, for the class “**[variable](variable.htm)**” slot, this is forwarded to “**my -append**”), and these methods which provide the implementation interface: 
 
*slot* **Get**

 Returns a list that is the current contents of the slot. This method must always be called from a stack frame created by a call to **oo::define** or **oo::objdefine**. 


*slot* **Set** *elementList*

 Sets the contents of the slot to the list *elementList* and returns the empty string. This method must always be called from a stack frame created by a call to **oo::define** or **oo::objdefine**. 

  The implementation of these methods is slot-dependent (and responsible for accessing the correct part of the class or object definition). Slots also have an unknown method handler to tie all these pieces together, and they hide their **[destroy](../tkcmd/destroy.htm)** method so that it is not invoked inadvertently. It is *recommended* that any user changes to the slot mechanism be restricted to defining new operations whose names start with a hyphen. 


Examples
--------

 This example demonstrates how to use both forms of the **oo::define** and **oo::objdefine** commands (they work in the same way), as well as illustrating four of the subcommands of them. 

```
oo::class create c
c create o
**oo::define** c **method** foo {} {
    puts "world"
}
**oo::objdefine** o {
    **method** bar {} {
        my Foo "hello "
        my foo
    }
    **forward** Foo ::puts -nonewline
    **unexport** foo
}
o bar                *→ prints "hello world"*
o foo                *→ error "unknown method foo"*
o Foo Bar            *→ error "unknown method Foo"*
**oo::objdefine** o **renamemethod** bar lollipop
o lollipop           *→ prints "hello world"*
```
  This example shows how additional classes can be mixed into an object. It also shows how **mixin** is a slot that supports appending: 



```
oo::object create inst
inst m1              *→ error "unknown method m1"*
inst m2              *→ error "unknown method m2"*

oo::class create A {
    **method** m1 {} {
        puts "red brick"
    }
}
**oo::objdefine** inst {
    **mixin** A
}
inst m1              *→ prints "red brick"*
inst m2              *→ error "unknown method m2"*

oo::class create B {
    **method** m2 {} {
        puts "blue brick"
    }
}
**oo::objdefine** inst {
    **mixin -append** B
}
inst m1              *→ prints "red brick"*
inst m2              *→ prints "blue brick"*
```
 See also
--------

 **[next](next.htm)**, **[oo::class](class.htm)**, **[oo::object](object.htm)** Copyright © 2007 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/define.htm>

close
=====

 Name
----

 close — Close an open channel Synopsis
--------

 **close** *channelId* ?r(ead)|w(rite)?  
 Description
-----------

 Closes or half-closes the channel given by *channelId*.  *ChannelId* must be an identifier for an open channel such as a Tcl standard channel (**[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, or **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**), the return value from an invocation of **[open](open.htm)** or **[socket](socket.htm)**, or the result of a channel creation command provided by a Tcl extension. 


 The single-argument form is a simple “full-close”: all buffered output is flushed to the channel's output device, any buffered input is discarded, the underlying file or device is closed, and *channelId* becomes unavailable for use. 


 If the channel is blocking, the command does not return until all output is flushed. If the channel is nonblocking and there is unflushed output, the channel remains open and the command returns immediately; output will be flushed in the background and the channel will be closed when all the flushing is complete. 


 If *channelId* is a blocking channel for a command pipeline then **close** waits for the child processes to complete. 


 If the channel is shared between interpreters, then **close** makes *channelId* unavailable in the invoking interpreter but has no other effect until all of the sharing interpreters have closed the channel. When the last interpreter in which the channel is registered invokes **close**, the cleanup actions described above occur. See the **[interp](interp.htm)** command for a description of channel sharing. 


 Channels are automatically closed when an interpreter is destroyed and when the process exits. From 8.6 on (TIP#398), nonblocking channels are no longer switched to blocking mode when exiting; this guarantees a timely exit even when the peer or a communication channel is stalled. To ensure proper flushing of stalled nonblocking channels on exit, one must now either (a) actively switch them back to blocking or (b) use the environment variable TCL\_FLUSH\_NONBLOCKING\_ON\_EXIT, which when set and not equal to "0" restores the previous behavior. 


 The command returns an empty string, and may generate an error if an error occurs while flushing output. If a command in a command pipeline created with **[open](open.htm)** returns an error, **close** generates an error (similar to the **[exec](exec.htm)** command.) 


 The two-argument form is a “half-close”: given a bidirectional channel like a socket or command pipeline and a (possibly abbreviated) direction, it closes only the sub-stream going in that direction. This means a shutdown() on a socket, and a close() of one end of a pipe for a command pipeline. Then, the Tcl-level channel data structure is either kept or freed depending on whether the other direction is still open. 


 A single-argument close on an already half-closed bidirectional channel is defined to just “finish the job”. A half-close on an already closed half, or on a wrong-sided unidirectional channel, raises an error. 


 In the case of a command pipeline, the child-reaping duty falls upon the shoulders of the last close or half-close, which is thus allowed to report an abnormal exit error. 


 Currently only sockets and command pipelines support half-close. A future extension will allow reflected and stacked channels to do so. 


Example
-------

 This illustrates how you can use Tcl to ensure that files get closed even when errors happen by combining **[catch](catch.htm)**, **close** and **[return](return.htm)**: 

```
proc withOpenFile {filename channelVar script} {
    upvar 1 $channelVar chan
    set chan [open $filename]
    catch {
        uplevel 1 $script
    } result options
    **close** $chan
    return -options $options $result
}
```
 See also
--------

 **[file](file.htm)**, **[open](open.htm)**, **[socket](socket.htm)**, **[eof](eof.htm)**, **[Tcl\_StandardChannels](https://www.tcl.tk/man/tcl/TclLib/StdChannels.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/close.htm>

tcltest
=======

  
[NAME](tcltest.htm#M2) tcltest — Test harness support code and utilities 
[SYNOPSIS](tcltest.htm#M3) 
[DESCRIPTION](tcltest.htm#M4) 
[COMMANDS](tcltest.htm#M5)  
[**test** *name description* ?*-option value ...*?](tcltest.htm#M6) 
[**test** *name description* ?*constraints*? *body result*](tcltest.htm#M7) 
[**loadTestedCommands**](tcltest.htm#M8) 
[**makeFile** *contents name* ?*directory*?](tcltest.htm#M9) 
[**removeFile** *name* ?*directory*?](tcltest.htm#M10) 
[**makeDirectory** *name* ?*directory*?](tcltest.htm#M11) 
[**removeDirectory** *name* ?*directory*?](tcltest.htm#M12) 
[**viewFile** *file* ?*directory*?](tcltest.htm#M13) 
[**cleanupTests**](tcltest.htm#M14) 
[**runAllTests**](tcltest.htm#M15) 









 
[CONFIGURATION COMMANDS](tcltest.htm#M16)  
[**configure**](tcltest.htm#M17) 
[**configure** *option*](tcltest.htm#M18) 
[**configure** *option value* ?*-option value ...*?](tcltest.htm#M19) 
[**customMatch** *mode script*](tcltest.htm#M20) 
[**testConstraint** *constraint* ?*boolean*?](tcltest.htm#M21) 
[**interpreter** ?*executableName*?](tcltest.htm#M22) 
[**outputChannel** ?*channelID*?](tcltest.htm#M23) 
[**errorChannel** ?*channelID*?](tcltest.htm#M24) 







 
[SHORTCUT CONFIGURATION COMMANDS](tcltest.htm#M25)  
[**debug** ?*level*?](tcltest.htm#M26) 
[**errorFile** ?*filename*?](tcltest.htm#M27) 
[**limitConstraints** ?*boolean*?](tcltest.htm#M28) 
[**loadFile** ?*filename*?](tcltest.htm#M29) 
[**loadScript** ?*script*?](tcltest.htm#M30) 
[**match** ?*patternList*?](tcltest.htm#M31) 
[**matchDirectories** ?*patternList*?](tcltest.htm#M32) 
[**matchFiles** ?*patternList*?](tcltest.htm#M33) 
[**outputFile** ?*filename*?](tcltest.htm#M34) 
[**preserveCore** ?*level*?](tcltest.htm#M35) 
[**singleProcess** ?*boolean*?](tcltest.htm#M36) 
[**skip** ?*patternList*?](tcltest.htm#M37) 
[**skipDirectories** ?*patternList*?](tcltest.htm#M38) 
[**skipFiles** ?*patternList*?](tcltest.htm#M39) 
[**temporaryDirectory** ?*directory*?](tcltest.htm#M40) 
[**testsDirectory** ?*directory*?](tcltest.htm#M41) 
[**verbose** ?*level*?](tcltest.htm#M42) 
















 
[OTHER COMMANDS](tcltest.htm#M43)  
[**test** *name description optionList*](tcltest.htm#M44) 
[**workingDirectory** ?*directoryName*?](tcltest.htm#M45) 
[**normalizeMsg** *msg*](tcltest.htm#M46) 
[**normalizePath** *pathVar*](tcltest.htm#M47) 
[**bytestring** *string*](tcltest.htm#M48) 




 
[TESTS](tcltest.htm#M49)  
[**-constraints** *keywordList*|*expression*](tcltest.htm#M50) 
[**-setup** *script*](tcltest.htm#M51) 
[**-body** *script*](tcltest.htm#M52) 
[**-cleanup** *script*](tcltest.htm#M53) 
[**-match** *mode*](tcltest.htm#M54) 
[**-result** *expectedValue*](tcltest.htm#M55) 
[**-output** *expectedValue*](tcltest.htm#M56) 
[**-errorOutput** *expectedValue*](tcltest.htm#M57) 
[**-returnCodes** *expectedCodeList*](tcltest.htm#M58) 








 
[TEST CONSTRAINTS](tcltest.htm#M59)  
[*singleTestInterp*](tcltest.htm#M60) 
[*unix*](tcltest.htm#M61) 
[*win*](tcltest.htm#M62) 
[*nt*](tcltest.htm#M63) 
[*mac*](tcltest.htm#M64) 
[*unixOrWin*](tcltest.htm#M65) 
[*macOrWin*](tcltest.htm#M66) 
[*macOrUnix*](tcltest.htm#M67) 
[*tempNotWin*](tcltest.htm#M68) 
[*tempNotMac*](tcltest.htm#M69) 
[*unixCrash*](tcltest.htm#M70) 
[*winCrash*](tcltest.htm#M71) 
[*macCrash*](tcltest.htm#M72) 
[*emptyTest*](tcltest.htm#M73) 
[*knownBug*](tcltest.htm#M74) 
[*nonPortable*](tcltest.htm#M75) 
[*userInteraction*](tcltest.htm#M76) 
[*interactive*](tcltest.htm#M77) 
[*nonBlockFiles*](tcltest.htm#M78) 
[*asyncPipeClose*](tcltest.htm#M79) 
[*unixExecs*](tcltest.htm#M80) 
[*hasIsoLocale*](tcltest.htm#M81) 
[*root*](tcltest.htm#M82) 
[*notRoot*](tcltest.htm#M83) 
[*eformat*](tcltest.htm#M84) 
[*stdio*](tcltest.htm#M85) 

























 
[RUNNING ALL TESTS](tcltest.htm#M86) 
[CONFIGURABLE OPTIONS](tcltest.htm#M87)  
[**-singleproc** *boolean*](tcltest.htm#M88) 
[**-debug** *level*](tcltest.htm#M89)  
[0](tcltest.htm#M90) 
[1](tcltest.htm#M91) 
[2](tcltest.htm#M92) 
[3](tcltest.htm#M93) 



 
[**-verbose** *level*](tcltest.htm#M94)  
[body (**b**)](tcltest.htm#M95) 
[pass (**p**)](tcltest.htm#M96) 
[skip (**s**)](tcltest.htm#M97) 
[start (**t**)](tcltest.htm#M98) 
[error (**e**)](tcltest.htm#M99) 
[line (**l**)](tcltest.htm#M100) 
[msec (**m**)](tcltest.htm#M101) 
[usec (**u**)](tcltest.htm#M102) 







 
[**-preservecore** *level*](tcltest.htm#M103)  
[0](tcltest.htm#M104) 
[1](tcltest.htm#M105) 
[2](tcltest.htm#M106) 


 
[**-limitconstraints** *boolean*](tcltest.htm#M107) 
[**-constraints** *list*](tcltest.htm#M108) 
[**-tmpdir** *directory*](tcltest.htm#M109) 
[**-testdir** *directory*](tcltest.htm#M110) 
[**-file** *patternList*](tcltest.htm#M111) 
[**-notfile** *patternList*](tcltest.htm#M112) 
[**-relateddir** *patternList*](tcltest.htm#M113) 
[**-asidefromdir** *patternList*](tcltest.htm#M114) 
[**-match** *patternList*](tcltest.htm#M115) 
[**-skip** *patternList*](tcltest.htm#M116) 
[**-load** *script*](tcltest.htm#M117) 
[**-loadfile** *filename*](tcltest.htm#M118) 
[**-outfile** *filename*](tcltest.htm#M119) 
[**-errfile** *filename*](tcltest.htm#M120) 

















 
[CREATING TEST SUITES WITH TCLTEST](tcltest.htm#M121) 
[COMPATIBILITY](tcltest.htm#M122) 
[KNOWN ISSUES](tcltest.htm#M123) 
[KEYWORDS](tcltest.htm#M124) 














 Name
----

 tcltest — Test harness support code and utilities Synopsis
--------

 **package require tcltest** ?**2.3**?  
   
 **tcltest::test** *name description* ?*-option value ...*?  
 **tcltest::test** *name description* ?*constraints*? *body result*  
   
 **tcltest::loadTestedCommands**  
 **tcltest::makeDirectory** *name* ?*directory*?  
 **tcltest::removeDirectory** *name* ?*directory*?  
 **tcltest::makeFile** *contents name* ?*directory*?  
 **tcltest::removeFile** *name* ?*directory*?  
 **tcltest::viewFile** *name* ?*directory*?  
 **tcltest::cleanupTests** ?*runningMultipleTests*?  
 **tcltest::runAllTests**  
   
 **tcltest::configure**  
 **tcltest::configure** *-option*  
 **tcltest::configure** *-option value* ?*-option value ...*?  
 **tcltest::customMatch** *mode command*  
 **tcltest::testConstraint** *constraint* ?*value*?  
 **tcltest::outputChannel** ?*channelID*?  
 **tcltest::errorChannel** ?*channelID*?  
 **tcltest::interpreter** ?*interp*?  
   
 **tcltest::debug** ?*level*?  
 **tcltest::errorFile** ?*filename*?  
 **tcltest::limitConstraints** ?*boolean*?  
 **tcltest::loadFile** ?*filename*?  
 **tcltest::loadScript** ?*script*?  
 **tcltest::match** ?*patternList*?  
 **tcltest::matchDirectories** ?*patternList*?  
 **tcltest::matchFiles** ?*patternList*?  
 **tcltest::outputFile** ?*filename*?  
 **tcltest::preserveCore** ?*level*?  
 **tcltest::singleProcess** ?*boolean*?  
 **tcltest::skip** ?*patternList*?  
 **tcltest::skipDirectories** ?*patternList*?  
 **tcltest::skipFiles** ?*patternList*?  
 **tcltest::temporaryDirectory** ?*directory*?  
 **tcltest::testsDirectory** ?*directory*?  
 **tcltest::verbose** ?*level*?  
   
 **tcltest::test** *name description optionList*  
 **tcltest::bytestring** *string*  
 **tcltest::normalizeMsg** *msg*  
 **tcltest::normalizePath** *pathVar*  
 **tcltest::workingDirectory** ?*dir*?  
 Description
-----------

 The **tcltest** package provides several utility commands useful in the construction of test suites for code instrumented to be run by evaluation of Tcl commands. Notably the built-in commands of the Tcl library itself are tested by a test suite using the tcltest package.  All the commands provided by the **tcltest** package are defined in and exported from the **::tcltest** namespace, as indicated in the **[SYNOPSIS](#M3)** above. In the following sections, all commands will be described by their simple names, in the interest of brevity. 


 The central command of **tcltest** is **test** that defines and runs a test. Testing with **test** involves evaluation of a Tcl script and comparing the result to an expected result, as configured and controlled by a number of options. Several other commands provided by **tcltest** govern the configuration of **test** and the collection of many **test** commands into test suites. 


 See **[CREATING TEST SUITES WITH TCLTEST](#M121)** below for an extended example of how to use the commands of **tcltest** to produce test suites for your Tcl-enabled code. 


Commands
--------

  
**test** *name description* ?*-option value ...*?
 Defines and possibly runs a test with the name *name* and description *description*. The name and description of a test are used in messages reported by **test** during the test, as configured by the options of **tcltest**. The remaining *option value* arguments to **test** define the test, including the scripts to run, the conditions under which to run them, the expected result, and the means by which the expected and actual results should be compared. See **[TESTS](#M49)** below for a complete description of the valid options and how they define a test. The **test** command returns an empty string. 


**test** *name description* ?*constraints*? *body result*

 This form of **test** is provided to support test suites written for version 1 of the **tcltest** package, and also a simpler interface for a common usage. It is the same as “**test** *name description* **-constraints** *constraints* **-body** *body* **-result** *result*”. All other options to **test** take their default values. When *constraints* is omitted, this form of **test** can be distinguished from the first because all *option*s begin with “-”. 

**loadTestedCommands**
 Evaluates in the caller's context the script specified by **configure -load** or **configure -loadfile**. Returns the result of that script evaluation, including any error raised by the script. Use this command and the related configuration options to provide the commands to be tested to the interpreter running the test suite. 


**makeFile** *contents name* ?*directory*?
 Creates a file named *name* relative to directory *directory* and write *contents* to that file using the encoding **[encoding system](encoding.htm)**. If *contents* does not end with a newline, a newline will be appended so that the file named *name* does end with a newline. Because the system encoding is used, this command is only suitable for making text files. The file will be removed by the next evaluation of **cleanupTests**, unless it is removed by **removeFile** first. The default value of *directory* is the directory **configure -tmpdir**. Returns the full path of the file created. Use this command to create any text file required by a test with contents as needed. 


**removeFile** *name* ?*directory*?
 Forces the file referenced by *name* to be removed. This file name should be relative to *directory*. The default value of *directory* is the directory **configure -tmpdir**. Returns an empty string. Use this command to delete files created by **makeFile**. 


**makeDirectory** *name* ?*directory*?
 Creates a directory named *name* relative to directory *directory*. The directory will be removed by the next evaluation of **cleanupTests**, unless it is removed by **removeDirectory** first. The default value of *directory* is the directory **configure -tmpdir**. Returns the full path of the directory created. Use this command to create any directories that are required to exist by a test. 


**removeDirectory** *name* ?*directory*?
 Forces the directory referenced by *name* to be removed. This directory should be relative to *directory*. The default value of *directory* is the directory **configure -tmpdir**. Returns an empty string. Use this command to delete any directories created by **makeDirectory**. 


**viewFile** *file* ?*directory*?
 Returns the contents of *file*, except for any final newline, just as **read -nonewline** would return. This file name should be relative to *directory*. The default value of *directory* is the directory **configure -tmpdir**. Use this command as a convenient way to turn the contents of a file generated by a test into the result of that test for matching against an expected result. The contents of the file are read using the system encoding, so its usefulness is limited to text files. 

**cleanupTests**
 Intended to clean up and summarize after several tests have been run. Typically called once per test file, at the end of the file after all tests have been completed. For best effectiveness, be sure that the **cleanupTests** is evaluated even if an error occurs earlier in the test file evaluation.  Prints statistics about the tests run and removes files that were created by **makeDirectory** and **makeFile** since the last **cleanupTests**. Names of files and directories in the directory **configure -tmpdir** created since the last **cleanupTests**, but not created by **makeFile** or **makeDirectory** are printed to **outputChannel**. This command also restores the original shell environment, as described by the global **[env](tclvars.htm)** array. Returns an empty string. 



**runAllTests**
 This is a master command meant to run an entire suite of tests, spanning multiple files and/or directories, as governed by the configurable options of **tcltest**. See **[RUNNING ALL TESTS](#M86)** below for a complete description of the many variations possible with **runAllTests**. 

 ### Configuration commands

  **configure**
 Returns the list of configurable options supported by **tcltest**. See **[CONFIGURABLE OPTIONS](#M87)** below for the full list of options, their valid values, and their effect on **tcltest** operations. 


**configure** *option*

 Returns the current value of the supported configurable option *option*. Raises an error if *option* is not a supported configurable option. 


**configure** *option value* ?*-option value ...*?
 Sets the value of each configurable option *option* to the corresponding value *value*, in order. Raises an error if an *option* is not a supported configurable option, or if *value* is not a valid value for the corresponding *option*, or if a *value* is not provided. When an error is raised, the operation of **configure** is halted, and subsequent *option value* arguments are not processed.  If the environment variable **::env(TCLTEST\_OPTIONS)** exists when the **tcltest** package is loaded (by **[package require](package.htm)** **tcltest**) then its value is taken as a list of arguments to pass to **configure**. This allows the default values of the configuration options to be set by the environment. 




**customMatch** *mode script*

 Registers *mode* as a new legal value of the **-match** option to **test**. When the **-match** *mode* option is passed to **test**, the script *script* will be evaluated to compare the actual result of evaluating the body of the test to the expected result. To perform the match, the *script* is completed with two additional words, the expected result, and the actual result, and the completed script is evaluated in the global namespace. The completed script is expected to return a boolean value indicating whether or not the results match. The built-in matching modes of **test** are **exact**, **[glob](glob.htm)**, and **[regexp](regexp.htm)**. 


**testConstraint** *constraint* ?*boolean*?
 Sets or returns the boolean value associated with the named *constraint*. See **[TEST CONSTRAINTS](#M59)** below for more information. 


**interpreter** ?*executableName*?
 Sets or returns the name of the executable to be **[exec](exec.htm)**ed by **runAllTests** to run each test file when **configure -singleproc** is false. The default value for **interpreter** is the name of the currently running program as returned by **[info nameofexecutable](info.htm)**. 


**outputChannel** ?*channelID*?
 Sets or returns the output channel ID. This defaults to **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**. Any test that prints test related output should send that output to **outputChannel** rather than letting that output default to **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**. 


**errorChannel** ?*channelID*?
 Sets or returns the error channel ID. This defaults to **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**. Any test that prints error messages should send that output to **errorChannel** rather than printing directly to **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**. 

 ### Shortcut configuration commands

  
**debug** ?*level*?
 Same as “**configure -debug** ?*level*?”. 


**errorFile** ?*filename*?
 Same as “**configure -errfile** ?*filename*?”. 


**limitConstraints** ?*boolean*?
 Same as “**configure -limitconstraints** ?*boolean*?”. 


**loadFile** ?*filename*?
 Same as “**configure -loadfile** ?*filename*?”. 


**loadScript** ?*script*?
 Same as “**configure -load** ?*script*?”. 


**match** ?*patternList*?
 Same as “**configure -match** ?*patternList*?”. 


**matchDirectories** ?*patternList*?
 Same as “**configure -relateddir** ?*patternList*?”. 


**matchFiles** ?*patternList*?
 Same as “**configure -file** ?*patternList*?”. 


**outputFile** ?*filename*?
 Same as “**configure -outfile** ?*filename*?”. 


**preserveCore** ?*level*?
 Same as “**configure -preservecore** ?*level*?”. 


**singleProcess** ?*boolean*?
 Same as “**configure -singleproc** ?*boolean*?”. 


**skip** ?*patternList*?
 Same as “**configure -skip** ?*patternList*?”. 


**skipDirectories** ?*patternList*?
 Same as “**configure -asidefromdir** ?*patternList*?”. 


**skipFiles** ?*patternList*?
 Same as “**configure -notfile** ?*patternList*?”. 


**temporaryDirectory** ?*directory*?
 Same as “**configure -tmpdir** ?*directory*?”. 


**testsDirectory** ?*directory*?
 Same as “**configure -testdir** ?*directory*?”. 


**verbose** ?*level*?
 Same as “**configure -verbose** ?*level*?”. 

 ### Other commands

 The remaining commands provided by **tcltest** have better alternatives provided by **tcltest** or **[Tcl](tcl.htm)** itself. They are retained to support existing test suites, but should be avoided in new code. 
 
**test** *name description optionList*

 This form of **test** was provided to enable passing many options spanning several lines to **test** as a single argument quoted by braces, rather than needing to backslash quote the newlines between arguments to **test**. The *optionList* argument is expected to be a list with an even number of elements representing *option* and *value* arguments to pass to **test**. However, these values are not passed directly, as in the alternate forms of **[switch](switch.htm)**. Instead, this form makes an unfortunate attempt to overthrow Tcl's substitution rules by performing substitutions on some of the list elements as an attempt to implement a “do what I mean” interpretation of a brace-enclosed “block”. The result is nearly impossible to document clearly, and for that reason this form is not recommended. See the examples in **[CREATING TEST SUITES WITH TCLTEST](#M121)** below to see that this form is really not necessary to avoid backslash-quoted newlines. If you insist on using this form, examine the source code of **tcltest** if you want to know the substitution details, or just enclose the third through last argument to **test** in braces and hope for the best. 


**workingDirectory** ?*directoryName*?
 Sets or returns the current working directory when the test suite is running. The default value for workingDirectory is the directory in which the test suite was launched. The Tcl commands **[cd](cd.htm)** and **[pwd](pwd.htm)** are sufficient replacements. 


**normalizeMsg** *msg*

 Returns the result of removing the “extra” newlines from *msg*, where “extra” is rather imprecise. Tcl offers plenty of string processing commands to modify strings as you wish, and **customMatch** allows flexible matching of actual and expected results. 


**normalizePath** *pathVar*

 Resolves symlinks in a path, thus creating a path without internal redirection. It is assumed that *pathVar* is absolute. *pathVar* is modified in place. The Tcl command **[file normalize](file.htm)** is a sufficient replacement. 


**bytestring** *string*

 Construct a string that consists of the requested sequence of bytes, as opposed to a string of properly formed UTF-8 characters using the value supplied in *string*. This allows the tester to create denormalized or improperly formed strings to pass to C procedures that are supposed to accept strings with embedded NULL types and confirm that a string result has a certain pattern of bytes. This is exactly equivalent to the Tcl command **[encoding convertfrom](encoding.htm)** **identity**. 

 Tests
-----

 The **test** command is the heart of the **tcltest** package. Its essential function is to evaluate a Tcl script and compare the result with an expected result. The options of **test** define the test script, the environment in which to evaluate it, the expected result, and how the compare the actual result to the expected result. Some configuration options of **tcltest** also influence how **test** operates.  The valid options for **test** are summarized: 



```
**test** *name* *description*
        ?**-constraints** *keywordList|expression*?
        ?**-setup** *setupScript*?
        ?**-body** *testScript*?
        ?**-cleanup** *cleanupScript*?
        ?**-result** *expectedAnswer*?
        ?**-output** *expectedOutput*?
        ?**-errorOutput** *expectedError*?
        ?**-returnCodes** *codeList*?
        ?**-match** *mode*?
```
  The *name* may be any string. It is conventional to choose a *name* according to the pattern: 



```
*target*-*majorNum*.*minorNum*
```
  For white-box (regression) tests, the target should be the name of the C function or Tcl procedure being tested. For black-box tests, the target should be the name of the feature being tested. Some conventions call for the names of black-box tests to have the suffix **\_bb**. Related tests should share a major number. As a test suite evolves, it is best to have the same test name continue to correspond to the same test, so that it remains meaningful to say things like “Test foo-1.3 passed in all releases up to 3.4, but began failing in release 3.5.” 


 During evaluation of **test**, the *name* will be compared to the lists of string matching patterns returned by **configure -match**, and **configure -skip**. The test will be run only if *name* matches any of the patterns from **configure -match** and matches none of the patterns from **configure -skip**. 


 The *description* should be a short textual description of the test. The *description* is included in output produced by the test, typically test failure messages. Good *description* values should briefly explain the purpose of the test to users of a test suite. The name of a Tcl or C function being tested should be included in the description for regression tests. If the test case exists to reproduce a bug, include the bug ID in the description. 


 Valid attributes and associated values are: 


 
**-constraints** *keywordList*|*expression*

 The optional **-constraints** attribute can be list of one or more keywords or an expression. If the **-constraints** value is a list of keywords, each of these keywords should be the name of a constraint defined by a call to **testConstraint**. If any of the listed constraints is false or does not exist, the test is skipped. If the **-constraints** value is an expression, that expression is evaluated. If the expression evaluates to true, then the test is run. Note that the expression form of **-constraints** may interfere with the operation of **configure -constraints** and **configure -limitconstraints**, and is not recommended. Appropriate constraints should be added to any tests that should not always be run. That is, conditional evaluation of a test should be accomplished by the **-constraints** option, not by conditional evaluation of **test**. In that way, the same number of tests are always reported by the test suite, though the number skipped may change based on the testing environment. The default value is an empty list. See **[TEST CONSTRAINTS](#M59)** below for a list of built-in constraints and information on how to add your own constraints. 


**-setup** *script*

 The optional **-setup** attribute indicates a *script* that will be run before the script indicated by the **-body** attribute. If evaluation of *script* raises an error, the test will fail. The default value is an empty script. 


**-body** *script*

 The **-body** attribute indicates the *script* to run to carry out the test, which must return a result that can be checked for correctness. If evaluation of *script* raises an error, the test will fail (unless the **-returnCodes** option is used to state that an error is expected). The default value is an empty script. 


**-cleanup** *script*

 The optional **-cleanup** attribute indicates a *script* that will be run after the script indicated by the **-body** attribute. If evaluation of *script* raises an error, the test will fail. The default value is an empty script. 


**-match** *mode*

 The **-match** attribute determines how expected answers supplied by **-result**, **-output**, and **-errorOutput** are compared. Valid values for *mode* are **[regexp](regexp.htm)**, **[glob](glob.htm)**, **exact**, and any value registered by a prior call to **customMatch**. The default value is **exact**. 


**-result** *expectedValue*

 The **-result** attribute supplies the *expectedValue* against which the return value from script will be compared. The default value is an empty string. 


**-output** *expectedValue*

 The **-output** attribute supplies the *expectedValue* against which any output sent to **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** or **outputChannel** during evaluation of the script(s) will be compared. Note that only output printed using the global **[puts](puts.htm)** command is used for comparison. If **-output** is not specified, output sent to **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** and **outputChannel** is not processed for comparison. 


**-errorOutput** *expectedValue*

 The **-errorOutput** attribute supplies the *expectedValue* against which any output sent to **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** or **errorChannel** during evaluation of the script(s) will be compared. Note that only output printed using the global **[puts](puts.htm)** command is used for comparison. If **-errorOutput** is not specified, output sent to **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** and **errorChannel** is not processed for comparison. 


**-returnCodes** *expectedCodeList*

 The optional **-returnCodes** attribute supplies *expectedCodeList*, a list of return codes that may be accepted from evaluation of the **-body** script. If evaluation of the **-body** script returns a code not in the *expectedCodeList*, the test fails. All return codes known to **[return](return.htm)**, in both numeric and symbolic form, including extended return codes, are acceptable elements in the *expectedCodeList*. Default value is “**ok return**”. 

  To pass, a test must successfully evaluate its **-setup**, **-body**, and **-cleanup** scripts. The return code of the **-body** script and its result must match expected values, and if specified, output and error data from the test must match expected **-output** and **-errorOutput** values. If any of these conditions are not met, then the test fails. Note that all scripts are evaluated in the context of the caller of **test**. 


 As long as **test** is called with valid syntax and legal values for all attributes, it will not raise an error. Test failures are instead reported as output written to **outputChannel**. In default operation, a successful test produces no output. The output messages produced by **test** are controlled by the **configure -verbose** option as described in **[CONFIGURABLE OPTIONS](#M87)** below. Any output produced by the test scripts themselves should be produced using **[puts](puts.htm)** to **outputChannel** or **errorChannel**, so that users of the test suite may easily capture output with the **configure -outfile** and **configure -errfile** options, and so that the **-output** and **-errorOutput** attributes work properly. 


### Test constraints

 Constraints are used to determine whether or not a test should be skipped. Each constraint has a name, which may be any string, and a boolean value. Each **test** has a **-constraints** value which is a list of constraint names. There are two modes of constraint control. Most frequently, the default mode is used, indicated by a setting of **configure -limitconstraints** to false. The test will run only if all constraints in the list are true-valued. Thus, the **-constraints** option of **test** is a convenient, symbolic way to define any conditions required for the test to be possible or meaningful. For example, a **test** with **-constraints unix** will only be run if the constraint **unix** is true, which indicates the test suite is being run on a Unix platform.  Each **test** should include whatever **-constraints** are required to constrain it to run only where appropriate. Several constraints are pre-defined in the **tcltest** package, listed below. The registration of user-defined constraints is performed by the **testConstraint** command. User-defined constraints may appear within a test file, or within the script specified by the **configure -load** or **configure -loadfile** options. 


 The following is a list of constraints pre-defined by the **tcltest** package itself: 


 *singleTestInterp*
 This test can only be run if all test files are sourced into a single interpreter. 

*unix*
 This test can only be run on any Unix platform. 

*win*
 This test can only be run on any Windows platform. 

*nt*
 This test can only be run on any Windows NT platform. 

*mac*
 This test can only be run on any Mac platform. 

*unixOrWin*
 This test can only be run on a Unix or Windows platform. 

*macOrWin*
 This test can only be run on a Mac or Windows platform. 

*macOrUnix*
 This test can only be run on a Mac or Unix platform. 

*tempNotWin*
 This test can not be run on Windows. This flag is used to temporarily disable a test. 

*tempNotMac*
 This test can not be run on a Mac. This flag is used to temporarily disable a test. 

*unixCrash*
 This test crashes if it is run on Unix. This flag is used to temporarily disable a test. 

*winCrash*
 This test crashes if it is run on Windows. This flag is used to temporarily disable a test. 

*macCrash*
 This test crashes if it is run on a Mac. This flag is used to temporarily disable a test. 

*emptyTest*
 This test is empty, and so not worth running, but it remains as a place-holder for a test to be written in the future. This constraint has value false to cause tests to be skipped unless the user specifies otherwise. 

*knownBug*
 This test is known to fail and the bug is not yet fixed. This constraint has value false to cause tests to be skipped unless the user specifies otherwise. 

*nonPortable*
 This test can only be run in some known development environment. Some tests are inherently non-portable because they depend on things like word length, file system configuration, window manager, etc. This constraint has value false to cause tests to be skipped unless the user specifies otherwise. 

*userInteraction*
 This test requires interaction from the user. This constraint has value false to causes tests to be skipped unless the user specifies otherwise. 

*interactive*
 This test can only be run in if the interpreter is in interactive mode (when the global tcl\_interactive variable is set to 1). 

*nonBlockFiles*
 This test can only be run if platform supports setting files into nonblocking mode. 

*asyncPipeClose*
 This test can only be run if platform supports async flush and async close on a pipe. 

*unixExecs*
 This test can only be run if this machine has Unix-style commands **cat**, **echo**, **sh**, **wc**, **rm**, **sleep**, **fgrep**, **ps**, **chmod**, and **mkdir** available. 

*hasIsoLocale*
 This test can only be run if can switch to an ISO locale. 

*root*
 This test can only run if Unix user is root. 

*notRoot*
 This test can only run if Unix user is not root. 

*eformat*
 This test can only run if app has a working version of sprintf with respect to the “e” format of floating-point numbers. 

*stdio*
 This test can only be run if **interpreter** can be **[open](open.htm)**ed as a pipe. 

  The alternative mode of constraint control is enabled by setting **configure -limitconstraints** to true. With that configuration setting, all existing constraints other than those in the constraint list returned by **configure -constraints** are set to false. When the value of **configure -constraints** is set, all those constraints are set to true. The effect is that when both options **configure -constraints** and **configure -limitconstraints** are in use, only those tests including only constraints from the **configure -constraints** list are run; all others are skipped. For example, one might set up a configuration with 



```
**configure** -constraints knownBug \
          -limitconstraints true \
          -verbose pass
```
  to run exactly those tests that exercise known bugs, and discover whether any of them pass, indicating the bug had been fixed. 


### Running all tests

 The single command **runAllTests** is evaluated to run an entire test suite, spanning many files and directories. The configuration options of **tcltest** control the precise operations. The **runAllTests** command begins by printing a summary of its configuration to **outputChannel**.  Test files to be evaluated are sought in the directory **configure -testdir**. The list of files in that directory that match any of the patterns in **configure -file** and match none of the patterns in **configure -notfile** is generated and sorted. Then each file will be evaluated in turn. If **configure -singleproc** is true, then each file will be **[source](source.htm)**d in the caller's context. If it is false, then a copy of **interpreter** will be **[exec](exec.htm)**'d to evaluate each file. The multi-process operation is useful when testing can cause errors so severe that a process terminates. Although such an error may terminate a child process evaluating one file, the master process can continue with the rest of the test suite. In multi-process operation, the configuration of **tcltest** in the master process is passed to the child processes as command line arguments, with the exception of **configure -outfile**. The **runAllTests** command in the master process collects all output from the child processes and collates their results into one master report. Any reports of individual test failures, or messages requested by a **configure -verbose** setting are passed directly on to **outputChannel** by the master process. 


 After evaluating all selected test files, a summary of the results is printed to **outputChannel**. The summary includes the total number of **test**s evaluated, broken down into those skipped, those passed, and those failed. The summary also notes the number of files evaluated, and the names of any files with failing tests or errors. A list of the constraints that caused tests to be skipped, and the number of tests skipped for each is also printed. Also, messages are printed if it appears that evaluation of a test file has caused any temporary files to be left behind in **configure -tmpdir**. 


 Having completed and summarized all selected test files, **runAllTests** then recursively acts on subdirectories of **configure -testdir**. All subdirectories that match any of the patterns in **configure -relateddir** and do not match any of the patterns in **configure -asidefromdir** are examined. If a file named **all.tcl** is found in such a directory, it will be **[source](source.htm)**d in the caller's context. Whether or not an examined directory contains an **all.tcl** file, its subdirectories are also scanned against the **configure -relateddir** and **configure -asidefromdir** patterns. In this way, many directories in a directory tree can have all their test files evaluated by a single **runAllTests** command. 


Configurable options
--------------------

 The **configure** command is used to set and query the configurable options of **tcltest**. The valid options are: 
 
**-singleproc** *boolean*

 Controls whether or not **runAllTests** spawns a child process for each test file. No spawning when *boolean* is true. Default value is false. 


**-debug** *level*

 Sets the debug level to *level*, an integer value indicating how much debugging information should be printed to **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**. Note that debug messages always go to **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, independent of the value of **configure -outfile**. Default value is 0. Levels are defined as: 
 0
 Do not display any debug information. 

1
 Display information regarding whether a test is skipped because it does not match any of the tests that were specified using by **configure -match** (userSpecifiedNonMatch) or matches any of the tests specified by **configure -skip** (userSpecifiedSkip). Also print warnings about possible lack of cleanup or balance in test files. Also print warnings about any re-use of test names. 

2
 Display the flag array parsed by the command line processor, the contents of the global **[env](tclvars.htm)** array, and all user-defined variables that exist in the current namespace as they are used. 

3
 Display information regarding what individual procs in the test harness are doing. 




**-verbose** *level*

 Sets the type of output verbosity desired to *level*, a list of zero or more of the elements **body**, **pass**, **skip**, **start**, **error**, **line**, **msec** and **usec**. Default value is “**body error**”. Levels are defined as: 
 body (**b**)
 Display the body of failed tests 

pass (**p**)
 Print output when a test passes 

skip (**s**)
 Print output when a test is skipped 

start (**t**)
 Print output whenever a test starts 

error (**e**)
 Print errorInfo and errorCode, if they exist, when a test return code does not match its expected return code 

line (**l**)
 Print source file line information of failed tests 

msec (**m**)
 Print each test's execution time in milliseconds 

usec (**u**)
 Print each test's execution time in microseconds 

   Note that the **msec** and **usec** verbosity levels are provided as indicative measures only. They do not tackle the problem of repeatibility which should be considered in performance tests or benchmarks. To use these verbosity levels to thoroughly track performance degradations, consider wrapping your test bodies with **[time](time.htm)** commands. 


 The single letter abbreviations noted above are also recognized so that “**configure -verbose pt**” is the same as “**configure -verbose {pass start}**”. 





**-preservecore** *level*

 Sets the core preservation level to *level*. This level determines how stringent checks for core files are. Default value is 0. Levels are defined as: 
 0
 No checking — do not check for core files at the end of each test command, but do check for them in **runAllTests** after all test files have been evaluated. 

1
 Also check for core files at the end of each **test** command. 

2
 Check for core files at all times described above, and save a copy of each core file produced in **configure -tmpdir**. 




**-limitconstraints** *boolean*

 Sets the mode by which **test** honors constraints as described in **[TESTS](#M49)** above. Default value is false. 


**-constraints** *list*

 Sets all the constraints in *list* to true. Also used in combination with **configure -limitconstraints true** to control an alternative constraint mode as described in **[TESTS](#M49)** above. Default value is an empty list. 


**-tmpdir** *directory*

 Sets the temporary directory to be used by **makeFile**, **makeDirectory**, **viewFile**, **removeFile**, and **removeDirectory** as the default directory where temporary files and directories created by test files should be created. Default value is **workingDirectory**. 


**-testdir** *directory*

 Sets the directory searched by **runAllTests** for test files and subdirectories. Default value is **workingDirectory**. 


**-file** *patternList*

 Sets the list of patterns used by **runAllTests** to determine what test files to evaluate. Default value is “**\*.test**”. 


**-notfile** *patternList*

 Sets the list of patterns used by **runAllTests** to determine what test files to skip. Default value is “**l.\*.test**”, so that any SCCS lock files are skipped. 


**-relateddir** *patternList*

 Sets the list of patterns used by **runAllTests** to determine what subdirectories to search for an **all.tcl** file. Default value is “**\***”. 


**-asidefromdir** *patternList*

 Sets the list of patterns used by **runAllTests** to determine what subdirectories to skip when searching for an **all.tcl** file. Default value is an empty list. 


**-match** *patternList*

 Set the list of patterns used by **test** to determine whether a test should be run. Default value is “**\***”. 


**-skip** *patternList*

 Set the list of patterns used by **test** to determine whether a test should be skipped. Default value is an empty list. 


**-load** *script*

 Sets a script to be evaluated by **loadTestedCommands**. Default value is an empty script. 


**-loadfile** *filename*

 Sets the filename from which to read a script to be evaluated by **loadTestedCommands**. This is an alternative to **-load**. They cannot be used together. 


**-outfile** *filename*

 Sets the file to which all output produced by tcltest should be written. A file named *filename* will be **[open](open.htm)**ed for writing, and the resulting channel will be set as the value of **outputChannel**. 


**-errfile** *filename*

 Sets the file to which all error output produced by tcltest should be written. A file named *filename* will be **[open](open.htm)**ed for writing, and the resulting channel will be set as the value of **errorChannel**. 

 Creating test suites with tcltest
---------------------------------

 The fundamental element of a test suite is the individual **test** command. We begin with several examples. 
1. Test of a script that returns normally. 

```
**test** example-1.0 {normal return} {
    format %s value
} value
```
2. Test of a script that requires context setup and cleanup. Note the bracing and indenting style that avoids any need for line continuation. 

```
**test** example-1.1 {test file existence} -setup {
    set file [makeFile {} test]
} -body {
    file exists $file
} -cleanup {
    removeFile test
} -result 1
```
3. Test of a script that raises an error. 

```
**test** example-1.2 {error return} -body {
    error message
} -returnCodes error -result message
```
4. Test with a constraint. 

```
**test** example-1.3 {user owns created files} -constraints {
    unix
} -setup {
    set file [makeFile {} test]
} -body {
    file attributes $file -owner
} -cleanup {
    removeFile test
} -result $::tcl_platform(user)
```

  At the next higher layer of organization, several **test** commands are gathered together into a single test file. Test files should have names with the “**.test**” extension, because that is the default pattern used by **runAllTests** to find test files. It is a good rule of thumb to have one test file for each source code file of your project. It is good practice to edit the test file and the source code file together, keeping tests synchronized with code changes. 


 Most of the code in the test file should be the **test** commands. Use constraints to skip tests, rather than conditional evaluation of **test**. 


1. Recommended system for writing conditional tests, using constraints to guard: 

```
**testConstraint** X [expr $myRequirement]
**test** goodConditionalTest {} X {
    # body
} result
```
2. Discouraged system for writing conditional tests, using **[if](if.htm)** to guard: 

```
if $myRequirement {
    **test** badConditionalTest {} {
        #body
    } result
}
```

  Use the **-setup** and **-cleanup** options to establish and release all context requirements of the test body. Do not make tests depend on prior tests in the file. Those prior tests might be skipped. If several consecutive tests require the same context, the appropriate setup and cleanup scripts may be stored in variable for passing to each tests **-setup** and **-cleanup** options. This is a better solution than performing setup outside of **test** commands, because the setup will only be done if necessary, and any errors during setup will be reported, and not cause the test file to abort. 


 A test file should be able to be combined with other test files and not interfere with them, even when **configure -singleproc 1** causes all files to be evaluated in a common interpreter. A simple way to achieve this is to have your tests define all their commands and variables in a namespace that is deleted when the test file evaluation is complete. A good namespace to use is a child namespace **test** of the namespace of the module you are testing. 


 A test file should also be able to be evaluated directly as a script, not depending on being called by a master **runAllTests**. This means that each test file should process command line arguments to give the tester all the configuration control that **tcltest** provides. 


 After all **test**s in a test file, the command **cleanupTests** should be called. 


1. Here is a sketch of a sample test file illustrating those points: 

```
package require tcltest 2.2
eval **::tcltest::configure** $argv
package require example
namespace eval ::example::test {
    namespace import ::tcltest::*
    **testConstraint** X [expr {...}]
    variable SETUP {#common setup code}
    variable CLEANUP {#common cleanup code}
    **test** example-1 {} -setup $SETUP -body {
        # First test
    } -cleanup $CLEANUP -result {...}
    **test** example-2 {} -constraints X -setup $SETUP -body {
        # Second test; constrained
    } -cleanup $CLEANUP -result {...}
    **test** example-3 {} {
        # Third test; no context required
    } {...}
    **cleanupTests**
}
namespace delete ::example::test
```

  The next level of organization is a full test suite, made up of several test files. One script is used to control the entire suite. The basic function of this script is to call **runAllTests** after doing any necessary setup. This script is usually named **all.tcl** because that is the default name used by **runAllTests** when combining multiple test suites into one testing run. 


1. Here is a sketch of a sample test suite master script: 

```
package require Tcl 8.4
package require tcltest 2.2
package require example
**::tcltest::configure** -testdir \
        [file dirname [file normalize [info script]]]
eval **::tcltest::configure** $argv
**::tcltest::runAllTests**
```

 Compatibility
-------------

 A number of commands and variables in the **::tcltest** namespace provided by earlier releases of **tcltest** have not been documented here. They are no longer part of the supported public interface of **tcltest** and should not be used in new test suites. However, to continue to support existing test suites written to the older interface specifications, many of those deprecated commands and variables still work as before. For example, in many circumstances, **configure** will be automatically called shortly after **[package require](package.htm)** **tcltest 2.1** succeeds with arguments from the variable **::argv**. This is to support test suites that depend on the old behavior that **tcltest** was automatically configured from command line arguments. New test files should not depend on this, but should explicitly include 

```
eval **::tcltest::configure** $::argv
```
  or 



```
**::tcltest::configure** {*}$::argv
```
  to establish a configuration from command line arguments. 


Known issues
------------

 There are two known issues related to nested evaluations of **test**. The first issue relates to the stack level in which test scripts are executed. Tests nested within other tests may be executed at the same stack level as the outermost test. For example, in the following code: 

```
**test** level-1.1 {level 1} {
    -body {
        **test** level-2.1 {level 2} {
        }
    }
}
```
  any script executed in level-2.1 may be executed at the same stack level as the script defined for level-1.1. 


 In addition, while two **test**s have been run, results will only be reported by **cleanupTests** for tests at the same level as test level-1.1. However, test results for all tests run prior to level-1.1 will be available when test level-2.1 runs. What this means is that if you try to access the test results for test level-2.1, it will may say that “m” tests have run, “n” tests have been skipped, “o” tests have passed and “p” tests have failed, where “m”, “n”, “o”, and “p” refer to tests that were run at the same test level as test level-1.1. 


 Implementation of output and error comparison in the test command depends on usage of **[puts](puts.htm)** in your application code. Output is intercepted by redefining the global **[puts](puts.htm)** command while the defined test script is being run. Errors thrown by C procedures or printed directly from C applications will not be caught by the **test** command. Therefore, usage of the **-output** and **-errorOutput** options to **test** is useful only for pure Tcl applications that use **[puts](puts.htm)** to produce output. 

 Copyright © 1990-1994 The Regents of the University of California  
 Copyright © 1994-1997 Sun Microsystems, Inc.  
 Copyright © 1998-1999 Scriptics Corporation  
 Copyright © 2000 Ajuba Solutions 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/tcltest.htm>

string
======

  
[NAME](string.htm#M2) string — Manipulate strings 
[SYNOPSIS](string.htm#M3) 
[DESCRIPTION](string.htm#M4)  
[**string cat** ?*string1*? ?*string2...*?](string.htm#M5) 
[**string compare** ?**-nocase**? ?**-length** *length*? *string1 string2*](string.htm#M6) 
[**string equal** ?**-nocase**? ?**-length** *length*? *string1 string2*](string.htm#M7) 
[**string first** *needleString haystackString* ?*startIndex*?](string.htm#M8) 
[**string index** *string charIndex*](string.htm#M9) 
[**string is** *class* ?**-strict**? ?**-failindex** *varname*? *string*](string.htm#M10)  
[**alnum**](string.htm#M11) 
[**alpha**](string.htm#M12) 
[**ascii**](string.htm#M13) 
[**boolean**](string.htm#M14) 
[**control**](string.htm#M15) 
[**digit**](string.htm#M16) 
[**double**](string.htm#M17) 
[**entier**](string.htm#M18) 
[**false**](string.htm#M19) 
[**graph**](string.htm#M20) 
[**integer**](string.htm#M21) 
[**list**](string.htm#M22) 
[**lower**](string.htm#M23) 
[**print**](string.htm#M24) 
[**punct**](string.htm#M25) 
[**space**](string.htm#M26) 
[**true**](string.htm#M27) 
[**upper**](string.htm#M28) 
[**wideinteger**](string.htm#M29) 
[**wordchar**](string.htm#M30) 
[**xdigit**](string.htm#M31) 




















 
[**string last** *needleString haystackString* ?*lastIndex*?](string.htm#M32) 
[**string length** *string*](string.htm#M33) 
[**string map** ?**-nocase**? *mapping string*](string.htm#M34) 
[**string match** ?**-nocase**? *pattern* *string*](string.htm#M35)  
[**\***](string.htm#M36) 
[**?**](string.htm#M37) 
[**[***chars***]**](string.htm#M38) 
[**\***x*](string.htm#M39) 



 
[**string range** *string first last*](string.htm#M40) 
[**string repeat** *string count*](string.htm#M41) 
[**string replace** *string first last* ?*newstring*?](string.htm#M42) 
[**string reverse** *string*](string.htm#M43) 
[**string tolower** *string* ?*first*? ?*last*?](string.htm#M44) 
[**string totitle** *string* ?*first*? ?*last*?](string.htm#M45) 
[**string toupper** *string* ?*first*? ?*last*?](string.htm#M46) 
[**string trim** *string* ?*chars*?](string.htm#M47) 
[**string trimleft** *string* ?*chars*?](string.htm#M48) 
[**string trimright** *string* ?*chars*?](string.htm#M49) 



















 
[OBSOLETE SUBCOMMANDS](string.htm#M50)  
[**string bytelength** *string*](string.htm#M51) 
[**string wordend** *string charIndex*](string.htm#M52) 
[**string wordstart** *string charIndex*](string.htm#M53) 


 
[STRING INDICES](string.htm#M54)  
[*integer*](string.htm#M55) 
[**end**](string.htm#M56) 
[**end-***N*](string.htm#M57) 
[**end+***N*](string.htm#M58) 
[*M***+***N*](string.htm#M59) 
[*M***-***N*](string.htm#M60) 





 
[EXAMPLE](string.htm#M61) 
[SEE ALSO](string.htm#M62) 
[KEYWORDS](string.htm#M63) 







 Name
----

 string — Manipulate strings Synopsis
--------

 **string** *option arg* ?*arg ...?*  
 Description
-----------

 Performs one of several string operations, depending on *option*. The legal *option*s (which may be abbreviated) are: 
 
**string cat** ?*string1*? ?*string2...*?
 Concatenate the given *string*s just like placing them directly next to each other and return the resulting compound string. If no *string*s are present, the result is an empty string.  This primitive is occasionally handier than juxtaposition of strings when mixed quoting is wanted, or when the aim is to return the result of a concatenation without resorting to **[return](return.htm)** **-level 0**, and is more efficient than building a list of arguments and using **[join](join.htm)** with an empty join string. 




**string compare** ?**-nocase**? ?**-length** *length*? *string1 string2*

 Perform a character-by-character comparison of strings *string1* and *string2*. Returns -1, 0, or 1, depending on whether *string1* is lexicographically less than, equal to, or greater than *string2*. If **-length** is specified, then only the first *length* characters are used in the comparison. If **-length** is negative, it is ignored. If **-nocase** is specified, then the strings are compared in a case-insensitive manner. 


**string equal** ?**-nocase**? ?**-length** *length*? *string1 string2*

 Perform a character-by-character comparison of strings *string1* and *string2*. Returns 1 if *string1* and *string2* are identical, or 0 when not. If **-length** is specified, then only the first *length* characters are used in the comparison. If **-length** is negative, it is ignored. If **-nocase** is specified, then the strings are compared in a case-insensitive manner. 


**string first** *needleString haystackString* ?*startIndex*?
 Search *haystackString* for a sequence of characters that exactly match the characters in *needleString*. If found, return the index of the first character in the first such match within *haystackString*. If not found, return -1. If *startIndex* is specified (in any of the forms described in **[STRING INDICES](#M54)**), then the search is constrained to start with the character in *haystackString* specified by the index. For example, 

```
**string first a 0a23456789abcdef 5**
```
  will return **10**, but 



```
**string first a 0123456789abcdef 11**
```
 will return **-1**. 




**string index** *string charIndex*

 Returns the *charIndex*'th character of the *string* argument. A *charIndex* of 0 corresponds to the first character of the string. *charIndex* may be specified as described in the **[STRING INDICES](#M54)** section.  If *charIndex* is less than 0 or greater than or equal to the length of the string then this command returns an empty string. 




**string is** *class* ?**-strict**? ?**-failindex** *varname*? *string*

 Returns 1 if *string* is a valid member of the specified character class, otherwise returns 0. If **-strict** is specified, then an empty string returns 0, otherwise an empty string will return 1 on any class. If **-failindex** is specified, then if the function returns 0, the index in the string where the class was no longer valid will be stored in the variable named *varname*. The *varname* will not be set if **string is** returns 1. The following character classes are recognized (the class name can be abbreviated): 
 **alnum**
 Any Unicode alphabet or digit character. 

**alpha**
 Any Unicode alphabet character. 

**ascii**
 Any character with a value less than \u0080 (those that are in the 7-bit ascii range). 

**boolean**
 Any of the forms allowed to **[Tcl\_GetBoolean](https://www.tcl.tk/man/tcl/TclLib/GetInt.htm)**. 

**control**
 Any Unicode control character. 

**digit**
 Any Unicode digit character. Note that this includes characters outside of the [0-9] range. 

**double**
 Any of the valid forms for a double in Tcl, with optional surrounding whitespace. In case of under/overflow in the value, 0 is returned and the *varname* will contain -1. 

**entier**
 Any of the valid string formats for an integer value of arbitrary size in Tcl, with optional surrounding whitespace. The formats accepted are exactly those accepted by the C routine **[Tcl\_GetBignumFromObj](https://www.tcl.tk/man/tcl/TclLib/IntObj.htm)**. 

**false**
 Any of the forms allowed to **[Tcl\_GetBoolean](https://www.tcl.tk/man/tcl/TclLib/GetInt.htm)** where the value is false. 

**graph**
 Any Unicode printing character, except space. 

**integer**
 Any of the valid string formats for a 32-bit integer value in Tcl, with optional surrounding whitespace. In case of under/overflow in the value, 0 is returned and the *varname* will contain -1. 

**list**
 Any proper list structure, with optional surrounding whitespace. In case of improper list structure, 0 is returned and the *varname* will contain the index of the “element” where the list parsing fails, or -1 if this cannot be determined. 

**lower**
 Any Unicode lower case alphabet character. 

**print**
 Any Unicode printing character, including space. 

**punct**
 Any Unicode punctuation character. 

**space**
 Any Unicode whitespace character, mongolian vowel separator (U+180e), zero width space (U+200b), word joiner (U+2060) or zero width no-break space (U+feff) (=BOM). 

**true**
 Any of the forms allowed to **[Tcl\_GetBoolean](https://www.tcl.tk/man/tcl/TclLib/GetInt.htm)** where the value is true. 

**upper**
 Any upper case alphabet character in the Unicode character set. 

**wideinteger**
 Any of the valid forms for a wide integer in Tcl, with optional surrounding whitespace. In case of under/overflow in the value, 0 is returned and the *varname* will contain -1. 

**wordchar**
 Any Unicode word character. That is any alphanumeric character, and any Unicode connector punctuation characters (e.g. underscore). 

**xdigit**
 Any hexadecimal digit character ([0-9A-Fa-f]). 

In the case of **boolean**, **true** and **false**, if the function will return 0, then the *varname* will always be set to 0, due to the varied nature of a valid boolean value.




**string last** *needleString haystackString* ?*lastIndex*?
 Search *haystackString* for a sequence of characters that exactly match the characters in *needleString*. If found, return the index of the first character in the last such match within *haystackString*. If there is no match, then return -1. If *lastIndex* is specified (in any of the forms described in **[STRING INDICES](#M54)**), then only the characters in *haystackString* at or before the specified *lastIndex* will be considered by the search. For example, 

```
**string last a 0a23456789abcdef 15**
```
  will return **10**, but 



```
**string last a 0a23456789abcdef 9**
```
 will return **1**. 




**string length** *string*

 Returns a decimal string giving the number of characters in *string*. Note that this is not necessarily the same as the number of bytes used to store the string. If the value is a byte array value (such as those returned from reading a binary encoded channel), then this will return the actual byte length of the value. 


**string map** ?**-nocase**? *mapping string*

 Replaces substrings in *string* based on the key-value pairs in *mapping*. *mapping* is a list of *key value key value ...* as in the form returned by **[array get](array.htm)**. Each instance of a key in the string will be replaced with its corresponding value. If **-nocase** is specified, then matching is done without regard to case differences. Both *key* and *value* may be multiple characters. Replacement is done in an ordered manner, so the key appearing first in the list will be checked first, and so on. *string* is only iterated over once, so earlier key replacements will have no affect for later key matches. For example, 

```
**string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc**
```
  will return the string **01321221**. 


 Note that if an earlier *key* is a prefix of a later one, it will completely mask the later one. So if the previous example is reordered like this, 



```
**string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc**
```
 it will return the string **02c322c222c**. 




**string match** ?**-nocase**? *pattern* *string*

 See if *pattern* matches *string*; return 1 if it does, 0 if it does not. If **-nocase** is specified, then the pattern attempts to match against the string in a case insensitive manner. For the two strings to match, their contents must be identical except that the following special sequences may appear in *pattern*: 
 **\***
 Matches any sequence of characters in *string*, including a null string. 

**?**
 Matches any single character in *string*. 


**[***chars***]**

 Matches any character in the set given by *chars*. If a sequence of the form *x***-***y* appears in *chars*, then any character between *x* and *y*, inclusive, will match. When used with **-nocase**, the end points of the range are converted to lower case first. Whereas {[A-z]} matches “\_” when matching case-sensitively (since “\_” falls between the “Z” and “a”), with **-nocase** this is considered like {[A-Za-z]} (and probably what was meant in the first place). 


**\***x*

 Matches the single character *x*. This provides a way of avoiding the special interpretation of the characters **\*?[]\** in *pattern*. 




**string range** *string first last*

 Returns a range of consecutive characters from *string*, starting with the character whose index is *first* and ending with the character whose index is *last*. An index of 0 refers to the first character of the string. *first* and *last* may be specified as for the **index** method. If *first* is less than zero then it is treated as if it were zero, and if *last* is greater than or equal to the length of the string then it is treated as if it were **end**. If *first* is greater than *last* then an empty string is returned. 


**string repeat** *string count*

 Returns *string* repeated *count* number of times. 


**string replace** *string first last* ?*newstring*?
 Removes a range of consecutive characters from *string*, starting with the character whose index is *first* and ending with the character whose index is *last*. An index of 0 refers to the first character of the string. *First* and *last* may be specified as for the **index** method. If *newstring* is specified, then it is placed in the removed character range. If *first* is less than zero then it is treated as if it were zero, and if *last* is greater than or equal to the length of the string then it is treated as if it were **end**. If *first* is greater than *last* or the length of the initial string, or *last* is less than 0, then the initial string is returned untouched. 


**string reverse** *string*

 Returns a string that is the same length as *string* but with its characters in the reverse order. 


**string tolower** *string* ?*first*? ?*last*?
 Returns a value equal to *string* except that all upper (or title) case letters have been converted to lower case. If *first* is specified, it refers to the first char index in the string to start modifying. If *last* is specified, it refers to the char index in the string to stop at (inclusive). *first* and *last* may be specified using the forms described in **[STRING INDICES](#M54)**. 


**string totitle** *string* ?*first*? ?*last*?
 Returns a value equal to *string* except that the first character in *string* is converted to its Unicode title case variant (or upper case if there is no title case variant) and the rest of the string is converted to lower case. If *first* is specified, it refers to the first char index in the string to start modifying. If *last* is specified, it refers to the char index in the string to stop at (inclusive). *first* and *last* may be specified using the forms described in **[STRING INDICES](#M54)**. 


**string toupper** *string* ?*first*? ?*last*?
 Returns a value equal to *string* except that all lower (or title) case letters have been converted to upper case. If *first* is specified, it refers to the first char index in the string to start modifying. If *last* is specified, it refers to the char index in the string to stop at (inclusive). *first* and *last* may be specified using the forms described in **[STRING INDICES](#M54)**. 


**string trim** *string* ?*chars*?
 Returns a value equal to *string* except that any leading or trailing characters present in the string given by *chars* are removed. If *chars* is not specified then white space is removed (any character for which **string is space** returns 1, and " "). 


**string trimleft** *string* ?*chars*?
 Returns a value equal to *string* except that any leading characters present in the string given by *chars* are removed. If *chars* is not specified then white space is removed (any character for which **string is space** returns 1, and " "). 


**string trimright** *string* ?*chars*?
 Returns a value equal to *string* except that any trailing characters present in the string given by *chars* are removed. If *chars* is not specified then white space is removed (any character for which **string is space** returns 1, and " "). 

 ### Obsolete subcommands

 These subcommands are currently supported, but are likely to go away in a future release as their functionality is either virtually never used or highly misleading. 
 
**string bytelength** *string*

 Returns a decimal string giving the number of bytes used to represent *string* in memory when encoded as Tcl's internal modified UTF-8; Tcl may use other encodings for *string* as well, and does not guarantee to only use a single encoding for a particular *string*. Because UTF-8 uses a variable number of bytes to represent Unicode characters, the byte length will not be the same as the character length in general. The cases where a script cares about the byte length are rare.  In almost all cases, you should use the **string length** operation (including determining the length of a Tcl byte array value). Refer to the **[Tcl\_NumUtfChars](https://www.tcl.tk/man/tcl/TclLib/Utf.htm)** manual entry for more details on the UTF-8 representation. 


 Formally, the **string bytelength** operation returns the content of the *length* field of the **[Tcl\_Obj](https://www.tcl.tk/man/tcl/TclLib/Object.htm)** structure, after calling **[Tcl\_GetString](https://www.tcl.tk/man/tcl/TclLib/StringObj.htm)** to ensure that the *bytes* field is populated. This is highly unlikely to be useful to Tcl scripts, as Tcl's internal encoding is not strict UTF-8, but rather a modified CESU-8 with a denormalized NUL (identical to that used in a number of places by Java's serialization mechanism) to enable basic processing with non-Unicode-aware C functions. As this representation should only ever be used by Tcl's implementation, the number of bytes used to store the representation is of very low value (except to C extension code, which has direct access for the purpose of memory management, etc.) 


 *Compatibility note:* it is likely that this subcommand will be withdrawn in a future version of Tcl. It is better to use the **[encoding convertto](encoding.htm)** command to convert a string to a known encoding and then apply **string length** to that. 



```
**string length** [encoding convertto utf-8 $theString]
```



**string wordend** *string charIndex*

 Returns the index of the character just after the last one in the word containing character *charIndex* of *string*. *charIndex* may be specified using the forms in **[STRING INDICES](#M54)**. A word is considered to be any contiguous range of alphanumeric (Unicode letters or decimal digits) or underscore (Unicode connector punctuation) characters, or any single character other than these. 


**string wordstart** *string charIndex*

 Returns the index of the first character in the word containing character *charIndex* of *string*. *charIndex* may be specified using the forms in **[STRING INDICES](#M54)**. A word is considered to be any contiguous range of alphanumeric (Unicode letters or decimal digits) or underscore (Unicode connector punctuation) characters, or any single character other than these. 

 String indices
--------------

 When referring to indices into a string (e.g., for **string index** or **string range**) the following formats are supported: 
 *integer*
 For any index value that passes **string is integer -strict**, the char specified at this integral index (e.g., **2** would refer to the “c” in “abcd”). 

**end**
 The last char of the string (e.g., **end** would refer to the “d” in “abcd”). 


**end-***N*

 The last char of the string minus the specified integer offset *N* (e.g., “**end-1**” would refer to the “c” in “abcd”). 


**end+***N*

 The last char of the string plus the specified integer offset *N* (e.g., “**end+-1**” would refer to the “c” in “abcd”). 


*M***+***N*

 The char specified at the integral index that is the sum of integer values *M* and *N* (e.g., “**1+1**” would refer to the “c” in “abcd”). 


*M***-***N*

 The char specified at the integral index that is the difference of integer values *M* and *N* (e.g., “**2-1**” would refer to the “b” in “abcd”). 

  In the specifications above, the integer value *M* contains no trailing whitespace and the integer value *N* contains no leading whitespace. 


Example
-------

 Test if the string in the variable *string* is a proper non-empty prefix of the string **foobar**. 

```
set length [**string length** $string]
if {$length == 0} {
    set isPrefix 0
} else {
    set isPrefix [**string equal** -length $length $string "foobar"]
}
```
 See also
--------

 **[expr](expr.htm)**, **[list](list.htm)** 

 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/string.htm>

uplevel
=======

 Name
----

 uplevel — Execute a script in a different stack frame Synopsis
--------

 **uplevel** ?*level*? *arg* ?*arg ...*?  
 Description
-----------

 All of the *arg* arguments are concatenated as if they had been passed to **[concat](concat.htm)**; the result is then evaluated in the variable context indicated by *level*. **Uplevel** returns the result of that evaluation.  If *level* is an integer then it gives a distance (up the procedure calling stack) to move before executing the command. If *level* consists of **#** followed by a number then the number gives an absolute level number. If *level* is omitted then it defaults to **1**. *Level* cannot be defaulted if the first *command* argument starts with a digit or **#**. 


 For example, suppose that procedure **a** was invoked from top-level, and that it called **b**, and that **b** called **c**. Suppose that **c** invokes the **uplevel** command. If *level* is **1** or **#2** or omitted, then the command will be executed in the variable context of **b**. If *level* is **2** or **#1** then the command will be executed in the variable context of **a**. If *level* is **3** or **#0** then the command will be executed at top-level (only global variables will be visible). 


 The **uplevel** command causes the invoking procedure to disappear from the procedure calling stack while the command is being executed. In the above example, suppose **c** invokes the command 



```
**uplevel** 1 {set x 43; d}
```
  where **d** is another Tcl procedure. The **[set](set.htm)** command will modify the variable **x** in **b**'s context, and **d** will execute at level 3, as if called from **b**. If it in turn executes the command 



```
**uplevel** {set x 42}
```
  then the **[set](set.htm)** command will modify the same variable **x** in **b**'s context: the procedure **c** does not appear to be on the call stack when **d** is executing. The **[info level](info.htm)** command may be used to obtain the level of the current procedure. 


 **Uplevel** makes it possible to implement new control constructs as Tcl procedures (for example, **uplevel** could be used to implement the **[while](while.htm)** construct as a Tcl procedure). 


 The **[namespace eval](namespace.htm)** and **[apply](apply.htm)** commands offer other ways (besides procedure calls) that the Tcl naming context can change. They add a call frame to the stack to represent the namespace context. This means each **[namespace eval](namespace.htm)** command counts as another call level for **uplevel** and **[upvar](upvar.htm)** commands. For example, **info level 1** will return a list describing a command that is either the outermost procedure call or the outermost **[namespace eval](namespace.htm)** command. Also, **uplevel #0** evaluates a script at top-level in the outermost namespace (the global namespace). 


Example
-------

 As stated above, the **uplevel** command is useful for creating new control constructs. This example shows how (without error handling) it can be used to create a **do** command that is the counterpart of **[while](while.htm)** except for always performing the test after running the loop body: 

```
proc do {body while condition} {
    if {$while ne "while"} {
        error "required word missing"
    }
    set conditionCmd [list expr $condition]
    while {1} {
        **uplevel** 1 $body
        if {![**uplevel** 1 $conditionCmd]} {
            break
        }
    }
}
```
 See also
--------

 **[apply](apply.htm)**, **[namespace](namespace.htm)**, **[upvar](upvar.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/uplevel.htm>

prefix
======

  
[NAME](prefix.htm#M2) tcl::prefix — facilities for prefix matching 
[SYNOPSIS](prefix.htm#M3) 
[DESCRIPTION](prefix.htm#M4)  
[**::tcl::prefix all** *table* *string*](prefix.htm#M5) 
[**::tcl::prefix longest** *table* *string*](prefix.htm#M6) 
[**::tcl::prefix match** ?*options*? *table* *string*](prefix.htm#M7)  
[**-exact**](prefix.htm#M8) 
[**-message** *string*](prefix.htm#M9) 
[**-error** *options*](prefix.htm#M10) 


 


 
[EXAMPLES](prefix.htm#M11) 
[SEE ALSO](prefix.htm#M12) 
[KEYWORDS](prefix.htm#M13) 





 Name
----

 tcl::prefix — facilities for prefix matching Synopsis
--------

 **::tcl::prefix all** *table* *string*  
 **::tcl::prefix longest** *table* *string*  
 **::tcl::prefix match** *?option ...?* *table* *string*  
 Description
-----------

 This document describes commands looking up a prefix in a list of strings. The following commands are supported: 
 
**::tcl::prefix all** *table* *string*

 Returns a list of all elements in *table* that begin with the prefix *string*. 


**::tcl::prefix longest** *table* *string*

 Returns the longest common prefix of all elements in *table* that begin with the prefix *string*. 


**::tcl::prefix match** ?*options*? *table* *string*

 If *string* equals one element in *table* or is a prefix to exactly one element, the matched element is returned. If not, the result depends on the **-error** option. (It is recommended that the *table* be sorted before use with this subcommand, so that the list of matches presented in the error message also becomes sorted, though this is not strictly necessary for the operation of this subcommand itself.) 
 **-exact**
 Accept only exact matches. 


**-message** *string*

 Use *string* in the error message at a mismatch. Default is “option”. 


**-error** *options*

 The *options* are used when no match is found. If *options* is empty, no error is generated and an empty string is returned. Otherwise the *options* are used as **[return](return.htm)** options when generating the error message. The default corresponds to setting “-level 0”. Example: If “**-error** {-errorcode MyError -level 1}” is used, an error would be generated as: 

```
return -errorcode MyError -level 1 -code error \
       "ambiguous option ..."
```




 Examples
--------

 Basic use: 

```
namespace import ::tcl::prefix
**prefix match** {apa bepa cepa} apa
     *→ apa*
**prefix match** {apa bepa cepa} a
     *→ apa*
**prefix match** -exact {apa bepa cepa} a
     *→ bad option "a": must be apa, bepa, or cepa*
**prefix match** -message "switch" {apa ada bepa cepa} a
     *→ ambiguous switch "a": must be apa, ada, bepa, or cepa*
**prefix longest** {fblocked fconfigure fcopy file fileevent flush} fc
     *→ fco*
**prefix all** {fblocked fconfigure fcopy file fileevent flush} fc
     *→ fconfigure fcopy*
```
  Simplifying option matching: 



```
array set opts {-apa 1 -bepa "" -cepa 0}
foreach {arg val} $args {
    set opts([**prefix match** {-apa -bepa -cepa} $arg]) $val
}
```
  Creating a **[switch](switch.htm)** that supports prefixes: 



```
switch [**prefix match** {apa bepa cepa} $arg] {
    apa  { }
    bepa { }
    cepa { }
}
```
 See also
--------

 **[lsearch](lsearch.htm)**, **[namespace](namespace.htm)**, **[string](string.htm)**, **[Tcl\_GetIndexFromObj](https://www.tcl.tk/man/tcl/TclLib/GetIndex.htm)** Copyright © 2008 Peter Spjuth <pspjuth(at)users.sourceforge.net> 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/prefix.htm>

upvar
=====

 Name
----

 upvar — Create link to variable in a different stack frame Synopsis
--------

 **upvar** ?*level*? *otherVar myVar* ?*otherVar myVar* ...?  
 Description
-----------

 This command arranges for one or more local variables in the current procedure to refer to variables in an enclosing procedure call or to global variables. *Level* may have any of the forms permitted for the **[uplevel](uplevel.htm)** command, and may be omitted (it defaults to **1**). For each *otherVar* argument, **upvar** makes the variable by that name in the procedure frame given by *level* (or at global level, if *level* is **#0**) accessible in the current procedure by the name given in the corresponding *myVar* argument. The variable named by *otherVar* need not exist at the time of the call; it will be created the first time *myVar* is referenced, just like an ordinary variable. There must not exist a variable by the name *myVar* at the time **upvar** is invoked. *MyVar* is always treated as the name of a variable, not an array element. An error is returned if the name looks like an array element, such as **a(b)**. *OtherVar* may refer to a scalar variable, an array, or an array element. **Upvar** returns an empty string.  The **upvar** command simplifies the implementation of call-by-name procedure calling and also makes it easier to build new control constructs as Tcl procedures. For example, consider the following procedure: 



```
proc *add2* name {
    **upvar** $name x
    set x [expr {$x + 2}]
}
```
  If *add2* is invoked with an argument giving the name of a variable, it adds two to the value of that variable. Although *add2* could have been implemented using **[uplevel](uplevel.htm)** instead of **upvar**, **upvar** makes it simpler for *add2* to access the variable in the caller's procedure frame. 


 **[namespace eval](namespace.htm)** is another way (besides procedure calls) that the Tcl naming context can change. It adds a call frame to the stack to represent the namespace context. This means each **[namespace eval](namespace.htm)** command counts as another call level for **[uplevel](uplevel.htm)** and **upvar** commands. For example, **[info level](info.htm)** **1** will return a list describing a command that is either the outermost procedure call or the outermost **[namespace eval](namespace.htm)** command. Also, **uplevel #0** evaluates a script at top-level in the outermost namespace (the global namespace). 


 If an upvar variable is unset (e.g. **x** in **add2** above), the **[unset](unset.htm)** operation affects the variable it is linked to, not the upvar variable. There is no way to unset an upvar variable except by exiting the procedure in which it is defined. However, it is possible to retarget an upvar variable by executing another **upvar** command. 


Traces and upvar
----------------

 Upvar interacts with traces in a straightforward but possibly unexpected manner. If a variable trace is defined on *otherVar*, that trace will be triggered by actions involving *myVar*. However, the trace procedure will be passed the name of *myVar*, rather than the name of *otherVar*. Thus, the output of the following code will be “*localVar*” rather than “*originalVar*”: 

```
proc *traceproc* { name index op } {
    puts $name
}
proc *setByUpvar* { name value } {
    **upvar** $name localVar
    set localVar $value
}
set originalVar 1
trace variable originalVar w *traceproc*
*setByUpvar* originalVar 2
```
  If *otherVar* refers to an element of an array, then variable traces set for the entire array will not be invoked when *myVar* is accessed (but traces on the particular element will still be invoked). In particular, if the array is **[env](tclvars.htm)**, then changes made to *myVar* will not be passed to subprocesses correctly. 


Example
-------

 A **decr** command that works like **[incr](incr.htm)** except it subtracts the value from the variable instead of adding it: 

```
proc decr {varName {decrement 1}} {
    **upvar** 1 $varName var
    incr var [expr {-$decrement}]
}
```
 See also
--------

 **[global](global.htm)**, **[namespace](namespace.htm)**, **[uplevel](uplevel.htm)**, **[variable](variable.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/upvar.htm>

variable
========

 Name
----

 variable — create and initialize a namespace variable Synopsis
--------

 **variable** *name*  
 **variable** ?*name value...*?  
 Description
-----------

 This command is normally used within a **[namespace eval](namespace.htm)** command to create one or more variables within a namespace. Each variable *name* is initialized with *value*. The *value* for the last variable is optional.  If a variable *name* does not exist, it is created. In this case, if *value* is specified, it is assigned to the newly created variable. If no *value* is specified, the new variable is left undefined. If the variable already exists, it is set to *value* if *value* is specified or left unchanged if no *value* is given. Normally, *name* is unqualified (does not include the names of any containing namespaces), and the variable is created in the current namespace. If *name* includes any namespace qualifiers, the variable is created in the specified namespace. If the variable is not defined, it will be visible to the **[namespace which](namespace.htm)** command, but not to the **[info exists](info.htm)** command. 


 If the **variable** command is executed inside a Tcl procedure, it creates local variables linked to the corresponding namespace variables (and therefore these variables are listed by **[info vars](info.htm)**.) In this way the **variable** command resembles the **[global](global.htm)** command, although the **[global](global.htm)** command only links to variables in the global namespace. If any *value*s are given, they are used to modify the values of the associated namespace variables. If a namespace variable does not exist, it is created and optionally initialized. 


 A *name* argument cannot reference an element within an array. Instead, *name* should reference the entire array, and the initialization *value* should be left off. After the variable has been declared, elements within the array can be set using ordinary **[set](set.htm)** or **[array](array.htm)** commands. 


Examples
--------

 Create a variable in a namespace: 

```
namespace eval foo {
    **variable** bar 12345
}
```
  Create an array in a namespace: 



```
namespace eval someNS {
    **variable** someAry
    array set someAry {
        someName  someValue
        otherName otherValue
    }
}
```
  Access variables in namespaces from a procedure: 



```
namespace eval foo {
    proc spong {} {
        # Variable in this namespace
        **variable** bar
        puts "bar is $bar"

        # Variable in another namespace
        **variable** ::someNS::someAry
        parray someAry
    }
}
```
 See also
--------

 **[global](global.htm)**, **[namespace](namespace.htm)**, **[upvar](upvar.htm)** Copyright © 1993-1997 Bell Labs Innovations for Lucent Technologies  
 Copyright © 1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/variable.htm>

continue
========

 Name
----

 continue — Skip to the next iteration of a loop Synopsis
--------

 **continue**  
 Description
-----------

 This command is typically invoked inside the body of a looping command such as **[for](for.htm)** or **[foreach](foreach.htm)** or **[while](while.htm)**. It returns a 4 (**[TCL\_CONTINUE](catch.htm)**) result code, which causes a continue exception to occur. The exception causes the current script to be aborted out to the innermost containing loop command, which then continues with the next iteration of the loop. Catch exceptions are also handled in a few other situations, such as the **[catch](catch.htm)** command and the outermost scripts of procedure bodies. Example
-------

 Print a line for each of the integers from 0 to 10 *except* 5: 

```
for {set x 0} {$x<10} {incr x} {
    if {$x == 5} {
        **continue**
    }
    puts "x is $x"
}
```
 See also
--------

 **[break](break.htm)**, **[for](for.htm)**, **[foreach](foreach.htm)**, **[return](return.htm)**, **[while](while.htm)** Copyright © 1993-1994 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/continue.htm>

join
====

 Name
----

 join — Create a string by joining together list elements Synopsis
--------

 **join** *list* ?*joinString*?  
 Description
-----------

 The *list* argument must be a valid Tcl list. This command returns the string formed by joining all of the elements of *list* together with *joinString* separating each adjacent pair of elements. The *joinString* argument defaults to a space character. Examples
--------

 Making a comma-separated list: 

```
set data {1 2 3 4 5}
**join** $data ", "
     **→ 1, 2, 3, 4, 5**
```
  Using **join** to flatten a list by a single level: 



```
set data {1 {2 3} 4 {5 {6 7} 8}}
**join** $data
     **→ 1 2 3 4 5 {6 7} 8**
```
 See also
--------

 **[list](list.htm)**, **[lappend](lappend.htm)**, **[split](split.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/join.htm>

pid
===

 Name
----

 pid — Retrieve process identifiers Synopsis
--------

 **pid** ?*fileId*?  
 Description
-----------

 If the *fileId* argument is given then it should normally refer to a process pipeline created with the **[open](open.htm)** command. In this case the **pid** command will return a list whose elements are the process identifiers of all the processes in the pipeline, in order. The list will be empty if *fileId* refers to an open file that is not a process pipeline. If no *fileId* argument is given then **pid** returns the process identifier of the current process. All process identifiers are returned as decimal strings. Example
-------

 Print process information about the processes in a pipeline using the SysV **ps** program before reading the output of that pipeline: 

```
set pipeline [open "| zcat somefile.gz | grep foobar | sort -u"]
# Print process information
exec ps -fp [**pid** $pipeline] >@stdout
# Print a separator and then the output of the pipeline
puts [string repeat - 70]
puts [read $pipeline]
close $pipeline
```
 See also
--------

 **[exec](exec.htm)**, **[open](open.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/pid.htm>

while
=====

 Name
----

 while — Execute script repeatedly as long as a condition is met Synopsis
--------

 **while** *test body*  
 Description
-----------

 The **while** command evaluates *test* as an expression (in the same way that **[expr](expr.htm)** evaluates its argument). The value of the expression must a proper boolean value; if it is a true value then *body* is executed by passing it to the Tcl interpreter. Once *body* has been executed then *test* is evaluated again, and the process repeats until eventually *test* evaluates to a false boolean value. **[Continue](continue.htm)** commands may be executed inside *body* to terminate the current iteration of the loop, and **[break](break.htm)** commands may be executed inside *body* to cause immediate termination of the **while** command. The **while** command always returns an empty string.  Note: *test* should almost always be enclosed in braces. If not, variable substitutions will be made before the **while** command starts executing, which means that variable changes made by the loop body will not be considered in the expression. This is likely to result in an infinite loop. If *test* is enclosed in braces, variable substitutions are delayed until the expression is evaluated (before each loop iteration), so changes in the variables will be visible. For an example, try the following script with and without the braces around **$x<10**: 



```
set x 0
**while** {$x<10} {
    puts "x is $x"
    incr x
}
```
 Example
-------

 Read lines from a channel until we get to the end of the stream, and print them out with a line-number prepended: 

```
set lineCount 0
**while** {[gets $chan line] >= 0} {
    puts "[incr lineCount]: $line"
}
```
 See also
--------

 **[break](break.htm)**, **[continue](continue.htm)**, **[for](for.htm)**, **[foreach](foreach.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/while.htm>

http
====

  
[NAME](http.htm#M2) http — Client-side implementation of the HTTP/1.1 protocol 
[SYNOPSIS](http.htm#M3) 
[DESCRIPTION](http.htm#M4) 
[COMMANDS](http.htm#M5)  
[**::http::config** ?*options*?](http.htm#M6)  
[**-accept** *mimetypes*](http.htm#M7) 
[**-proxyhost** *hostname*](http.htm#M8) 
[**-proxyport** *number*](http.htm#M9) 
[**-proxyfilter** *command*](http.htm#M10) 
[**-urlencoding** *encoding*](http.htm#M11) 
[**-useragent** *string*](http.htm#M12) 





 
[**::http::geturl** *url* ?*options*?](http.htm#M13)  
[**-binary** *boolean*](http.htm#M14) 
[**-blocksize** *size*](http.htm#M15) 
[**-channel** *name*](http.htm#M16) 
[**-command** *callback*](http.htm#M17) 
[**-handler** *callback*](http.htm#M18) 
[**-headers** *keyvaluelist*](http.htm#M19) 
[**-keepalive** *boolean*](http.htm#M20) 
[**-method** *type*](http.htm#M21) 
[**-myaddr** *address*](http.htm#M22) 
[**-progress** *callback*](http.htm#M23) 
[**-protocol** *version*](http.htm#M24) 
[**-query** *query*](http.htm#M25) 
[**-queryblocksize** *size*](http.htm#M26) 
[**-querychannel** *channelID*](http.htm#M27) 
[**-queryprogress** *callback*](http.htm#M28) 
[**-strict** *boolean*](http.htm#M29) 
[**-timeout** *milliseconds*](http.htm#M30) 
[**-type** *mime-type*](http.htm#M31) 
[**-validate** *boolean*](http.htm#M32) 


















 
[**::http::formatQuery** *key value* ?*key value* ...?](http.htm#M33) 
[**::http::reset** *token* ?*why*?](http.htm#M34) 
[**::http::wait** *token*](http.htm#M35) 
[**::http::data** *token*](http.htm#M36) 
[**::http::error** *token*](http.htm#M37) 
[**::http::status** *token*](http.htm#M38) 
[**::http::code** *token*](http.htm#M39) 
[**::http::ncode** *token*](http.htm#M40) 
[**::http::size** *token*](http.htm#M41) 
[**::http::meta** *token*](http.htm#M42) 
[**::http::cleanup** *token*](http.htm#M43) 
[**::http::register** *proto port command*](http.htm#M44) 
[**::http::unregister** *proto*](http.htm#M45) 














 
[ERRORS](http.htm#M46)  
[**ok**](http.htm#M47) 
[**eof**](http.htm#M48) 
[**error**](http.htm#M49) 


 
[STATE ARRAY](http.htm#M50)  
[**body**](http.htm#M51) 
[**charset**](http.htm#M52) 
[**coding**](http.htm#M53) 
[**currentsize**](http.htm#M54) 
[**error**](http.htm#M55) 
[**http**](http.htm#M56) 
[**meta**](http.htm#M57)  
[**Content-Type**](http.htm#M58) 
[**Content-Length**](http.htm#M59) 
[**Location**](http.htm#M60) 


 
[**posterror**](http.htm#M61) 
[**status**](http.htm#M62) 
[**totalsize**](http.htm#M63) 
[**type**](http.htm#M64) 
[**url**](http.htm#M65) 











 
[EXAMPLE](http.htm#M66) 
[SEE ALSO](http.htm#M67) 
[KEYWORDS](http.htm#M68) 








 Name
----

 http — Client-side implementation of the HTTP/1.1 protocol Synopsis
--------

 **package require http ?2.7?**  
 **::http::config ?***-option value* ...?  
 **::http::geturl** *url* ?*-option value* ...?  
 **::http::formatQuery** *key value* ?*key value* ...?  
 **::http::reset** *token* ?*why*?  
 **::http::wait** *token*  
 **::http::status** *token*  
 **::http::size** *token*  
 **::http::code** *token*  
 **::http::ncode** *token*  
 **::http::meta** *token*  
 **::http::data** *token*  
 **::http::error** *token*  
 **::http::cleanup** *token*  
 **::http::register** *proto port command*  
 **::http::unregister** *proto*  
 Description
-----------

 The **http** package provides the client side of the HTTP/1.1 protocol, as defined in RFC 2616. The package implements the GET, POST, and HEAD operations of HTTP/1.1. It allows configuration of a proxy host to get through firewalls. The package is compatible with the **Safesock** security policy, so it can be used by untrusted applets to do URL fetching from a restricted set of hosts. This package can be extended to support additional HTTP transport protocols, such as HTTPS, by providing a custom **[socket](socket.htm)** command, via **::http::register**.  The **::http::geturl** procedure does a HTTP transaction. Its *options*  determine whether a GET, POST, or HEAD transaction is performed. The return value of **::http::geturl** is a token for the transaction. The value is also the name of an array in the ::http namespace that contains state information about the transaction. The elements of this array are described in the **[STATE ARRAY](#M50)** section. 


 If the **-command** option is specified, then the HTTP operation is done in the background. **::http::geturl** returns immediately after generating the HTTP request and the callback is invoked when the transaction completes. For this to work, the Tcl event loop must be active. In Tk applications this is always true. For pure-Tcl applications, the caller can use **::http::wait** after calling **::http::geturl** to start the event loop. 


Commands
--------

  
**::http::config** ?*options*?
 The **::http::config** command is used to set and query the name of the proxy server and port, and the User-Agent name used in the HTTP requests. If no options are specified, then the current configuration is returned. If a single argument is specified, then it should be one of the flags described below. In this case the current value of that setting is returned. Otherwise, the options should be a set of flags and values that define the configuration: 
 
**-accept** *mimetypes*

 The Accept header of the request. The default is \*/\*, which means that all types of documents are accepted. Otherwise you can supply a comma-separated list of mime type patterns that you are willing to receive. For example, “image/gif, image/jpeg, text/\*”. 


**-proxyhost** *hostname*

 The name of the proxy host, if any. If this value is the empty string, the URL host is contacted directly. 


**-proxyport** *number*

 The proxy port number. 


**-proxyfilter** *command*

 The command is a callback that is made during **::http::geturl** to determine if a proxy is required for a given host. One argument, a host name, is added to *command* when it is invoked. If a proxy is required, the callback should return a two-element list containing the proxy server and proxy port. Otherwise the filter should return an empty list. The default filter returns the values of the **-proxyhost** and **-proxyport** settings if they are non-empty. 


**-urlencoding** *encoding*

 The *encoding* used for creating the x-url-encoded URLs with **::http::formatQuery**. The default is **utf-8**, as specified by RFC 2718. Prior to http 2.5 this was unspecified, and that behavior can be returned by specifying the empty string (**{}**), although *iso8859-1* is recommended to restore similar behavior but without the **::http::formatQuery** throwing an error processing non-latin-1 characters. 


**-useragent** *string*

 The value of the User-Agent header in the HTTP request. The default is “**Tcl http client package 2.7**”. 




**::http::geturl** *url* ?*options*?
 The **::http::geturl** command is the main procedure in the package. The **-query** option causes a POST operation and the **-validate** option causes a HEAD operation; otherwise, a GET operation is performed. The **::http::geturl** command returns a *token* value that can be used to get information about the transaction. See the **[STATE ARRAY](#M50)** and **[ERRORS](#M46)** section for details. The **::http::geturl** command blocks until the operation completes, unless the **-command** option specifies a callback that is invoked when the HTTP transaction completes. **::http::geturl** takes several options: 
 
**-binary** *boolean*

 Specifies whether to force interpreting the URL data as binary. Normally this is auto-detected (anything not beginning with a **[text](../tkcmd/text.htm)** content type or whose content encoding is **gzip** or **compress** is considered binary data). 


**-blocksize** *size*

 The block size used when reading the URL. At most *size* bytes are read at once. After each block, a call to the **-progress** callback is made (if that option is specified). 


**-channel** *name*

 Copy the URL contents to channel *name* instead of saving it in **state(body)**. 


**-command** *callback*

 Invoke *callback* after the HTTP transaction completes. This option causes **::http::geturl** to return immediately. The *callback* gets an additional argument that is the *token* returned from **::http::geturl**. This token is the name of an array that is described in the **[STATE ARRAY](#M50)** section. Here is a template for the callback: 

```
proc httpCallback {token} {
    upvar #0 $token state
    # Access state as a Tcl array
}
```



**-handler** *callback*

 Invoke *callback* whenever HTTP data is available; if present, nothing else will be done with the HTTP data. This procedure gets two additional arguments: the socket for the HTTP data and the *token* returned from **::http::geturl**. The token is the name of a global array that is described in the **[STATE ARRAY](#M50)** section. The procedure is expected to return the number of bytes read from the socket. Here is a template for the callback: 

```
proc httpHandlerCallback {socket token} {
    upvar #0 $token state
    # Access socket, and state as a Tcl array
    # For example...
    ...
    set data [read $socket 1000]
    set nbytes [string length $data]
    ...
    return $nbytes
}
```



**-headers** *keyvaluelist*

 This option is used to add headers not already specified by **::http::config** to the HTTP request. The *keyvaluelist* argument must be a list with an even number of elements that alternate between keys and values. The keys become header field names. Newlines are stripped from the values so the header cannot be corrupted. For example, if *keyvaluelist* is **Pragma no-cache** then the following header is included in the HTTP request: 

```
Pragma: no-cache
```



**-keepalive** *boolean*

 If true, attempt to keep the connection open for servicing multiple requests. Default is 0. 


**-method** *type*

 Force the HTTP request method to *type*. **::http::geturl** will auto-select GET, POST or HEAD based on other options, but this option enables choices like PUT and DELETE for webdav support. 


**-myaddr** *address*

 Pass an specific local address to the underlying **[socket](socket.htm)** call in case multiple interfaces are available. 


**-progress** *callback*

 The *callback* is made after each transfer of data from the URL. The callback gets three additional arguments: the *token* from **::http::geturl**, the expected total size of the contents from the **Content-Length** meta-data, and the current number of bytes transferred so far. The expected total size may be unknown, in which case zero is passed to the callback. Here is a template for the progress callback: 

```
proc httpProgress {token total current} {
    upvar #0 $token state
}
```



**-protocol** *version*

 Select the HTTP protocol version to use. This should be 1.0 or 1.1 (the default). Should only be necessary for servers that do not understand or otherwise complain about HTTP/1.1. 


**-query** *query*

 This flag causes **::http::geturl** to do a POST request that passes the *query* to the server. The *query* must be an x-url-encoding formatted query. The **::http::formatQuery** procedure can be used to do the formatting. 


**-queryblocksize** *size*

 The block size used when posting query data to the URL. At most *size* bytes are written at once. After each block, a call to the **-queryprogress** callback is made (if that option is specified). 


**-querychannel** *channelID*

 This flag causes **::http::geturl** to do a POST request that passes the data contained in *channelID* to the server. The data contained in *channelID* must be an x-url-encoding formatted query unless the **-type** option below is used. If a Content-Length header is not specified via the **-headers** options, **::http::geturl** attempts to determine the size of the post data in order to create that header. If it is unable to determine the size, it returns an error. 


**-queryprogress** *callback*

 The *callback* is made after each transfer of data to the URL (i.e. POST) and acts exactly like the **-progress** option (the callback format is the same). 


**-strict** *boolean*

 Whether to enforce RFC 3986 URL validation on the request. Default is 1. 


**-timeout** *milliseconds*

 If *milliseconds* is non-zero, then **::http::geturl** sets up a timeout to occur after the specified number of milliseconds. A timeout results in a call to **::http::reset** and to the **-command** callback, if specified. The return value of **::http::status** is **timeout** after a timeout has occurred. 


**-type** *mime-type*

 Use *mime-type* as the **Content-Type** value, instead of the default value (**application/x-www-form-urlencoded**) during a POST operation. 


**-validate** *boolean*

 If *boolean* is non-zero, then **::http::geturl** does an HTTP HEAD request. This request returns meta information about the URL, but the contents are not returned. The meta information is available in the **state(meta)**  variable after the transaction. See the **[STATE ARRAY](#M50)** section for details. 




**::http::formatQuery** *key value* ?*key value* ...?
 This procedure does x-url-encoding of query data. It takes an even number of arguments that are the keys and values of the query. It encodes the keys and values, and generates one string that has the proper & and = separators. The result is suitable for the **-query** value passed to **::http::geturl**. 


**::http::reset** *token* ?*why*?
 This command resets the HTTP transaction identified by *token*, if any. This sets the **state(status)** value to *why*, which defaults to **reset**, and then calls the registered **-command** callback. 


**::http::wait** *token*

 This is a convenience procedure that blocks and waits for the transaction to complete. This only works in trusted code because it uses **[vwait](vwait.htm)**. Also, it is not useful for the case where **::http::geturl** is called *without* the **-command** option because in this case the **::http::geturl** call does not return until the HTTP transaction is complete, and thus there is nothing to wait for. 


**::http::data** *token*

 This is a convenience procedure that returns the **body** element (i.e., the URL data) of the state array. 


**::http::error** *token*

 This is a convenience procedure that returns the **[error](error.htm)** element of the state array. 


**::http::status** *token*

 This is a convenience procedure that returns the **status** element of the state array. 


**::http::code** *token*

 This is a convenience procedure that returns the **http** element of the state array. 


**::http::ncode** *token*

 This is a convenience procedure that returns just the numeric return code (200, 404, etc.) from the **http** element of the state array. 


**::http::size** *token*

 This is a convenience procedure that returns the **currentsize** element of the state array, which represents the number of bytes received from the URL in the **::http::geturl** call. 


**::http::meta** *token*

 This is a convenience procedure that returns the **meta** element of the state array which contains the HTTP response headers. See below for an explanation of this element. 


**::http::cleanup** *token*

 This procedure cleans up the state associated with the connection identified by *token*. After this call, the procedures like **::http::data** cannot be used to get information about the operation. It is *strongly* recommended that you call this function after you are done with a given HTTP request. Not doing so will result in memory not being freed, and if your app calls **::http::geturl** enough times, the memory leak could cause a performance hit...or worse. 


**::http::register** *proto port command*

 This procedure allows one to provide custom HTTP transport types such as HTTPS, by registering a prefix, the default port, and the command to execute to create the Tcl **channel**. E.g.: 

```
package require http
package require tls

::http::register https 443 ::tls::socket

set token [::http::geturl https://my.secure.site/]
```



**::http::unregister** *proto*

 This procedure unregisters a protocol handler that was previously registered via **::http::register**. 

 Errors
------

 The **::http::geturl** procedure will raise errors in the following cases: invalid command line options, an invalid URL, a URL on a non-existent host, or a URL at a bad port on an existing host. These errors mean that it cannot even start the network transaction. It will also raise an error if it gets an I/O error while writing out the HTTP request header. For synchronous **::http::geturl** calls (where **-command** is not specified), it will raise an error if it gets an I/O error while reading the HTTP reply headers or data. Because **::http::geturl** does not return a token in these cases, it does all the required cleanup and there is no issue of your app having to call **::http::cleanup**.  For asynchronous **::http::geturl** calls, all of the above error situations apply, except that if there is any error while reading the HTTP reply headers or data, no exception is thrown. This is because after writing the HTTP headers, **::http::geturl** returns, and the rest of the HTTP transaction occurs in the background. The command callback can check if any error occurred during the read by calling **::http::status** to check the status and if its *error*, calling **::http::error** to get the error message. 


 Alternatively, if the main program flow reaches a point where it needs to know the result of the asynchronous HTTP request, it can call **::http::wait** and then check status and error, just as the callback does. 


 In any case, you must still call **::http::cleanup** to delete the state array when you are done. 


 There are other possible results of the HTTP transaction determined by examining the status from **::http::status**. These are described below. 


 **ok**
 If the HTTP transaction completes entirely, then status will be **ok**. However, you should still check the **::http::code** value to get the HTTP status. The **::http::ncode** procedure provides just the numeric error (e.g., 200, 404 or 500) while the **::http::code** procedure returns a value like “HTTP 404 File not found”. 

**eof**
 If the server closes the socket without replying, then no error is raised, but the status of the transaction will be **[eof](eof.htm)**. 

**error**
 The error message will also be stored in the **[error](error.htm)** status array element, accessible via **::http::error**. 

  Another error possibility is that **::http::geturl** is unable to write all the post query data to the server before the server responds and closes the socket. The error message is saved in the **posterror** status array element and then **::http::geturl** attempts to complete the transaction. If it can read the server's response it will end up with an **ok** status, otherwise it will have an **[eof](eof.htm)** status. 


State array
-----------

 The **::http::geturl** procedure returns a *token* that can be used to get to the state of the HTTP transaction in the form of a Tcl array. Use this construct to create an easy-to-use array variable: 

```
upvar #0 $token state
```
  Once the data associated with the URL is no longer needed, the state array should be unset to free up storage. The **::http::cleanup** procedure is provided for that purpose. The following elements of the array are supported: 


 **body**
 The contents of the URL. This will be empty if the **-channel** option has been specified. This value is returned by the **::http::data** command. 

**charset**
 The value of the charset attribute from the **Content-Type** meta-data value. If none was specified, this defaults to the RFC standard **iso8859-1**, or the value of **$::http::defaultCharset**. Incoming text data will be automatically converted from this charset to utf-8. 

**coding**
 A copy of the **Content-Encoding** meta-data value. 

**currentsize**
 The current number of bytes fetched from the URL. This value is returned by the **::http::size** command. 

**error**
 If defined, this is the error string seen when the HTTP transaction was aborted. 

**http**
 The HTTP status reply from the server. This value is returned by the **::http::code** command. The format of this value is: 

```
*HTTP/1.1 code string*
```
 The *code* is a three-digit number defined in the HTTP standard. A code of 200 is OK. Codes beginning with 4 or 5 indicate errors. Codes beginning with 3 are redirection errors. In this case the **Location** meta-data specifies a new URL that contains the requested information. 



**meta**
 The HTTP protocol returns meta-data that describes the URL contents. The **meta** element of the state array is a list of the keys and values of the meta-data. This is in a format useful for initializing an array that just contains the meta-data: 

```
array set meta $state(meta)
```
  Some of the meta-data keys are listed below, but the HTTP standard defines more, and servers are free to add their own. 


 **Content-Type**
 The type of the URL contents. Examples include **text/html**, **image/gif,** **application/postscript** and **application/x-tcl**. 

**Content-Length**
 The advertised size of the contents. The actual size obtained by **::http::geturl** is available as **state(currentsize)**. 

**Location**
 An alternate URL that contains the requested data. 



**posterror**
 The error, if any, that occurred while writing the post query data to the server. 

**status**
 Either **ok**, for successful completion, **reset** for user-reset, **timeout** if a timeout occurred before the transaction could complete, or **[error](error.htm)** for an error condition. During the transaction this value is the empty string. 

**totalsize**
 A copy of the **Content-Length** meta-data value. 

**type**
 A copy of the **Content-Type** meta-data value. 

**url**
 The requested URL. 

 Example
-------

 This example creates a procedure to copy a URL to a file while printing a progress meter, and prints the meta-data associated with the URL. 

```
proc httpcopy { url file {chunk 4096} } {
    set out [open $file w]
    set token [**::http::geturl** $url -channel $out \
            -progress httpCopyProgress -blocksize $chunk]
    close $out

    # This ends the line started by httpCopyProgress
    puts stderr ""

    upvar #0 $token state
    set max 0
    foreach {name value} $state(meta) {
        if {[string length $name] > $max} {
            set max [string length $name]
        }
        if {[regexp -nocase ^location$ $name]} {
            # Handle URL redirects
            puts stderr "Location:$value"
            return [httpcopy [string trim $value] $file $chunk]
        }
    }
    incr max
    foreach {name value} $state(meta) {
        puts [format "%-*s %s" $max $name: $value]
    }

    return $token
}
proc httpCopyProgress {args} {
    puts -nonewline stderr .
    flush stderr
}
```
 See also
--------

 **[safe](safe.htm)**, **[socket](socket.htm)**, **safesock** Copyright © 1995-1997 Sun Microsystems, Inc.  
 Copyright © 1998-2000 by Ajuba Solutions.  
 Copyright © 2004 ActiveState Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/http.htm>

Tcl
===

  
[NAME](tcl.htm#M2) Tcl — Tool Command Language 
[SYNOPSIS](tcl.htm#M3) 
[DESCRIPTION](tcl.htm#M4) 
[[1] **Commands.**](tcl.htm#M5) 
[[2] **Evaluation.**](tcl.htm#M6) 
[[3] **Words.**](tcl.htm#M7) 
[[4] **Double quotes.**](tcl.htm#M8) 
[[5] **Argument expansion.**](tcl.htm#M9) 
[[6] **Braces.**](tcl.htm#M10) 
[[7] **Command substitution.**](tcl.htm#M11) 
[[8] **Variable substitution.**](tcl.htm#M12)  
[**$***name*](tcl.htm#M13) 
[**$***name***(***index***)**](tcl.htm#M14) 
[**${***name***}**](tcl.htm#M15) 


 
[[9] **Backslash substitution.**](tcl.htm#M16)  
[\**a**](tcl.htm#M17) 
[\**b**](tcl.htm#M18) 
[\**f**](tcl.htm#M19) 
[\**n**](tcl.htm#M20) 
[\**r**](tcl.htm#M21) 
[\**t**](tcl.htm#M22) 
[\**v**](tcl.htm#M23) 
[\**<newline>***whiteSpace*](tcl.htm#M24) 
[\\](tcl.htm#M25) 
[\*ooo*](tcl.htm#M26) 
[\**x***hh*](tcl.htm#M27) 
[\**u***hhhh*](tcl.htm#M28) 
[\**U***hhhhhhhh*](tcl.htm#M29) 












 
[[10] **Comments.**](tcl.htm#M30) 
[[11] **Order of substitution.**](tcl.htm#M31) 
[[12] **Substitution and word boundaries.**](tcl.htm#M32) 











 
[KEYWORDS](tcl.htm#M33) 



 Name
----

 Tcl — Tool Command Language Synopsis
--------

 Summary of Tcl language syntax.  
 Description
-----------

 The following rules define the syntax and semantics of the Tcl language: 
[1] **Commands.**

 A Tcl script is a string containing one or more commands. Semi-colons and newlines are command separators unless quoted as described below. Close brackets are command terminators during command substitution (see below) unless quoted. 

[2] **Evaluation.**

 A command is evaluated in two steps. First, the Tcl interpreter breaks the command into *words* and performs substitutions as described below. These substitutions are performed in the same way for all commands. Secondly, the first word is used to locate a command procedure to carry out the command, then all of the words of the command are passed to the command procedure. The command procedure is free to interpret each of its words in any way it likes, such as an integer, variable name, list, or Tcl script. Different commands interpret their words differently. 

[3] **Words.**

 Words of a command are separated by white space (except for newlines, which are command separators). 

[4] **Double quotes.**

 If the first character of a word is double-quote (“"”) then the word is terminated by the next double-quote character. If semi-colons, close brackets, or white space characters (including newlines) appear between the quotes then they are treated as ordinary characters and included in the word. Command substitution, variable substitution, and backslash substitution are performed on the characters between the quotes as described below. The double-quotes are not retained as part of the word. 

[5] **Argument expansion.**

 If a word starts with the string “{\*}” followed by a non-whitespace character, then the leading “{\*}” is removed and the rest of the word is parsed and substituted as any other word. After substitution, the word is parsed as a list (without command or variable substitutions; backslash substitutions are performed as is normal for a list and individual internal words may be surrounded by either braces or double-quote characters), and its words are added to the command being substituted. For instance, “cmd a {\*}{b [c]} d {\*}{$e f {g h}}” is equivalent to “cmd a b {[c]} d {$e} f {g h}”. 

[6] **Braces.**

 If the first character of a word is an open brace (“{”) and rule [5] does not apply, then the word is terminated by the matching close brace (“}”). Braces nest within the word: for each additional open brace there must be an additional close brace (however, if an open brace or close brace within the word is quoted with a backslash then it is not counted in locating the matching close brace). No substitutions are performed on the characters between the braces except for backslash-newline substitutions described below, nor do semi-colons, newlines, close brackets, or white space receive any special interpretation. The word will consist of exactly the characters between the outer braces, not including the braces themselves. 

[7] **Command substitution.**

 If a word contains an open bracket (“[”) then Tcl performs *command substitution*. To do this it invokes the Tcl interpreter recursively to process the characters following the open bracket as a Tcl script. The script may contain any number of commands and must be terminated by a close bracket (“]”). The result of the script (i.e. the result of its last command) is substituted into the word in place of the brackets and all of the characters between them. There may be any number of command substitutions in a single word. Command substitution is not performed on words enclosed in braces. 

[8] **Variable substitution.**

 If a word contains a dollar-sign (“$”) followed by one of the forms described below, then Tcl performs *variable substitution*: the dollar-sign and the following characters are replaced in the word by the value of a variable. Variable substitution may take any of the following forms: 
 
**$***name*

 *Name* is the name of a scalar variable; the name is a sequence of one or more characters that are a letter, digit, underscore, or namespace separators (two or more colons). Letters and digits are *only* the standard ASCII ones (**0**–**9**, **A**–**Z** and **a**–**z**). 


**$***name***(***index***)**

 *Name* gives the name of an array variable and *index* gives the name of an element within that array. *Name* must contain only letters, digits, underscores, and namespace separators, and may be an empty string. Letters and digits are *only* the standard ASCII ones (**0**–**9**, **A**–**Z** and **a**–**z**). Command substitutions, variable substitutions, and backslash substitutions are performed on the characters of *index*. 


**${***name***}**

 *Name* is the name of a scalar variable or array element. It may contain any characters whatsoever except for close braces. It indicates an array element if *name* is in the form “*arrayName***(***index***)**” where *arrayName* does not contain any open parenthesis characters, “**(**”, or close brace characters, “**}**”, and *index* can be any sequence of characters except for close brace characters. No further substitutions are performed during the parsing of *name*. 

   There may be any number of variable substitutions in a single word. Variable substitution is not performed on words enclosed in braces. 


 Note that variables may contain character sequences other than those listed above, but in that case other mechanisms must be used to access them (e.g., via the **[set](set.htm)** command's single-argument form). 




[9] **Backslash substitution.**

 If a backslash (“\”) appears within a word then *backslash substitution* occurs. In all cases but those described below the backslash is dropped and the following character is treated as an ordinary character and included in the word. This allows characters such as double quotes, close brackets, and dollar signs to be included in words without triggering special processing. The following table lists the backslash sequences that are handled specially, along with the value that replaces each sequence. 
 \**a**

 Audible alert (bell) (Unicode U+000007). 

\**b**

 Backspace (Unicode U+000008). 

\**f**

 Form feed (Unicode U+00000C). 

\**n**

 Newline (Unicode U+00000A). 

\**r**

 Carriage-return (Unicode U+00000D). 

\**t**

 Tab (Unicode U+000009). 

\**v**

 Vertical tab (Unicode U+00000B). 

\**<newline>***whiteSpace*

 A single space character replaces the backslash, newline, and all spaces and tabs after the newline. This backslash sequence is unique in that it is replaced in a separate pre-pass before the command is actually parsed. This means that it will be replaced even when it occurs between braces, and the resulting space will be treated as a word separator if it is not in braces or quotes. 

\\
 Backslash (“\”). 

\*ooo*

 The digits *ooo* (one, two, or three of them) give a eight-bit octal value for the Unicode character that will be inserted, in the range *000*–*377* (i.e., the range U+000000–U+0000FF). The parser will stop just before this range overflows, or when the maximum of three digits is reached. The upper bits of the Unicode character will be 0. 

\**x***hh*

 The hexadecimal digits *hh* (one or two of them) give an eight-bit hexadecimal value for the Unicode character that will be inserted. The upper bits of the Unicode character will be 0 (i.e., the character will be in the range U+000000–U+0000FF). 

\**u***hhhh*

 The hexadecimal digits *hhhh* (one, two, three, or four of them) give a sixteen-bit hexadecimal value for the Unicode character that will be inserted. The upper bits of the Unicode character will be 0 (i.e., the character will be in the range U+000000–U+00FFFF). 

\**U***hhhhhhhh*

 The hexadecimal digits *hhhhhhhh* (one up to eight of them) give a twenty-one-bit hexadecimal value for the Unicode character that will be inserted, in the range U+000000–U+10FFFF. The parser will stop just before this range overflows, or when the maximum of eight digits is reached. The upper bits of the Unicode character will be 0.  The range U+010000–U+10FFFD is reserved for the future. 




Backslash substitution is not performed on words enclosed in braces, except for backslash-newline as described above.



[10] **Comments.**

 If a hash character (“#”) appears at a point where Tcl is expecting the first character of the first word of a command, then the hash character and the characters that follow it, up through the next newline, are treated as a comment and ignored. The comment character only has significance when it appears at the beginning of a command. 

[11] **Order of substitution.**

 Each character is processed exactly once by the Tcl interpreter as part of creating the words of a command. For example, if variable substitution occurs then no further substitutions are performed on the value of the variable; the value is inserted into the word verbatim. If command substitution occurs then the nested command is processed entirely by the recursive call to the Tcl interpreter; no substitutions are performed before making the recursive call and no additional substitutions are performed on the result of the nested script.  Substitutions take place from left to right, and each substitution is evaluated completely before attempting to evaluate the next. Thus, a sequence like 



```
set y [set x 0][incr x][incr x]
```
 will always set the variable *y* to the value, *012*. 



[12] **Substitution and word boundaries.**

 Substitutions do not affect the word boundaries of a command, except for argument expansion as specified in rule [5]. For example, during variable substitution the entire value of the variable becomes part of a single word, even if the variable's value contains spaces. 

 Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/Tcl.htm>

package
=======

  
[NAME](package.htm#M2) package — Facilities for package loading and version control 
[SYNOPSIS](package.htm#M3) 
[DESCRIPTION](package.htm#M4)  
[**package forget** ?*package package ...*?](package.htm#M5) 
[**package ifneeded** *package version* ?*script*?](package.htm#M6) 
[**package names**](package.htm#M7) 
[**package present** ?**-exact**? *package* ?*requirement...*?](package.htm#M8) 
[**package provide** *package* ?*version*?](package.htm#M9) 
[**package require** *package* ?*requirement...*?](package.htm#M10) 
[**package require -exact** *package version*](package.htm#M11) 
[**package unknown** ?*command*?](package.htm#M12) 
[**package vcompare** *version1 version2*](package.htm#M13) 
[**package versions** *package*](package.htm#M14) 
[**package vsatisfies** *version requirement...*](package.htm#M15)  
[min](package.htm#M16) 
[min-](package.htm#M17) 
[min-max](package.htm#M18) 


 
[**package prefer** ?**latest**|**stable**?](package.htm#M19) 











 
[VERSION NUMBERS](package.htm#M20) 
[PACKAGE INDICES](package.htm#M21) 
[EXAMPLES](package.htm#M22) 
[SEE ALSO](package.htm#M23) 
[KEYWORDS](package.htm#M24) 







 Name
----

 package — Facilities for package loading and version control Synopsis
--------

 **package forget** ?*package package ...*?  
 **package ifneeded** *package version* ?*script*?  
 **package names**  
 **package present** *package* ?*requirement...*?  
 **package present -exact** *package version*  
 **package provide** *package* ?*version*?  
 **package require** *package* ?*requirement...*?  
 **package require -exact** *package version*  
 **package unknown** ?*command*?  
 **package vcompare** *version1 version2*  
 **package versions** *package*  
 **package vsatisfies** *version requirement...*  
 **package prefer** ?**latest**|**stable**?  
 Description
-----------

 This command keeps a simple database of the packages available for use by the current interpreter and how to load them into the interpreter. It supports multiple versions of each package and arranges for the correct version of a package to be loaded based on what is needed by the application. This command also detects and reports version clashes. Typically, only the **package require** and **package provide** commands are invoked in normal Tcl scripts; the other commands are used primarily by system scripts that maintain the package database.  The behavior of the **package** command is determined by its first argument. The following forms are permitted: 


 
**package forget** ?*package package ...*?
 Removes all information about each specified package from this interpreter, including information provided by both **package ifneeded** and **package provide**. 


**package ifneeded** *package version* ?*script*?
 This command typically appears only in system configuration scripts to set up the package database. It indicates that a particular version of a particular package is available if needed, and that the package can be added to the interpreter by executing *script*. The script is saved in a database for use by subsequent **package require** commands; typically, *script* sets up auto-loading for the commands in the package (or calls **[load](load.htm)** and/or **[source](source.htm)** directly), then invokes **package provide** to indicate that the package is present. There may be information in the database for several different versions of a single package. If the database already contains information for *package* and *version*, the new *script* replaces the existing one. If the *script* argument is omitted, the current script for version *version* of package *package* is returned, or an empty string if no **package ifneeded** command has been invoked for this *package* and *version*. 

**package names**
 Returns a list of the names of all packages in the interpreter for which a version has been provided (via **package provide**) or for which a **package ifneeded** script is available. The order of elements in the list is arbitrary. 


**package present** ?**-exact**? *package* ?*requirement...*?
 This command is equivalent to **package require** except that it does not try and load the package if it is not already loaded. 


**package provide** *package* ?*version*?
 This command is invoked to indicate that version *version* of package *package* is now present in the interpreter. It is typically invoked once as part of an **ifneeded** script, and again by the package itself when it is finally loaded. An error occurs if a different version of *package* has been provided by a previous **package provide** command. If the *version* argument is omitted, then the command returns the version number that is currently provided, or an empty string if no **package provide** command has been invoked for *package* in this interpreter. 


**package require** *package* ?*requirement...*?
 This command is typically invoked by Tcl code that wishes to use a particular version of a particular package. The arguments indicate which package is wanted, and the command ensures that a suitable version of the package is loaded into the interpreter. If the command succeeds, it returns the version number that is loaded; otherwise it generates an error.  A suitable version of the package is any version which satisfies at least one of the requirements, per the rules of **package vsatisfies**. If multiple versions are suitable the implementation with the highest version is chosen. This last part is additionally influenced by the selection mode set with **package prefer**. 


 In the “stable” selection mode the command will select the highest stable version satisfying the requirements, if any. If no stable version satisfies the requirements, the highest unstable version satisfying the requirements will be selected. In the “latest” selection mode the command will accept the highest version satisfying all the requirements, regardless of its stableness. 


If a version of *package* has already been provided (by invoking the **package provide** command), then its version number must satisfy the *requirement*s and the command returns immediately. Otherwise, the command searches the database of information provided by previous **package ifneeded** commands to see if an acceptable version of the package is available. If so, the script for the highest acceptable version number is evaluated in the global namespace; it must do whatever is necessary to load the package, including calling **package provide** for the package. If the **package ifneeded** database does not contain an acceptable version of the package and a **package unknown** command has been specified for the interpreter then that command is evaluated in the global namespace; when it completes, Tcl checks again to see if the package is now provided or if there is a **package ifneeded** script for it. If all of these steps fail to provide an acceptable version of the package, then the command returns an error. 




**package require -exact** *package version*

 This form of the command is used when only the given *version* of *package* is acceptable to the caller. This command is equivalent to **package require** *package version*-*version*. 


**package unknown** ?*command*?
 This command supplies a “last resort” command to invoke during **package require** if no suitable version of a package can be found in the **package ifneeded** database. If the *command* argument is supplied, it contains the first part of a command; when the command is invoked during a **package require** command, Tcl appends one or more additional arguments giving the desired package name and requirements. For example, if *command* is **foo bar** and later the command **package require test 2.4** is invoked, then Tcl will execute the command **foo bar test 2.4** to load the package. If no requirements are supplied to the **package require** command, then only the name will be added to invoked command. If the **package unknown** command is invoked without a *command* argument, then the current **package unknown** script is returned, or an empty string if there is none. If *command* is specified as an empty string, then the current **package unknown** script is removed, if there is one. 


**package vcompare** *version1 version2*

 Compares the two version numbers given by *version1* and *version2*. Returns -1 if *version1* is an earlier version than *version2*, 0 if they are equal, and 1 if *version1* is later than *version2*. 


**package versions** *package*

 Returns a list of all the version numbers of *package* for which information has been provided by **package ifneeded** commands. 


**package vsatisfies** *version requirement...*

 Returns 1 if the *version* satisfies at least one of the given requirements, and 0 otherwise. Each *requirement* is allowed to have any of the forms: 
 min
 This form is called “min-bounded”. 

min-
 This form is called “min-unbound”. 

min-max
 This form is called “bounded”. 

  where “min” and “max” are valid version numbers. The legacy syntax is a special case of the extended syntax, keeping backward compatibility. Regarding satisfaction the rules are: 


1. The *version* has to pass at least one of the listed *requirement*s to be satisfactory.
2. A version satisfies a “bounded” requirement when
	1. For *min* equal to the *max* if, and only if the *version* is equal to the *min*.
	2. Otherwise if, and only if the *version* is greater than or equal to the *min*, and less than the *max*, where both *min* and *max* have been padded internally with “a0”. Note that while the comparison to *min* is inclusive, the comparison to *max* is exclusive.
3. A “min-bounded” requirement is a “bounded” requirement in disguise, with the *max* part implicitly specified as the next higher major version number of the *min* part. A version satisfies it per the rules above.
4. A *version* satisfies a “min-unbound” requirement if, and only if it is greater than or equal to the *min*, where the *min* has been padded internally with “a0”. There is no constraint to a maximum.




**package prefer** ?**latest**|**stable**?
 With no arguments, the commands returns either “latest” or “stable”, whichever describes the current mode of selection logic used by **package require**.  When passed the argument “latest”, it sets the selection logic mode to “latest”. 


 When passed the argument “stable”, if the mode is already “stable”, that value is kept. If the mode is already “latest”, then the attempt to set it back to “stable” is ineffective and the mode value remains “latest”. 


 When passed any other value as an argument, raise an invalid argument error. 


When an interpreter is created, its initial selection mode value is set to “stable” unless the environment variable **TCL\_PKG\_PREFER\_LATEST** is set. If that environment variable is defined (with any value) then the initial (and permanent) selection mode value is set to “latest”. 



 Version numbers
---------------

 Version numbers consist of one or more decimal numbers separated by dots, such as 2 or 1.162 or 3.1.13.1. The first number is called the major version number. Larger numbers correspond to later versions of a package, with leftmost numbers having greater significance. For example, version 2.1 is later than 1.3 and version 3.4.6 is later than 3.3.5. Missing fields are equivalent to zeroes: version 1.3 is the same as version 1.3.0 and 1.3.0.0, so it is earlier than 1.3.1 or 1.3.0.2. In addition, the letters “a” (alpha) and/or “b” (beta) may appear exactly once to replace a dot for separation. These letters semantically add a negative specifier into the version, where “a” is -2, and “b” is -1. Each may be specified only once, and “a” or “b” are mutually exclusive in a specifier. Thus 1.3a1 becomes (semantically) 1.3.-2.1, 1.3b1 is 1.3.-1.1. Negative numbers are not directly allowed in version specifiers. A version number not containing the letters “a” or “b” as specified above is called a **stable** version, whereas presence of the letters causes the version to be called is **unstable**. A later version number is assumed to be upwards compatible with an earlier version number as long as both versions have the same major version number. For example, Tcl scripts written for version 2.3 of a package should work unchanged under versions 2.3.2, 2.4, and 2.5.1. Changes in the major version number signify incompatible changes: if code is written to use version 2.1 of a package, it is not guaranteed to work unmodified with either version 1.7.3 or version 3.1. Package indices
---------------

 The recommended way to use packages in Tcl is to invoke **package require** and **package provide** commands in scripts, and use the procedure **pkg\_mkIndex** to create package index files. Once you have done this, packages will be loaded automatically in response to **package require** commands. See the documentation for **pkg\_mkIndex** for details. Examples
--------

 To state that a Tcl script requires the Tk and http packages, put this at the top of the script: 

```
**package require** Tk
**package require** http
```
  To test to see if the Snack package is available and load if it is (often useful for optional enhancements to programs where the loss of the functionality is not critical) do this: 



```
if {[catch {**package require** Snack}]} {
    # Error thrown - package not found.
    # Set up a dummy interface to work around the absence
} else {
    # We have the package, configure the app to use it
}
```
 See also
--------

 **[msgcat](msgcat.htm)**, **[packagens](packagens.htm)**, **pkgMkIndex** Copyright © 1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/package.htm>

vwait
=====

 Name
----

 vwait — Process events until a variable is written Synopsis
--------

 **vwait** *varName*  
 Description
-----------

 This command enters the Tcl event loop to process events, blocking the application if no events are ready. It continues processing events until some event handler sets the value of the global variable *varName*. Once *varName* has been set, the **vwait** command will return as soon as the event handler that modified *varName* completes. The *varName* argument is always interpreted as a variable name with respect to the global namespace, but can refer to any namespace's variables if the fully-qualified name is given.  In some cases the **vwait** command may not return immediately after *varName* is set. This happens if the event handler that sets *varName* does not complete immediately. For example, if an event handler sets *varName* and then itself calls **vwait** to wait for a different variable, then it may not return for a long time. During this time the top-level **vwait** is blocked waiting for the event handler to complete, so it cannot return either. (See the **[NESTED VWAITS BY EXAMPLE](#M6)** below.) 


 To be clear, *multiple* **vwait** *calls will nest and will not happen in parallel*. The outermost call to **vwait** will not return until all the inner ones do. It is recommended that code should never nest **vwait** calls (by avoiding putting them in event callbacks) but when that is not possible, care should be taken to add interlock variables to the code to prevent all reentrant calls to **vwait** that are not *strictly* necessary. Be aware that the synchronous modes of operation of some Tcl packages (e.g., **[http](http.htm)**) use **vwait** internally; if using the event loop, it is best to use the asynchronous callback-based modes of operation of those packages where available. 


Examples
--------

 Run the event-loop continually until some event calls **[exit](exit.htm)**. (You can use any variable not mentioned elsewhere, but the name *forever* reminds you at a glance of the intent.) 

```
**vwait** forever
```
  Wait five seconds for a connection to a server socket, otherwise close the socket and continue running the script: 



```
# Initialise the state
after 5000 set state timeout
set server [socket -server accept 12345]
proc accept {args} {
    global state connectionInfo
    set state accepted
    set connectionInfo $args
}

# Wait for something to happen
**vwait** state

# Clean up events that could have happened
close $server
after cancel set state timeout

# Do something based on how the vwait finished...
switch $state {
    timeout {
        puts "no connection on port 12345"
    }
    accepted {
       puts "connection: $connectionInfo"
       puts [lindex $connectionInfo 0] "Hello there!"
    }
}
```
  A command that will wait for some time delay by waiting for a namespace variable to be set. Includes an interlock to prevent nested waits. 



```
namespace eval example {
    variable v done
    proc wait {delay} {
        variable v
        if {$v ne "waiting"} {
            set v waiting
            after $delay [namespace code {set v done}]
            **vwait** [namespace which -variable v]
        }
        return $v
    }
}
```
  When running inside a **[coroutine](coroutine.htm)**, an alternative to using **vwait** is to **[yield](coroutine.htm)** to an outer event loop and to get recommenced when the variable is set, or at an idle moment after that. 



```
coroutine task apply {{} {
    # simulate [after 1000]
    after 1000 [info coroutine]
    yield

    # schedule the setting of a global variable, as normal
    after 2000 {set var 1}

    # simulate [**vwait** var]
    proc updatedVar {task args} {
        after idle $task
        trace remove variable ::var write "updatedVar $task"
    }
    trace add variable ::var write "updatedVar [info coroutine]"
    yield
}}
```
 ### Nested vwaits by example

 This example demonstrates what can happen when the **vwait** command is nested. The script will never finish because the waiting for the *a* variable never finishes; that **vwait** command is still waiting for a script scheduled with **[after](after.htm)** to complete, which just happens to be running an inner **vwait** (for *b*) even though the event that the outer **vwait** was waiting for (the setting of *a*) has occurred. 

```
after 500 {
    puts "waiting for b"
    **vwait** b
    puts "b was set"
}
after 1000 {
    puts "setting a"
    set a 10
}
puts "waiting for a"
**vwait** a
puts "a was set"
puts "setting b"
set b 42
```
  If you run the above code, you get this output: 



```
waiting for a
waiting for b
setting a
```
  The script will never print “a was set” until after it has printed “b was set” because of the nesting of **vwait** commands, and yet *b* will not be set until after the outer **vwait** returns, so the script has deadlocked. The only ways to avoid this are to either structure the overall program in continuation-passing style or to use **[coroutine](coroutine.htm)** to make the continuations implicit. The first of these options would be written as: 



```
after 500 {
    puts "waiting for b"
    trace add variable b write {apply {args {
        global a b
        trace remove variable ::b write \
                [lrange [info level 0] 0 1]
        puts "b was set"
        set ::done ok
    }}}
}
after 1000 {
    puts "setting a"
    set a 10
}
puts "waiting for a"
trace add variable a write {apply {args {
    global a b
    trace remove variable a write [lrange [info level 0] 0 1]
    puts "a was set"
    puts "setting b"
    set b 42
}}}
**vwait** done
```
  The second option, with **[coroutine](coroutine.htm)** and some helper procedures, is done like this: 



```
# A coroutine-based wait-for-variable command
proc waitvar globalVar {
    trace add variable ::$globalVar write \
            [list apply {{v c args} {
        trace remove variable $v write \
                [lrange [info level 0] 0 3]
        after 0 $c
    }} ::$globalVar [info coroutine]]
    yield
}
# A coroutine-based wait-for-some-time command
proc waittime ms {
    after $ms [info coroutine]
    yield
}

coroutine task-1 eval {
    puts "waiting for a"
    waitvar a
    puts "a was set"
    puts "setting b"
    set b 42
}
coroutine task-2 eval {
    waittime 500
    puts "waiting for b"
    waitvar b
    puts "b was set"
    set done ok
}
coroutine task-3 eval {
    waittime 1000
    puts "setting a"
    set a 10
}
**vwait** done
```
 See also
--------

 **[global](global.htm)**, **[update](update.htm)** Copyright © 1995-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/vwait.htm>

coroutine
=========

 Name
----

 coroutine, yield, yieldto — Create and produce values from coroutines Synopsis
--------

 **coroutine** *name command* ?*arg...*?  
 **yield** ?*value*?  
 **yieldto** *command* ?*arg...*?  
 *name* ?*value...*?  
 Description
-----------

 The **coroutine** command creates a new coroutine context (with associated command) named *name* and executes that context by calling *command*, passing in the other remaining arguments without further interpretation. Once *command* returns normally or with an exception (e.g., an error) the coroutine context *name* is deleted.  Within the context, values may be generated as results by using the **yield** command; if no *value* is supplied, the empty string is used. When that is called, the context will suspend execution and the **coroutine** command will return the argument to **yield**. The execution of the context can then be resumed by calling the context command, optionally passing in the *single* value to use as the result of the **yield** call that caused the context to be suspended. If the coroutine context never yields and instead returns conventionally, the result of the **coroutine** command will be the result of the evaluation of the context. 


 The coroutine may also suspend its execution by use of the **yieldto** command, which instead of returning, cedes execution to some command called *command* (resolved in the context of the coroutine) and to which *any number* of arguments may be passed. Since every coroutine has a context command, **yieldto** can be used to transfer control directly from one coroutine to another (this is only advisable if the two coroutines are expecting this to happen) but *any* command may be the target. If a coroutine is suspended by this mechanism, the coroutine processing can be resumed by calling the context command optionally passing in an arbitrary number of arguments. The return value of the **yieldto** call will be the list of arguments passed to the context command; it is up to the caller to decide what to do with those values. 


 The recommended way of writing a version of **yield** that allows resumption with multiple arguments is by using **yieldto** and the **[return](return.htm)** command, like this: 



```
proc yieldm {value} {
    **yieldto** return -level 0 $value
}
```
  The coroutine can also be deleted by destroying the command *name*, and the name of the current coroutine can be retrieved by using **[info coroutine](info.htm)**. If there are deletion traces on variables in the coroutine's implementation, they will fire at the point when the coroutine is explicitly deleted (or, naturally, if the command returns conventionally). 


 At the point when *command* is called, the current namespace will be the global namespace and there will be no stack frames above it (in the sense of **[upvar](upvar.htm)** and **[uplevel](uplevel.htm)**). However, which command to call will be determined in the namespace that the **coroutine** command was called from. 


Examples
--------

 This example shows a coroutine that will produce an infinite sequence of even values, and a loop that consumes the first ten of them. 

```
proc allNumbers {} {
    **yield**
    set i 0
    while 1 {
        **yield** $i
        incr i 2
    }
}
**coroutine** nextNumber allNumbers
for {set i 0} {$i < 10} {incr i} {
    puts "received [*nextNumber*]"
}
rename nextNumber {}
```
  In this example, the coroutine acts to add up the arguments passed to it. 



```
**coroutine** accumulator apply {{} {
    set x 0
    while 1 {
        incr x [**yield** $x]
    }
}}
for {set i 0} {$i < 10} {incr i} {
    puts "$i -> [*accumulator* $i]"
}
```
  This example demonstrates the use of coroutines to implement the classic Sieve of Eratosthenes algorithm for finding prime numbers. Note the creation of coroutines inside a coroutine. 



```
proc filterByFactor {source n} {
    **yield** [info coroutine]
    while 1 {
        set x [*$source*]
        if {$x % $n} {
            **yield** $x
        }
    }
}
**coroutine** allNumbers apply {{} {while 1 {**yield** [incr x]}}}
**coroutine** eratosthenes apply {c {
    **yield**
    while 1 {
        set n [*$c*]
        **yield** $n
        set c [**coroutine** prime$n filterByFactor $c $n]
    }
}} allNumbers
for {set i 1} {$i <= 20} {incr i} {
    puts "prime#$i = [*eratosthenes*]"
}
```
  This example shows how a value can be passed around a group of three coroutines that yield to each other: 



```
proc juggler {name target {value ""}} {
    if {$value eq ""} {
        set value [**yield** [info coroutine]]
    }
    while {$value ne ""} {
        puts "$name : $value"
        set value [string range $value 0 end-1]
        lassign [**yieldto** $target $value] value
    }
}
**coroutine** j1 juggler Larry [
    **coroutine** j2 juggler Curly [
        **coroutine** j3 juggler Moe j1]] "Nyuck!Nyuck!Nyuck!"
```
 ### Detailed semantics

 This example demonstrates that coroutines start from the global namespace, and that *command* resolution happens before the coroutine stack is created. 

```
proc report {where level} {
    # Where was the caller called from?
    set ns [uplevel 2 {namespace current}]
    **yield** "made $where $level context=$ns name=[info coroutine]"
}
proc example {} {
    report outer [info level]
}
namespace eval demo {
    proc example {} {
        report inner [info level]
    }
    proc makeExample {} {
        puts "making from [info level]"
        puts [**coroutine** coroEg example]
    }
    makeExample
}
```
  Which produces the output below. In particular, we can see that stack manipulation has occurred (comparing the levels from the first and second line) and that the parent level in the coroutine is the global namespace. We can also see that coroutine names are local to the current namespace if not qualified, and that coroutines may yield at depth (e.g., in called procedures). 



```
making from 2
made inner 1 context=:: name=::demo::coroEg
```
 See also
--------

 **[apply](apply.htm)**, **[info](info.htm)**, **[proc](proc.htm)**, **[return](return.htm)** Copyright © 2009 Donal K. Fellows. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/coroutine.htm>

lappend
=======

 Name
----

 lappend — Append list elements onto a variable Synopsis
--------

 **lappend** *varName* ?*value value value ...*?  
 Description
-----------

 This command treats the variable given by *varName* as a list and appends each of the *value* arguments to that list as a separate element, with spaces between elements. If *varName* does not exist, it is created as a list with elements given by the *value* arguments. **Lappend** is similar to **[append](append.htm)** except that the *value*s are appended as list elements rather than raw text. This command provides a relatively efficient way to build up large lists. For example, “**lappend a $b**” is much more efficient than “**set a [concat $a [list $b]]**” when **$a** is long. Example
-------

 Using **lappend** to build up a list of numbers. 

```
% set var 1
1
% **lappend** var 2
1 2
% **lappend** var 3 4 5
1 2 3 4 5
```
 See also
--------

 **[list](list.htm)**, **[lindex](lindex.htm)**, **[linsert](linsert.htm)**, **[llength](llength.htm)**, **[lset](lset.htm)**, **[lsort](lsort.htm)**, **[lrange](lrange.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2001 Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/lappend.htm>

lassign
=======

 Name
----

 lassign — Assign list elements to variables Synopsis
--------

 **lassign** *list* ?*varName ...*?  
 Description
-----------

 This command treats the value *list* as a list and assigns successive elements from that list to the variables given by the *varName* arguments in order. If there are more variable names than list elements, the remaining variables are set to the empty string. If there are more list elements than variables, a list of unassigned elements is returned. Examples
--------

 An illustration of how multiple assignment works, and what happens when there are either too few or too many elements. 

```
**lassign** {a b c} x y z       ;# Empty return
puts $x                     ;# Prints "a"
puts $y                     ;# Prints "b"
puts $z                     ;# Prints "c"

**lassign** {d e} x y z         ;# Empty return
puts $x                     ;# Prints "d"
puts $y                     ;# Prints "e"
puts $z                     ;# Prints ""

**lassign** {f g h i} x y       ;# Returns "h i"
puts $x                     ;# Prints "f"
puts $y                     ;# Prints "g"
```
  The **lassign** command has other uses. It can be used to create the analogue of the “shift” command in many shell languages like this: 



```
set ::argv [**lassign** $::argv argumentToReadOff]
```
 See also
--------

 **[lindex](lindex.htm)**, **[list](list.htm)**, **[lrange](lrange.htm)**, **[lset](lset.htm)**, **[set](set.htm)** Copyright © 1992-1999 Karl Lehenbauer & Mark Diekhans  
 Copyright © 2004 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/lassign.htm>

linsert
=======

 Name
----

 linsert — Insert elements into a list Synopsis
--------

 **linsert** *list index* ?*element element ...*?  
 Description
-----------

 This command produces a new list from *list* by inserting all of the *element* arguments just before the *index*'th element of *list*. Each *element* argument will become a separate element of the new list. If *index* is less than or equal to zero, then the new elements are inserted at the beginning of the list, and if *index* is greater or equal to the length of *list*, it is as if it was **end**. As with **[string index](string.htm)**, the *index* value supports both simple index arithmetic and end-relative indexing.  Subject to the restrictions that indices must refer to locations inside the list and that the *element*s will always be inserted in order, insertions are done so that when *index* is start-relative, the first *element* will be at that index in the resulting list, and when *index* is end-relative, the last *element* will be at that index in the resulting list. 


Example
-------

 Putting some values into a list, first indexing from the start and then indexing from the end, and then chaining them together: 

```
set oldList {the fox jumps over the dog}
set midList [**linsert** $oldList 1 quick]
set newList [**linsert** $midList end-1 lazy]
# The old lists still exist though...
set newerList [**linsert** [**linsert** $oldList end-1 quick] 1 lazy]
```
 See also
--------

 **[list](list.htm)**, **[lappend](lappend.htm)**, **[lindex](lindex.htm)**, **[llength](llength.htm)**, **[lsearch](lsearch.htm)**, **[lset](lset.htm)**, **[lsort](lsort.htm)**, **[lrange](lrange.htm)**, **[lreplace](lreplace.htm)**, **[string](string.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2001 Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/linsert.htm>

open
====

  
[NAME](open.htm#M2) open — Open a file-based or command pipeline channel 
[SYNOPSIS](open.htm#M3) 
[DESCRIPTION](open.htm#M4)  
[**r**](open.htm#M5) 
[**r+**](open.htm#M6) 
[**w**](open.htm#M7) 
[**w+**](open.htm#M8) 
[**a**](open.htm#M9) 
[**a+**](open.htm#M10) 





  
[**RDONLY**](open.htm#M11) 
[**WRONLY**](open.htm#M12) 
[**RDWR**](open.htm#M13) 
[**APPEND**](open.htm#M14) 
[**BINARY**](open.htm#M15) 
[**CREAT**](open.htm#M16) 
[**EXCL**](open.htm#M17) 
[**NOCTTY**](open.htm#M18) 
[**NONBLOCK**](open.htm#M19) 
[**TRUNC**](open.htm#M20) 









 
[COMMAND PIPELINES](open.htm#M21) 
[SERIAL COMMUNICATIONS](open.htm#M22)  
[**-mode** *baud***,***parity***,***data***,***stop*](open.htm#M23) 
[**-handshake** *type*](open.htm#M24) 
[**-queue**](open.htm#M25) 
[**-timeout** *msec*](open.htm#M26) 
[**-ttycontrol** *{signal boolean signal boolean ...}*](open.htm#M27) 
[**-ttystatus**](open.htm#M28) 
[**-xchar** *{xonChar xoffChar}*](open.htm#M29) 
[**-pollinterval** *msec*](open.htm#M30) 
[**-sysbuffer** *inSize*](open.htm#M31) 
[**-sysbuffer** *{inSize outSize}*](open.htm#M32) 
[**-lasterror**](open.htm#M33) 










 
[SERIAL PORT SIGNALS](open.htm#M34)  
[**TXD**(output)](open.htm#M35) 
[**RXD**(input)](open.htm#M36) 
[**RTS**(output)](open.htm#M37) 
[**CTS**(input)](open.htm#M38) 
[**DTR**(output)](open.htm#M39) 
[**DSR**(input)](open.htm#M40) 
[**DCD**(input)](open.htm#M41) 
[**RI**(input)](open.htm#M42) 
[**BREAK**](open.htm#M43) 








 
[ERROR CODES (Windows only)](open.htm#M44)  
[**RXOVER**](open.htm#M45) 
[**TXFULL**](open.htm#M46) 
[**OVERRUN**](open.htm#M47) 
[**RXPARITY**](open.htm#M48) 
[**FRAME**](open.htm#M49) 
[**BREAK**](open.htm#M50) 





 
[PORTABILITY ISSUES](open.htm#M51)  
[**Windows**](open.htm#M52)  
  
[**Unix**](open.htm#M53) 
 
[EXAMPLE](open.htm#M54) 
[SEE ALSO](open.htm#M55) 
[KEYWORDS](open.htm#M56) 










 Name
----

 open — Open a file-based or command pipeline channel Synopsis
--------

 **open** *fileName*  
 **open** *fileName access*  
 **open** *fileName access permissions*  
 Description
-----------

 This command opens a file, serial port, or command pipeline and returns a channel identifier that may be used in future invocations of commands like **[read](read.htm)**, **[puts](puts.htm)**, and **[close](close.htm)**. If the first character of *fileName* is not **|** then the command opens a file: *fileName* gives the name of the file to open, and it must conform to the conventions described in the **[filename](filename.htm)** manual entry.  The *access* argument, if present, indicates the way in which the file (or command pipeline) is to be accessed. In the first form *access* may have any of the following values: 


 **r**
 Open the file for reading only; the file must already exist. This is the default value if *access* is not specified. 

**r+**
 Open the file for both reading and writing; the file must already exist. 

**w**
 Open the file for writing only. Truncate it if it exists. If it does not exist, create a new file. 

**w+**
 Open the file for reading and writing. Truncate it if it exists. If it does not exist, create a new file. 

**a**
 Open the file for writing only. If the file does not exist, create a new empty file. Set the file pointer to the end of the file prior to each write. 

**a+**
 Open the file for reading and writing. If the file does not exist, create a new empty file. Set the initial access position to the end of the file. 

  All of the legal *access* values above may have the character **b** added as the second or third character in the value to indicate that the opened channel should be configured as if with the **[fconfigure](fconfigure.htm)** **-translation binary** option, making the channel suitable for reading or writing of binary data. 


 In the second form, *access* consists of a list of any of the following flags, all of which have the standard POSIX meanings. One of the flags must be either **RDONLY**, **WRONLY** or **RDWR**. 


 **RDONLY**
 Open the file for reading only. 

**WRONLY**
 Open the file for writing only. 

**RDWR**
 Open the file for both reading and writing. 

**APPEND**
 Set the file pointer to the end of the file prior to each write. 

**BINARY**
 Configure the opened channel with the **-translation binary** option. 

**CREAT**
 Create the file if it does not already exist (without this flag it is an error for the file not to exist). 

**EXCL**
 If **CREAT** is also specified, an error is returned if the file already exists. 

**NOCTTY**
 If the file is a terminal device, this flag prevents the file from becoming the controlling terminal of the process. 

**NONBLOCK**
 Prevents the process from blocking while opening the file, and possibly in subsequent I/O operations. The exact behavior of this flag is system- and device-dependent; its use is discouraged (it is better to use the **[fconfigure](fconfigure.htm)** command to put a file in nonblocking mode). For details refer to your system documentation on the **open** system call's **O\_NONBLOCK** flag. 

**TRUNC**
 If the file exists it is truncated to zero length. 

  If a new file is created as part of opening it, *permissions* (an integer) is used to set the permissions for the new file in conjunction with the process's file mode creation mask. *Permissions* defaults to 0666. 


Command pipelines
-----------------

 If the first character of *fileName* is “**|**” then the remaining characters of *fileName* are treated as a list of arguments that describe a command pipeline to invoke, in the same style as the arguments for **[exec](exec.htm)**. In this case, the channel identifier returned by **open** may be used to write to the command's input pipe or read from its output pipe, depending on the value of *access*. If write-only access is used (e.g. *access* is “**w**”), then standard output for the pipeline is directed to the current standard output unless overridden by the command. If read-only access is used (e.g. *access* is “**r**”), standard input for the pipeline is taken from the current standard input unless overridden by the command. The id of the spawned process is accessible through the **[pid](pid.htm)** command, using the channel id returned by **open** as argument.  If the command (or one of the commands) executed in the command pipeline returns an error (according to the definition in **[exec](exec.htm)**), a Tcl error is generated when **[close](close.htm)** is called on the channel unless the pipeline is in non-blocking mode then no exit status is returned (a silent **[close](close.htm)** with -blocking 0). 


 It is often useful to use the **[fileevent](fileevent.htm)** command with pipelines so other processing may happen at the same time as running the command in the background. 


Serial communications
---------------------

 If *fileName* refers to a serial port, then the specified serial port is opened and initialized in a platform-dependent manner. Acceptable values for the *fileName* to use to open a serial port are described in the PORTABILITY ISSUES section.  The **[fconfigure](fconfigure.htm)** command can be used to query and set additional configuration options specific to serial ports (where supported): 


 
**-mode** *baud***,***parity***,***data***,***stop*

 This option is a set of 4 comma-separated values: the baud rate, parity, number of data bits, and number of stop bits for this serial port. The *baud* rate is a simple integer that specifies the connection speed. *Parity* is one of the following letters: **n**, **o**, **e**, **m**, **s**; respectively signifying the parity options of “none”, “odd”, “even”, “mark”, or “space”. *Data* is the number of data bits and should be an integer from 5 to 8, while *stop* is the number of stop bits and should be the integer 1 or 2. 


**-handshake** *type*

 (Windows and Unix). This option is used to setup automatic handshake control. Note that not all handshake types maybe supported by your operating system. The *type* parameter is case-independent.  If *type* is **none** then any handshake is switched off. **rtscts** activates hardware handshake. Hardware handshake signals are described below. For software handshake **xonxoff** the handshake characters can be redefined with **-xchar**. An additional hardware handshake **dtrdsr** is available only under Windows. There is no default handshake configuration, the initial value depends on your operating system settings. The **-handshake** option cannot be queried. 



**-queue**
 (Windows and Unix). The **-queue** option can only be queried. It returns a list of two integers representing the current number of bytes in the input and output queue respectively. 


**-timeout** *msec*

 (Windows and Unix). This option is used to set the timeout for blocking read operations. It specifies the maximum interval between the reception of two bytes in milliseconds. For Unix systems the granularity is 100 milliseconds. The **-timeout** option does not affect write operations or nonblocking reads. This option cannot be queried. 


**-ttycontrol** *{signal boolean signal boolean ...}*

 (Windows and Unix). This option is used to setup the handshake output lines (see below) permanently or to send a BREAK over the serial line. The *signal* names are case-independent. **{RTS 1 DTR 0}** sets the RTS output to high and the DTR output to low. The BREAK condition (see below) is enabled and disabled with **{BREAK 1}** and **{BREAK 0}** respectively. It is not a good idea to change the **RTS** (or **DTR**) signal with active hardware handshake **rtscts** (or **dtrdsr**). The result is unpredictable. The **-ttycontrol** option cannot be queried. 

**-ttystatus**
 (Windows and Unix). The **-ttystatus** option can only be queried. It returns the current modem status and handshake input signals (see below). The result is a list of signal,value pairs with a fixed order, e.g. **{CTS 1 DSR 0 RING 1 DCD 0}**. The *signal* names are returned upper case. 


**-xchar** *{xonChar xoffChar}*

 (Windows and Unix). This option is used to query or change the software handshake characters. Normally the operating system default should be DC1 (0x11) and DC3 (0x13) representing the ASCII standard XON and XOFF characters. 


**-pollinterval** *msec*

 (Windows only). This option is used to set the maximum time between polling for fileevents. This affects the time interval between checking for events throughout the Tcl interpreter (the smallest value always wins). Use this option only if you want to poll the serial port more or less often than 10 msec (the default). 


**-sysbuffer** *inSize*


**-sysbuffer** *{inSize outSize}*

 (Windows only). This option is used to change the size of Windows system buffers for a serial channel. Especially at higher communication rates the default input buffer size of 4096 bytes can overrun for latent systems. The first form specifies the input buffer size, in the second form both input and output buffers are defined. 

**-lasterror**
 (Windows only). This option is query only. In case of a serial communication error, **[read](read.htm)** or **[puts](puts.htm)** returns a general Tcl file I/O error. **[fconfigure](fconfigure.htm)** **-lasterror** can be called to get a list of error details. See below for an explanation of the various error codes. 

 Serial port signals
-------------------

 RS-232 is the most commonly used standard electrical interface for serial communications. A negative voltage (-3V..-12V) define a mark (on=1) bit and a positive voltage (+3..+12V) define a space (off=0) bit (RS-232C). The following signals are specified for incoming and outgoing data, status lines and handshaking. Here we are using the terms *workstation* for your computer and *modem* for the external device, because some signal names (DCD, RI) come from modems. Of course your external device may use these signal lines for other purposes. 
 
**TXD**(output)
 **Transmitted Data:** Outgoing serial data. 


**RXD**(input)
 **Received Data:**Incoming serial data. 


**RTS**(output)
 **Request To Send:** This hardware handshake line informs the modem that your workstation is ready to receive data. Your workstation may automatically reset this signal to indicate that the input buffer is full. 


**CTS**(input)
 **Clear To Send:** The complement to RTS. Indicates that the modem is ready to receive data. 


**DTR**(output)
 **Data Terminal Ready:** This signal tells the modem that the workstation is ready to establish a link. DTR is often enabled automatically whenever a serial port is opened. 


**DSR**(input)
 **Data Set Ready:** The complement to DTR. Tells the workstation that the modem is ready to establish a link. 


**DCD**(input)
 **Data Carrier Detect:** This line becomes active when a modem detects a “Carrier” signal. 


**RI**(input)
 **Ring Indicator:** Goes active when the modem detects an incoming call. 

**BREAK**
 A BREAK condition is not a hardware signal line, but a logical zero on the TXD or RXD lines for a long period of time, usually 250 to 500 milliseconds. Normally a receive or transmit data signal stays at the mark (on=1) voltage until the next character is transferred. A BREAK is sometimes used to reset the communications line or change the operating mode of communications hardware. 

 Error codes (windows only)
--------------------------

 A lot of different errors may occur during serial read operations or during event polling in background. The external device may have been switched off, the data lines may be noisy, system buffers may overrun or your mode settings may be wrong. That is why a reliable software should always **[catch](catch.htm)** serial read operations. In cases of an error Tcl returns a general file I/O error. Then **[fconfigure](fconfigure.htm)** **-lasterror** may help to locate the problem. The following error codes may be returned. 
 **RXOVER**
 Windows input buffer overrun. The data comes faster than your scripts reads it or your system is overloaded. Use **[fconfigure](fconfigure.htm)** **-sysbuffer** to avoid a temporary bottleneck and/or make your script faster. 

**TXFULL**
 Windows output buffer overrun. Complement to RXOVER. This error should practically not happen, because Tcl cares about the output buffer status. 

**OVERRUN**
 UART buffer overrun (hardware) with data lost. The data comes faster than the system driver receives it. Check your advanced serial port settings to enable the FIFO (16550) buffer and/or setup a lower(1) interrupt threshold value. 

**RXPARITY**
 A parity error has been detected by your UART. Wrong parity settings with **[fconfigure](fconfigure.htm)** **-mode** or a noisy data line (RXD) may cause this error. 

**FRAME**
 A stop-bit error has been detected by your UART. Wrong mode settings with **[fconfigure](fconfigure.htm)** **-mode** or a noisy data line (RXD) may cause this error. 

**BREAK**
 A BREAK condition has been detected by your UART (see above). 

 Portability issues
------------------

  **Windows** 
 Valid values for *fileName* to open a serial port are of the form **com***X*, where *X* is a number, generally from 1 to 9. A legacy form accepted as well is **com***X***:**. This notation only works for serial ports from 1 to 9. An attempt to open a serial port that does not exist or has a number greater than 9 will fail. An alternate form of opening serial ports is to use the filename **//./comX**, where X is any number that corresponds to a serial port. 


 When running Tcl interactively, there may be some strange interactions between the real console, if one is present, and a command pipeline that uses standard input or output. If a command pipeline is opened for reading, some of the lines entered at the console will be sent to the command pipeline and some will be sent to the Tcl evaluator. If a command pipeline is opened for writing, keystrokes entered into the console are not visible until the pipe is closed. These problems only occur because both Tcl and the child application are competing for the console at the same time. If the command pipeline is started from a script, so that Tcl is not accessing the console, or if the command pipeline does not use standard input or output, but is redirected from or to a file, then the above problems do not occur. 
 **Unix**
 Valid values for *fileName* to open a serial port are generally of the form **/dev/tty***X*, where *X* is **a** or **b**, but the name of any pseudo-file that maps to a serial port may be used. Advanced configuration options are only supported for serial ports when Tcl is built to use the POSIX serial interface.  When running Tcl interactively, there may be some strange interactions between the console, if one is present, and a command pipeline that uses standard input. If a command pipeline is opened for reading, some of the lines entered at the console will be sent to the command pipeline and some will be sent to the Tcl evaluator. This problem only occurs because both Tcl and the child application are competing for the console at the same time. If the command pipeline is started from a script, so that Tcl is not accessing the console, or if the command pipeline does not use standard input, but is redirected from a file, then the above problem does not occur. 



  See the **[PORTABILITY ISSUES](#M51)** section of the **[exec](exec.htm)** command for additional information not specific to command pipelines about executing applications on the various platforms 


Example
-------

 Open a command pipeline and catch any errors: 

```
set fl [**open** "| ls this_file_does_not_exist"]
set data [read $fl]
if {[catch {close $fl} err]} {
    puts "ls command failed: $err"
}
```
 See also
--------

 **[file](file.htm)**, **[close](close.htm)**, **[filename](filename.htm)**, **[fconfigure](fconfigure.htm)**, **[gets](gets.htm)**, **[read](read.htm)**, **[puts](puts.htm)**, **[exec](exec.htm)**, **[pid](pid.htm)**, **fopen** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/open.htm>

packagens
=========

  
[NAME](packagens.htm#M2) pkg::create — Construct an appropriate 'package ifneeded' command for a given package specification 
[SYNOPSIS](packagens.htm#M3) 
[DESCRIPTION](packagens.htm#M4) 
[OPTIONS](packagens.htm#M5)  
[**-name** *packageName*](packagens.htm#M6) 
[**-version** *packageVersion*](packagens.htm#M7) 
[**-load** *filespec*](packagens.htm#M8) 
[**-source** *filespec*](packagens.htm#M9) 



 
[SEE ALSO](packagens.htm#M10) 
[KEYWORDS](packagens.htm#M11) 





 Name
----

 pkg::create — Construct an appropriate 'package ifneeded' command for a given package specification Synopsis
--------

 **::pkg::create** **-name** *packageName* **-version** *packageVersion* ?**-load** *filespec*? ... ?**-source** *filespec*? ...  
 Description
-----------

 **::pkg::create** is a utility procedure that is part of the standard Tcl library. It is used to create an appropriate **[package ifneeded](package.htm)** command for a given package specification. It can be used to construct a **pkgIndex.tcl** file for use with the **[package](package.htm)** mechanism. Options
-------

 The parameters supported are: 
 
**-name** *packageName*

 This parameter specifies the name of the package. It is required. 


**-version** *packageVersion*

 This parameter specifies the version of the package. It is required. 


**-load** *filespec*

 This parameter specifies a binary library that must be loaded with the **[load](load.htm)** command. *filespec* is a list with two elements. The first element is the name of the file to load. The second, optional element is a list of commands supplied by loading that file. If the list of procedures is empty or omitted, **::pkg::create** will set up the library for direct loading (see **pkg\_mkIndex**). Any number of **-load** parameters may be specified. 


**-source** *filespec*

 This parameter is similar to the **-load** parameter, except that it specifies a Tcl library that must be loaded with the **[source](source.htm)** command. Any number of **-source** parameters may be specified. 

  At least one **-load** or **-source** parameter must be given. 


See also
--------

 **[package](package.htm)** Copyright © 1998-2000 by Scriptics Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/packagens.htm>

lindex
======

 Name
----

 lindex — Retrieve an element from a list Synopsis
--------

 **lindex** *list ?index ...?*  
 Description
-----------

 The **lindex** command accepts a parameter, *list*, which it treats as a Tcl list. It also accepts zero or more *indices* into the list. The indices may be presented either consecutively on the command line, or grouped in a Tcl list and presented as a single argument.  If no indices are presented, the command takes the form: 



```
**lindex** *list*
```
  or 



```
**lindex** *list* {}
```
  In this case, the return value of **lindex** is simply the value of the *list* parameter. 


 When presented with a single index, the **lindex** command treats *list* as a Tcl list and returns the *index*'th element from it (0 refers to the first element of the list). In extracting the element, **lindex** observes the same rules concerning braces and quotes and backslashes as the Tcl command interpreter; however, variable substitution and command substitution do not occur. If *index* is negative or greater than or equal to the number of elements in *value*, then an empty string is returned. The interpretation of each simple *index* value is the same as for the command **[string index](string.htm)**, supporting simple index arithmetic and indices relative to the end of the list. 


 If additional *index* arguments are supplied, then each argument is used in turn to select an element from the previous indexing operation, allowing the script to select elements from sublists. The command, 



```
**lindex** $a 1 2 3
```
  or 



```
**lindex** $a {1 2 3}
```
  is synonymous with 



```
**lindex** [**lindex** [**lindex** $a 1] 2] 3
```
 Examples
--------

 Lists can be indexed into from either end: 

```
**lindex** {a b c} 0
      *→ a*
**lindex** {a b c} 2
      *→ c*
**lindex** {a b c} end
      *→ c*
**lindex** {a b c} end-1
      *→ b*
```
  Lists or sequences of indices allow selection into lists of lists: 



```
**lindex** {a b c}
      *→ a b c*
**lindex** {a b c} {}
      *→ a b c*
**lindex** {{a b c} {d e f} {g h i}} 2 1
      *→ h*
**lindex** {{a b c} {d e f} {g h i}} {2 1}
      *→ h*
**lindex** {{{a b} {c d}} {{e f} {g h}}} 1 1 0
      *→ g*
**lindex** {{{a b} {c d}} {{e f} {g h}}} {1 1 0}
      *→ g*
```
  List indices may also perform limited computation, adding or subtracting fixed amounts from other indices: 



```
set idx 1
**lindex** {a b c d e f} $idx+2
      *→ d*
set idx 3
**lindex** {a b c d e f} $idx+2
      *→ f*
```
 See also
--------

 **[list](list.htm)**, **[lappend](lappend.htm)**, **[linsert](linsert.htm)**, **[llength](llength.htm)**, **[lsearch](lsearch.htm)**, **[lset](lset.htm)**, **[lsort](lsort.htm)**, **[lrange](lrange.htm)**, **[lreplace](lreplace.htm)**, **[string](string.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2001 by Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/lindex.htm>

platform
========

 Name
----

 platform — System identification support code and utilities Synopsis
--------

 **package require platform ?1.0.10?**  
 **platform::generic**  
 **platform::identify**  
 **platform::patterns** *identifier*  
 Description
-----------

 The **platform** package provides several utility commands useful for the identification of the architecture of a machine running Tcl.  Whilst Tcl provides the **[tcl\_platform](tclvars.htm)** array for identifying the current architecture (in particular, the platform and machine elements) this is not always sufficient. This is because (on Unix machines) **[tcl\_platform](tclvars.htm)** reflects the values returned by the **uname** command and these are not standardized across platforms and architectures. In addition, on at least one platform (AIX) the **tcl\_platform(machine)** contains the CPU serial number. 


 Consequently, individual applications need to manipulate the values in **[tcl\_platform](tclvars.htm)** (along with the output of system specific utilities) - which is both inconvenient for developers, and introduces the potential for inconsistencies in identifying architectures and in naming conventions. 


 The **platform** package prevents such fragmentation - i.e., it establishes a standard naming convention for architectures running Tcl and makes it more convenient for developers to identify the current architecture a Tcl program is running on. 


Commands
--------

  **platform::identify**
 This command returns an identifier describing the platform the Tcl core is running on. The returned identifier has the general format *OS*-*CPU*. The *OS* part of the identifier may contain details like kernel version, libc version, etc., and this information may contain dashes as well. The *CPU* part will not contain dashes, making the preceding dash the last dash in the result. 

**platform::generic**
 This command returns a simplified identifier describing the platform the Tcl core is running on. In contrast to **platform::identify** it leaves out details like kernel version, libc version, etc. The returned identifier has the general format *OS*-*CPU*. 


**platform::patterns** *identifier*

 This command takes an identifier as returned by **platform::identify** and returns a list of identifiers describing compatible architectures. 

 Example
-------

 This can be used to allow an application to be shipped with multiple builds of a shared library, so that the same package works on many versions of an operating system. For example: 

```
**package require platform**
# Assume that app script is .../theapp/bin/theapp.tcl
set binDir [file dirname [file normalize [info script]]]
set libDir [file join $binDir .. lib]
set platLibDir [file join $libDir [**platform::identify**]]
load [file join $platLibDir support[info sharedlibextension]]
```
 Copyright © 2006 ActiveState Software Inc 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/platform.htm>

platform\_shell
===============

 Name
----

 platform::shell — System identification support code and utilities Synopsis
--------

 **package require platform::shell ?1.1.4?**  
 **platform::shell::generic** *shell*  
 **platform::shell::identify** *shell*  
 **platform::shell::platform** *shell*  
 Description
-----------

 The **platform::shell** package provides several utility commands useful for the identification of the architecture of a specific Tcl shell.  This package allows the identification of the architecture of a specific Tcl shell different from the shell running the package. The only requirement is that the other shell (identified by its path), is actually executable on the current machine. 


 While for most platform this means that the architecture of the interrogated shell is identical to the architecture of the running shell this is not generally true. A counter example are all platforms which have 32 and 64 bit variants and where a 64bit system is able to run 32bit code. For these running and interrogated shell may have different 32/64 bit settings and thus different identifiers. 


 For applications like a code repository it is important to identify the architecture of the shell which will actually run the installed packages, versus the architecture of the shell running the repository software. 


Commands
--------

  
**platform::shell::identify** *shell*

 This command does the same identification as **platform::identify**, for the specified Tcl shell, in contrast to the running shell. 


**platform::shell::generic** *shell*

 This command does the same identification as **platform::generic**, for the specified Tcl shell, in contrast to the running shell. 


**platform::shell::platform** *shell*

 This command returns the contents of **tcl\_platform(platform)** for the specified Tcl shell. 

 Copyright © 2006-2008 ActiveState Software Inc 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/platform_shell.htm>

eof
===

 Name
----

 eof — Check for end of file condition on channel Synopsis
--------

 **eof** *channelId*  
 Description
-----------

 Returns 1 if an end of file condition occurred during the most recent input operation on *channelId* (such as **[gets](gets.htm)**), 0 otherwise.  *ChannelId* must be an identifier for an open channel such as a Tcl standard channel (**[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, or **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**), the return value from an invocation of **[open](open.htm)** or **[socket](socket.htm)**, or the result of a channel creation command provided by a Tcl extension. 


Examples
--------

 Read and print out the contents of a file line-by-line: 

```
set f [open somefile.txt]
while {1} {
    set line [gets $f]
    if {[**eof** $f]} {
        close $f
        break
    }
    puts "Read line: $line"
}
```
  Read and print out the contents of a file by fixed-size records: 



```
set f [open somefile.dat]
fconfigure $f -translation binary
set recordSize 40
while {1} {
    set record [read $f $recordSize]
    if {[**eof** $f]} {
        close $f
        break
    }
    puts "Read record: $record"
}
```
 See also
--------

 **[file](file.htm)**, **[open](open.htm)**, **[close](close.htm)**, **[fblocked](fblocked.htm)**, **[Tcl\_StandardChannels](https://www.tcl.tk/man/tcl/TclLib/StdChannels.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/eof.htm>

dde
===

  
[NAME](dde.htm#M2) dde — Execute a Dynamic Data Exchange command 
[SYNOPSIS](dde.htm#M3) 
[DESCRIPTION](dde.htm#M4) 
[DDE COMMANDS](dde.htm#M5)  
[**dde servername** ?**-force**? ?**-handler** *proc*? ?**--**? ?*topic*?](dde.htm#M6) 
[**dde execute** ?**-async**? ?**-binary**? *service topic data*](dde.htm#M7) 
[**dde poke** ?**-binary**? *service topic item data*](dde.htm#M8) 
[**dde request** ?**-binary**? *service topic item*](dde.htm#M9) 
[**dde services** *service topic*](dde.htm#M10) 
[**dde eval** ?**-async**? *topic cmd* ?*arg arg ...*?](dde.htm#M11) 





 
[DDE AND TCL](dde.htm#M12) 
[EXAMPLE](dde.htm#M13) 
[SEE ALSO](dde.htm#M14) 
[KEYWORDS](dde.htm#M15) 







 Name
----

 dde — Execute a Dynamic Data Exchange command Synopsis
--------

 **package require dde 1.4**  
 **dde servername** ?**-force**? ?**-handler** *proc*? ?**--**? ?*topic*?  
 **dde execute** ?**-async**? ?**-binary**? *service topic data*  
 **dde poke** ?**-binary**? *service topic item data*  
 **dde request** ?**-binary**? *service topic item*  
 **dde services** *service topic*  
 **dde eval** ?**-async**? *topic cmd* ?*arg arg ...*?  
 Description
-----------

 This command allows an application to send Dynamic Data Exchange (DDE) command when running under Microsoft Windows. Dynamic Data Exchange is a mechanism where applications can exchange raw data. Each DDE transaction needs a *service name* and a *topic*. Both the *service name* and *topic* are application defined; Tcl uses the service name **TclEval**, while the topic name is the name of the interpreter given by **dde servername**. Other applications have their own *service names* and *topics*. For instance, Microsoft Excel has the service name **Excel**. 
Dde commands
------------

 The following commands are a subset of the full Dynamic Data Exchange set of commands. 
 
**dde servername** ?**-force**? ?**-handler** *proc*? ?**--**? ?*topic*?
 **dde servername** registers the interpreter as a DDE server with the service name **TclEval** and the topic name specified by *topic*. If no *topic* is given, **dde servername** returns the name of the current topic or the empty string if it is not registered as a service. If the given *topic* name is already in use, then a suffix of the form “ #2” or “ #3” is appended to the name to make it unique. The command's result will be the name actually used. The **-force** option is used to force registration of precisely the given *topic* name.  The **-handler** option specifies a Tcl procedure that will be called to process calls to the dde server. If the package has been loaded into a safe interpreter then a **-handler** procedure must be defined. The procedure is called with all the arguments provided by the remote call. 




**dde execute** ?**-async**? ?**-binary**? *service topic data*

 **dde execute** takes the *data* and sends it to the server indicated by *service* with the topic indicated by *topic*. Typically, *service* is the name of an application, and *topic* is a file to work on. The *data* field is given to the remote application. Typically, the application treats the *data* field as a script, and the script is run in the application. The **-async** option requests asynchronous invocation. The command returns an error message if the script did not run, unless the **-async** flag was used, in which case the command returns immediately with no error. Without the **-binary** option all data will be sent in unicode. For dde clients which don't implement the CF\_UNICODE clipboard format, this will automatically be translated to the system encoding. You can use the **-binary** option in combination with the result of **[encoding convertto](encoding.htm)** to send data in any other encoding. 


**dde poke** ?**-binary**? *service topic item data*

 **dde poke** passes the *data* to the server indicated by *service* using the *topic* and *item* specified. Typically, *service* is the name of an application. *topic* is application specific but can be a command to the server or the name of a file to work on. The *item* is also application specific and is often not used, but it must always be non-null. The *data* field is given to the remote application. Without the **-binary** option all data will be sent in unicode. For dde clients which don't implement the CF\_UNICODE clipboard format, this will automatically be translated to the system encoding. You can use the **-binary** option in combination with the result of **[encoding convertto](encoding.htm)** to send data in any other encoding. 


**dde request** ?**-binary**? *service topic item*

 **dde request** is typically used to get the value of something; the value of a cell in Microsoft Excel or the text of a selection in Microsoft Word. *service* is typically the name of an application, *topic* is typically the name of the file, and *item* is application-specific. The command returns the value of *item* as defined in the application. Normally this is interpreted to be a string with terminating null. If **-binary** is specified, the result is returned as a byte array. 


**dde services** *service topic*

 **dde services** returns a list of service-topic pairs that currently exist on the machine. If *service* and *topic* are both empty strings ({}), then all service-topic pairs currently available on the system are returned. If *service* is empty and *topic* is not, then all services with the specified topic are returned. If *service* is non-empty and *topic* is, all topics for a given service are returned. If both are non-empty, if that service-topic pair currently exists, it is returned; otherwise, an empty string is returned. 


**dde eval** ?**-async**? *topic cmd* ?*arg arg ...*?
 **dde eval** evaluates a command and its arguments using the interpreter specified by *topic*. The DDE service must be the **TclEval** service. The **-async** option requests asynchronous invocation. The command returns an error message if the script did not run, unless the **-async** flag was used, in which case the command returns immediately with no error. This command can be used to replace send on Windows. 

 Dde and tcl
-----------

 A Tcl interpreter always has a service name of **TclEval**. Each different interpreter of all running Tcl applications must be given a unique name specified by **dde servername**. Each interp is available as a DDE topic only if the **dde servername** command was used to set the name of the topic for each interp. So a **dde services TclEval {}** command will return a list of service-topic pairs, where each of the currently running interps will be a topic.  When Tcl processes a **dde execute** command, the data for the execute is run as a script in the interp named by the topic of the **dde execute** command. 


 When Tcl processes a **dde request** command, it returns the value of the variable given in the dde command in the context of the interp named by the dde topic. Tcl reserves the variable **$TCLEVAL$EXECUTE$RESULT** for internal use, and **dde request** commands for that variable will give unpredictable results. 


 An external application which wishes to run a script in Tcl should have that script store its result in a variable, run the **dde execute** command, and then run **dde request** to get the value of the variable. 


 When using DDE, be careful to ensure that the event queue is flushed using either **[update](update.htm)** or **[vwait](vwait.htm)**. This happens by default when using **[wish](../usercmd/wish.htm)** unless a blocking command is called (such as **[exec](exec.htm)** without adding the **&** to place the process in the background). If for any reason the event queue is not flushed, DDE commands may hang until the event queue is flushed. This can create a deadlock situation. 


Example
-------

 This asks Internet Explorer (which must already be running) to go to a particularly important website: 

```
package require dde
**dde execute** -async iexplore WWW_OpenURL <http://www.tcl.tk/>
```
 See also
--------

 **[tk](../tkcmd/tk.htm)**, **[winfo](../tkcmd/winfo.htm)**, **[send](../tkcmd/send.htm)** Copyright © 1997 Sun Microsystems, Inc.  
 Copyright © 2001 ActiveState Corporation. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/dde.htm>

error
=====

 Name
----

 error — Generate an error Synopsis
--------

 **error** *message* ?*info*? ?*code*?  
 Description
-----------

 Returns a **[TCL\_ERROR](catch.htm)** code, which causes command interpretation to be unwound. *Message* is a string that is returned to the application to indicate what went wrong.  The **-errorinfo** return option of an interpreter is used to accumulate a stack trace of what was in progress when an error occurred; as nested commands unwind, the Tcl interpreter adds information to the **-errorinfo** return option. If the *info* argument is present, it is used to initialize the **-errorinfo** return options and the first increment of unwind information will not be added by the Tcl interpreter. In other words, the command containing the **error** command will not appear in the stack trace; in its place will be *info*. Historically, this feature had been most useful in conjunction with the **[catch](catch.htm)** command: if a caught error cannot be handled successfully, *info* can be used to return a stack trace reflecting the original point of occurrence of the error: 



```
catch {...} errMsg
set savedInfo $::errorInfo
	...
**error** $errMsg $savedInfo
```
  When working with Tcl 8.5 or later, the following code should be used instead: 



```
catch {...} errMsg options
	...
return -options $options $errMsg
```
  If the *code* argument is present, then its value is stored in the **-errorcode** return option. The **-errorcode** return option is intended to hold a machine-readable description of the error in cases where such information is available; see the **[return](return.htm)** manual page for information on the proper format for this option's value. 


Example
-------

 Generate an error if a basic mathematical operation fails: 

```
if {1+2 != 3} {
    **error** "something is very wrong with addition"
}
```
 See also
--------

 **[catch](catch.htm)**, **[return](return.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/error.htm>

llength
=======

 Name
----

 llength — Count the number of elements in a list Synopsis
--------

 **llength** *list*  
 Description
-----------

 Treats *list* as a list and returns a decimal string giving the number of elements in it. Examples
--------

 The result is the number of elements: 

```
% **llength** {a b c d e}
5
% **llength** {a b c}
3
% **llength** {}
0
```
  Elements are not guaranteed to be exactly words in a dictionary sense of course, especially when quoting is used: 



```
% **llength** {a b {c d} e}
4
% **llength** {a b { } c d e}
6
```
  An empty list is not necessarily an empty string: 



```
% set var { }; puts "[string length $var],[**llength** $var]"
1,0
```
 See also
--------

 **[list](list.htm)**, **[lappend](lappend.htm)**, **[lindex](lindex.htm)**, **[linsert](linsert.htm)**, **[lsearch](lsearch.htm)**, **[lset](lset.htm)**, **[lsort](lsort.htm)**, **[lrange](lrange.htm)**, **[lreplace](lreplace.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc.  
 Copyright © 2001 Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/llength.htm>

pwd
===

 Name
----

 pwd — Return the absolute path of the current working directory Synopsis
--------

 **pwd**  
 Description
-----------

 Returns the absolute path name of the current working directory. Example
-------

 Sometimes it is useful to change to a known directory when running some external command using **[exec](exec.htm)**, but it is important to keep the application usually running in the directory that it was started in (unless the user specifies otherwise) since that minimizes user confusion. The way to do this is to save the current directory while the external command is being run: 

```
set tarFile [file normalize somefile.tar]
set savedDir [**pwd**]
cd /tmp
exec tar -xf $tarFile
cd $savedDir
```
 See also
--------

 **[file](file.htm)**, **[cd](cd.htm)**, **[glob](glob.htm)**, **[filename](filename.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/pwd.htm>

chan
====

  
[NAME](chan.htm#M2) chan — Read, write and manipulate channels 
[SYNOPSIS](chan.htm#M3) 
[DESCRIPTION](chan.htm#M4)  
[**chan blocked** *channelId*](chan.htm#M5) 
[**chan close** *channelId* ?*direction*?](chan.htm#M6) 
[**chan configure** *channelId* ?*optionName*? ?*value*? ?*optionName value*?...](chan.htm#M7)  
[**-blocking** *boolean*](chan.htm#M8) 
[**-buffering** *newValue*](chan.htm#M9) 
[**-buffersize** *newSize*](chan.htm#M10) 
[**-encoding** *name*](chan.htm#M11) 
[**-eofchar** *char*](chan.htm#M12) 
[**-eofchar** **{***inChar outChar***}**](chan.htm#M13) 
[**-translation** *mode*](chan.htm#M14) 
[**-translation** **{***inMode outMode***}**](chan.htm#M15)  
[**auto**](chan.htm#M16) 
[**binary**](chan.htm#M17) 
[**cr**](chan.htm#M18) 
[**crlf**](chan.htm#M19) 
[**lf**](chan.htm#M20) 




 







 
[**chan copy** *inputChan outputChan* ?**-size** *size*? ?**-command** *callback*?](chan.htm#M21) 
[**chan create** *mode cmdPrefix*](chan.htm#M22) 
[**chan eof** *channelId*](chan.htm#M23) 
[**chan event** *channelId event* ?*script*?](chan.htm#M24) 
[**chan flush** *channelId*](chan.htm#M25) 
[**chan gets** *channelId* ?*varName*?](chan.htm#M26) 
[**chan names** ?*pattern*?](chan.htm#M27) 
[**chan pending** *mode channelId*](chan.htm#M28) 
[**chan pipe**](chan.htm#M29) 
[**chan pop** *channelId*](chan.htm#M30) 
[**chan postevent** *channelId eventSpec*](chan.htm#M31) 
[**chan push** *channelId cmdPrefix*](chan.htm#M32) 
[**chan puts** ?**-nonewline**? ?*channelId*? *string*](chan.htm#M33) 
[**chan read** *channelId* ?*numChars*?](chan.htm#M34) 
[**chan read** ?**-nonewline**? *channelId*](chan.htm#M35)  
[**chan read** *channelId numChars*](chan.htm#M36) 
[**chan read** *channelId*](chan.htm#M37) 

 
[**chan seek** *channelId offset* ?*origin*?](chan.htm#M38)  
[**start**](chan.htm#M39) 
[**current**](chan.htm#M40) 
[**end**](chan.htm#M41) 


 
[**chan tell** *channelId*](chan.htm#M42) 
[**chan truncate** *channelId* ?*length*?](chan.htm#M43) 




















 
[EXAMPLES](chan.htm#M44) 
[SEE ALSO](chan.htm#M45) 
[KEYWORDS](chan.htm#M46) 





 Name
----

 chan — Read, write and manipulate channels Synopsis
--------

 **chan** *option* ?*arg arg ...*?  
 Description
-----------

 This command provides several operations for reading from, writing to and otherwise manipulating open channels (such as have been created with the **[open](open.htm)** and **[socket](socket.htm)** commands, or the default named channels **[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**, **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** or **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** which correspond to the process's standard input, output and error streams respectively). *Option* indicates what to do with the channel; any unique abbreviation for *option* is acceptable. Valid options are: 
 
**chan blocked** *channelId*

 This tests whether the last input operation on the channel called *channelId* failed because it would have otherwise caused the process to block, and returns 1 if that was the case. It returns 0 otherwise. Note that this only ever returns 1 when the channel has been configured to be non-blocking; all Tcl channels have blocking turned on by default. 


**chan close** *channelId* ?*direction*?
 Close and destroy the channel called *channelId*. Note that this deletes all existing file-events registered on the channel. If the *direction* argument (which must be **[read](read.htm)** or **write** or any unique abbreviation of them) is present, the channel will only be half-closed, so that it can go from being read-write to write-only or read-only respectively. If a read-only channel is closed for reading, it is the same as if the channel is fully closed, and respectively similar for write-only channels. Without the *direction* argument, the channel is closed for both reading and writing (but only if those directions are currently open). It is an error to close a read-only channel for writing, or a write-only channel for reading.  As part of closing the channel, all buffered output is flushed to the channel's output device (only if the channel is ceasing to be writable), any buffered input is discarded (only if the channel is ceasing to be readable), the underlying operating system resource is closed and *channelId* becomes unavailable for future use (both only if the channel is being completely closed). 


 If the channel is blocking and the channel is ceasing to be writable, the command does not return until all output is flushed. If the channel is non-blocking and there is unflushed output, the channel remains open and the command returns immediately; output will be flushed in the background and the channel will be closed when all the flushing is complete. 


 If *channelId* is a blocking channel for a command pipeline then **chan close** waits for the child processes to complete. 


 If the channel is shared between interpreters, then **chan close** makes *channelId* unavailable in the invoking interpreter but has no other effect until all of the sharing interpreters have closed the channel. When the last interpreter in which the channel is registered invokes **chan close** (or **[close](close.htm)**), the cleanup actions described above occur. With half-closing, the half-close of the channel only applies to the current interpreter's view of the channel until all channels have closed it in that direction (or completely). See the **[interp](interp.htm)** command for a description of channel sharing. 


 Channels are automatically fully closed when an interpreter is destroyed and when the process exits. Channels are switched to blocking mode, to ensure that all output is correctly flushed before the process exits. 


 The command returns an empty string, and may generate an error if an error occurs while flushing output. If a command in a command pipeline created with **[open](open.htm)** returns an error, **chan close** generates an error (similar to the **[exec](exec.htm)** command.) 


Note that half-closes of sockets and command pipelines can have important side effects because they result in a shutdown() or close() of the underlying system resource, which can change how other processes or systems respond to the Tcl program. 




**chan configure** *channelId* ?*optionName*? ?*value*? ?*optionName value*?...
 Query or set the configuration options of the channel named *channelId*.  If no *optionName* or *value* arguments are supplied, the command returns a list containing alternating option names and values for the channel. If *optionName* is supplied but no *value* then the command returns the current value of the given option. If one or more pairs of *optionName* and *value* are supplied, the command sets each of the named options to the corresponding *value*; in this case the return value is an empty string. 


 The options described below are supported for all channels. In addition, each channel type may add options that only it supports. See the manual entry for the command that creates each type of channel for the options supported by that specific type of channel. For example, see the manual entry for the **[socket](socket.htm)** command for additional options for sockets, and the **[open](open.htm)** command for additional options for serial devices. 


 
**-blocking** *boolean*

 The **-blocking** option determines whether I/O operations on the channel can cause the process to block indefinitely. The value of the option must be a proper boolean value. Channels are normally in blocking mode; if a channel is placed into non-blocking mode it will affect the operation of the **chan gets**, **chan read**, **chan puts**, **chan flush**, and **chan close** commands; see the documentation for those commands for details. For non-blocking mode to work correctly, the application must be using the Tcl event loop (e.g. by calling **[Tcl\_DoOneEvent](https://www.tcl.tk/man/tcl/TclLib/DoOneEvent.htm)** or invoking the **[vwait](vwait.htm)** command). 


**-buffering** *newValue*

 If *newValue* is **full** then the I/O system will buffer output until its internal buffer is full or until the **chan flush** command is invoked. If *newValue* is **line**, then the I/O system will automatically flush output for the channel whenever a newline character is output. If *newValue* is **none**, the I/O system will flush automatically after every output operation. The default is for **-buffering** to be set to **full** except for channels that connect to terminal-like devices; for these channels the initial setting is **line**. Additionally, **[stdin](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** and **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** are initially set to **line**, and **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** is set to **none**. 


**-buffersize** *newSize*

 *Newvalue* must be an integer; its value is used to set the size of buffers, in bytes, subsequently allocated for this channel to store input or output. *Newvalue* must be a number of no more than one million, allowing buffers of up to one million bytes in size. 


**-encoding** *name*

 This option is used to specify the encoding of the channel as one of the named encodings returned by **[encoding names](encoding.htm)** or the special value **[binary](binary.htm)**, so that the data can be converted to and from Unicode for use in Tcl. For instance, in order for Tcl to read characters from a Japanese file in **shiftjis** and properly process and display the contents, the encoding would be set to **shiftjis**. Thereafter, when reading from the channel, the bytes in the Japanese file would be converted to Unicode as they are read. Writing is also supported - as Tcl strings are written to the channel they will automatically be converted to the specified encoding on output.  If a file contains pure binary data (for instance, a JPEG image), the encoding for the channel should be configured to be **[binary](binary.htm)**. Tcl will then assign no interpretation to the data in the file and simply read or write raw bytes. The Tcl **[binary](binary.htm)** command can be used to manipulate this byte-oriented data. It is usually better to set the **-translation** option to **[binary](binary.htm)** when you want to transfer binary data, as this turns off the other automatic interpretations of the bytes in the stream as well. 


The default encoding for newly opened channels is the same platform- and locale-dependent system encoding used for interfacing with the operating system, as returned by **[encoding system](encoding.htm)**. 




**-eofchar** *char*


**-eofchar** **{***inChar outChar***}**

 This option supports DOS file systems that use Control-z (\x1a) as an end of file marker. If *char* is not an empty string, then this character signals end-of-file when it is encountered during input. For output, the end-of-file character is output when the channel is closed. If *char* is the empty string, then there is no special end of file character marker. For read-write channels, a two-element list specifies the end of file marker for input and output, respectively. As a convenience, when setting the end-of-file character for a read-write channel you can specify a single value that will apply to both reading and writing. When querying the end-of-file character of a read-write channel, a two-element list will always be returned. The default value for **-eofchar** is the empty string in all cases except for files under Windows. In that case the **-eofchar** is Control-z (\x1a) for reading and the empty string for writing. The acceptable range for **-eofchar** values is \x01 - \x7f; attempting to set **-eofchar** to a value outside of this range will generate an error. 


**-translation** *mode*


**-translation** **{***inMode outMode***}**

 In Tcl scripts the end of a line is always represented using a single newline character (\n). However, in actual files and devices the end of a line may be represented differently on different platforms, or even for different devices on the same platform. For example, under UNIX newlines are used in files, whereas carriage-return-linefeed sequences are normally used in network connections. On input (i.e., with **chan gets** and **chan read**) the Tcl I/O system automatically translates the external end-of-line representation into newline characters. Upon output (i.e., with **chan puts**), the I/O system translates newlines to the external end-of-line representation. The default translation mode, **auto**, handles all the common cases automatically, but the **-translation** option provides explicit control over the end of line translations.  The value associated with **-translation** is a single item for read-only and write-only channels. The value is a two-element list for read-write channels; the read translation mode is the first element of the list, and the write translation mode is the second element. As a convenience, when setting the translation mode for a read-write channel you can specify a single value that will apply to both reading and writing. When querying the translation mode of a read-write channel, a two-element list will always be returned. The following values are currently supported: 


 **auto**
 As the input translation mode, **auto** treats any of newline (**lf**), carriage return (**cr**), or carriage return followed by a newline (**crlf**) as the end of line representation. The end of line representation can even change from line-to-line, and all cases are translated to a newline. As the output translation mode, **auto** chooses a platform specific representation; for sockets on all platforms Tcl chooses **crlf**, for all Unix flavors, it chooses **lf**, and for the various flavors of Windows it chooses **crlf**. The default setting for **-translation** is **auto** for both input and output. 

**binary**
 No end-of-line translations are performed. This is nearly identical to **lf** mode, except that in addition **[binary](binary.htm)** mode also sets the end-of-file character to the empty string (which disables it) and sets the encoding to **[binary](binary.htm)** (which disables encoding filtering). See the description of **-eofchar** and **-encoding** for more information. 

**cr**
 The end of a line in the underlying file or device is represented by a single carriage return character. As the input translation mode, **cr** mode converts carriage returns to newline characters. As the output translation mode, **cr** mode translates newline characters to carriage returns. 

**crlf**
 The end of a line in the underlying file or device is represented by a carriage return character followed by a linefeed character. As the input translation mode, **crlf** mode converts carriage-return-linefeed sequences to newline characters. As the output translation mode, **crlf** mode translates newline characters to carriage-return-linefeed sequences. This mode is typically used on Windows platforms and for network connections. 

**lf**
 The end of a line in the underlying file or device is represented by a single newline (linefeed) character. In this mode no translations occur during either input or output. This mode is typically used on UNIX platforms. 






**chan copy** *inputChan outputChan* ?**-size** *size*? ?**-command** *callback*?
 Copy data from the channel *inputChan*, which must have been opened for reading, to the channel *outputChan*, which must have been opened for writing. The **chan copy** command leverages the buffering in the Tcl I/O system to avoid extra copies and to avoid buffering too much data in main memory when copying large files to slow destinations like network sockets.  The **chan copy** command transfers data from *inputChan* until end of file or *size* bytes or characters have been transferred; *size* is in bytes if the two channels are using the same encoding, and is in characters otherwise. If no **-size** argument is given, then the copy goes until end of file. All the data read from *inputChan* is copied to *outputChan*. Without the **-command** option, **chan copy** blocks until the copy is complete and returns the number of bytes or characters (using the same rules as for the **-size** option) written to *outputChan*. 


 The **-command** argument makes **chan copy** work in the background. In this case it returns immediately and the *callback* is invoked later when the copy completes. The *callback* is called with one or two additional arguments that indicates how many bytes were written to *outputChan*. If an error occurred during the background copy, the second argument is the error string associated with the error. With a background copy, it is not necessary to put *inputChan* or *outputChan* into non-blocking mode; the **chan copy** command takes care of that automatically. However, it is necessary to enter the event loop by using the **[vwait](vwait.htm)** command or by using Tk. 


 You are not allowed to do other I/O operations with *inputChan* or *outputChan* during a background **chan copy**. If either *inputChan* or *outputChan* get closed while the copy is in progress, the current copy is stopped and the command callback is *not* made. If *inputChan* is closed, then all data already queued for *outputChan* is written out. 


 Note that *inputChan* can become readable during a background copy. You should turn off any **chan event** or **[fileevent](fileevent.htm)** handlers during a background copy so those handlers do not interfere with the copy. Any I/O attempted by a **chan event** or **[fileevent](fileevent.htm)** handler will get a “channel busy” error. 


 **Chan copy** translates end-of-line sequences in *inputChan* and *outputChan* according to the **-translation** option for these channels (see **chan configure** above). The translations mean that the number of bytes read from *inputChan* can be different than the number of bytes written to *outputChan*. Only the number of bytes written to *outputChan* is reported, either as the return value of a synchronous **chan copy** or as the argument to the callback for an asynchronous **chan copy**. 


**Chan copy** obeys the encodings and character translations configured for the channels. This means that the incoming characters are converted internally first UTF-8 and then into the encoding of the channel **chan copy** writes to (see **chan configure** above for details on the **-encoding** and **-translation** options). No conversion is done if both channels are set to encoding **[binary](binary.htm)** and have matching translations. If only the output channel is set to encoding **[binary](binary.htm)** the system will write the internal UTF-8 representation of the incoming characters. If only the input channel is set to encoding **[binary](binary.htm)** the system will assume that the incoming bytes are valid UTF-8 characters and convert them according to the output encoding. The behaviour of the system for bytes which are not valid UTF-8 characters is undefined in this case. 




**chan create** *mode cmdPrefix*

 This subcommand creates a new script level channel using the command prefix *cmdPrefix* as its handler. Any such channel is called a **reflected** channel. The specified command prefix, **cmdPrefix**, must be a non-empty list, and should provide the API described in the **[refchan](refchan.htm)** manual page. The handle of the new channel is returned as the result of the **chan create** command, and the channel is open. Use either **[close](close.htm)** or **chan close** to remove the channel.  The argument *mode* specifies if the new channel is opened for reading, writing, or both. It has to be a list containing any of the strings “**[read](read.htm)**” or “**write**”. The list must have at least one element, as a channel you can neither write to nor read from makes no sense. The handler command for the new channel must support the chosen mode, or an error is thrown. 


 The command prefix is executed in the global namespace, at the top of call stack, following the appending of arguments as described in the **[refchan](refchan.htm)** manual page. Command resolution happens at the time of the call. Renaming the command, or destroying it means that the next call of a handler method may fail, causing the channel command invoking the handler to fail as well. Depending on the subcommand being invoked, the error message may not be able to explain the reason for that failure. 


 Every channel created with this subcommand knows which interpreter it was created in, and only ever executes its handler command in that interpreter, even if the channel was shared with and/or was moved into a different interpreter. Each reflected channel also knows the thread it was created in, and executes its handler command only in that thread, even if the channel was moved into a different thread. To this end all invocations of the handler are forwarded to the original thread by posting special events to it. This means that the original thread (i.e. the thread that executed the **chan create** command) must have an active event loop, i.e. it must be able to process such events. Otherwise the thread sending them will *block indefinitely*. Deadlock may occur. 


 Note that this permits the creation of a channel whose two endpoints live in two different threads, providing a stream-oriented bridge between these threads. In other words, we can provide a way for regular stream communication between threads instead of having to send commands. 


 When a thread or interpreter is deleted, all channels created with this subcommand and using this thread/interpreter as their computing base are deleted as well, in all interpreters they have been shared with or moved into, and in whatever thread they have been transferred to. While this pulls the rug out under the other thread(s) and/or interpreter(s), this cannot be avoided. Trying to use such a channel will cause the generation of a regular error about unknown channel handles. 


This subcommand is **[safe](safe.htm)** and made accessible to safe interpreters. While it arranges for the execution of arbitrary Tcl code the system also makes sure that the code is always executed within the safe interpreter. 




**chan eof** *channelId*

 Test whether the last input operation on the channel called *channelId* failed because the end of the data stream was reached, returning 1 if end-of-file was reached, and 0 otherwise. 


**chan event** *channelId event* ?*script*?
 Arrange for the Tcl script *script* to be installed as a *file event handler* to be called whenever the channel called *channelId* enters the state described by *event* (which must be either **readable** or **writable**); only one such handler may be installed per event per channel at a time. If *script* is the empty string, the current handler is deleted (this also happens if the channel is closed or the interpreter deleted). If *script* is omitted, the currently installed script is returned (or an empty string if no such handler is installed). The callback is only performed if the event loop is being serviced (e.g. via **[vwait](vwait.htm)** or **[update](update.htm)**).  A file event handler is a binding between a channel and a script, such that the script is evaluated whenever the channel becomes readable or writable. File event handlers are most commonly used to allow data to be received from another process on an event-driven basis, so that the receiver can continue to interact with the user or with other channels while waiting for the data to arrive. If an application invokes **chan gets** or **chan read** on a blocking channel when there is no input data available, the process will block; until the input data arrives, it will not be able to service other events, so it will appear to the user to “freeze up”. With **chan event**, the process can tell when data is present and only invoke **chan gets** or **chan read** when they will not block. 


 A channel is considered to be readable if there is unread data available on the underlying device. A channel is also considered to be readable if there is unread data in an input buffer, except in the special case where the most recent attempt to read from the channel was a **chan gets** call that could not find a complete line in the input buffer. This feature allows a file to be read a line at a time in non-blocking mode using events. A channel is also considered to be readable if an end of file or error condition is present on the underlying file or device. It is important for *script* to check for these conditions and handle them appropriately; for example, if there is no special check for end of file, an infinite loop may occur where *script* reads no data, returns, and is immediately invoked again. 


 A channel is considered to be writable if at least one byte of data can be written to the underlying file or device without blocking, or if an error condition is present on the underlying file or device. Note that client sockets opened in asynchronous mode become writable when they become connected or if the connection fails. 


 Event-driven I/O works best for channels that have been placed into non-blocking mode with the **chan configure** command. In blocking mode, a **chan puts** command may block if you give it more data than the underlying file or device can accept, and a **chan gets** or **chan read** command will block if you attempt to read more data than is ready; no events will be processed while the commands block. In non-blocking mode **chan puts**, **chan read**, and **chan gets** never block. 


The script for a file event is executed at global level (outside the context of any Tcl procedure) in the interpreter in which the **chan event** command was invoked. If an error occurs while executing the script then the command registered with **[interp bgerror](interp.htm)** is used to report the error. In addition, the file event handler is deleted if it ever returns an error; this is done in order to prevent infinite loops due to buggy handlers. 




**chan flush** *channelId*

 Ensures that all pending output for the channel called *channelId* is written.  If the channel is in blocking mode the command does not return until all the buffered output has been flushed to the channel. If the channel is in non-blocking mode, the command may return before all buffered output has been flushed; the remainder will be flushed in the background as fast as the underlying file or device is able to absorb it. 




**chan gets** *channelId* ?*varName*?
 Reads the next line from the channel called *channelId*. If *varName* is not specified, the result of the command will be the line that has been read (without a trailing newline character) or an empty string upon end-of-file or, in non-blocking mode, if the data available is exhausted. If *varName* is specified, the line that has been read will be written to the variable called *varName* and result will be the number of characters that have been read or -1 if end-of-file was reached or, in non-blocking mode, if the data available is exhausted.  If an end-of-file occurs while part way through reading a line, the partial line will be returned (or written into *varName*). When *varName* is not specified, the end-of-file case can be distinguished from an empty line using the **chan eof** command, and the partial-line-but-non-blocking case can be distinguished with the **chan blocked** command. 




**chan names** ?*pattern*?
 Produces a list of all channel names. If *pattern* is specified, only those channel names that match it (according to the rules of **[string match](string.htm)**) will be returned. 


**chan pending** *mode channelId*

 Depending on whether *mode* is **input** or **output**, returns the number of bytes of input or output (respectively) currently buffered internally for *channelId* (especially useful in a readable event callback to impose application-specific limits on input line lengths to avoid a potential denial-of-service attack where a hostile user crafts an extremely long line that exceeds the available memory to buffer it). Returns -1 if the channel was not opened for the mode in question. 

**chan pipe**
 Creates a standalone pipe whose read- and write-side channels are returned as a 2-element list, the first element being the read side and the second the write side. Can be useful e.g. to redirect separately **[stderr](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** and **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)** from a subprocess. To do this, spawn with "2>@" or ">@" redirection operators onto the write side of a pipe, and then immediately close it in the parent. This is necessary to get an EOF on the read side once the child has exited or otherwise closed its output.  Note that the pipe buffering semantics can vary at the operating system level substantially; it is not safe to assume that a write performed on the output side of the pipe will appear instantly to the input side. This is a fundamental difference and Tcl cannot conceal it. The overall stream semantics *are* compatible, so blocking reads and writes will not see most of the differences, but the details of what exactly gets written when are not. This is most likely to show up when using pipelines for testing; care should be taken to ensure that deadlocks do not occur and that potential short reads are allowed for. 




**chan pop** *channelId*

 Removes the topmost transformation from the channel *channelId*, if there is any. If there are no transformations added to *channelId*, this is equivalent to **chan close** of that channel. The result is normally the empty string, but can be an error in some situations (i.e. where the underlying system stream is closed and that results in an error). 


**chan postevent** *channelId eventSpec*

 This subcommand is used by command handlers specified with **chan create**. It notifies the channel represented by the handle *channelId* that the event(s) listed in the *eventSpec* have occurred. The argument has to be a list containing any of the strings **[read](read.htm)** and **write**. The list must contain at least one element as it does not make sense to invoke the command if there are no events to post.  Note that this subcommand can only be used with channel handles that were created/opened by **chan create**. All other channels will cause this subcommand to report an error. 


 As only the Tcl level of a channel, i.e. its command handler, should post events to it we also restrict the usage of this command to the interpreter that created the channel. In other words, posting events to a reflected channel from an interpreter that does not contain it's implementation is not allowed. Attempting to post an event from any other interpreter will cause this subcommand to report an error. 


 Another restriction is that it is not possible to post events that the I/O core has not registered an interest in. Trying to do so will cause the method to throw an error. See the command handler method **watch** described in **[refchan](refchan.htm)**, the document specifying the API of command handlers for reflected channels. 


This command is **[safe](safe.htm)** and made accessible to safe interpreters. It can trigger the execution of **chan event** handlers, whether in the current interpreter or in other interpreters or other threads, even where the event is posted from a safe interpreter and listened for by a trusted interpreter. **Chan event** handlers are *always* executed in the interpreter that set them up. 




**chan push** *channelId cmdPrefix*

 Adds a new transformation on top of the channel *channelId*. The *cmdPrefix* argument describes a list of one or more words which represent a handler that will be used to implement the transformation. The command prefix must provide the API described in the **[transchan](transchan.htm)** manual page. The result of this subcommand is a handle to the transformation. Note that it is important to make sure that the transformation is capable of supporting the channel mode that it is used with or this can make the channel neither readable nor writable. 


**chan puts** ?**-nonewline**? ?*channelId*? *string*

 Writes *string* to the channel named *channelId* followed by a newline character. A trailing newline character is written unless the optional flag **-nonewline** is given. If *channelId* is omitted, the string is written to the standard output channel, **[stdout](https://www.tcl.tk/man/tcl/TclLib/GetStdChan.htm)**.  Newline characters in the output are translated by **chan puts** to platform-specific end-of-line sequences according to the currently configured value of the **-translation** option for the channel (for example, on PCs newlines are normally replaced with carriage-return-linefeed sequences; see **chan configure** above for details). 


 Tcl buffers output internally, so characters written with **chan puts** may not appear immediately on the output file or device; Tcl will normally delay output until the buffer is full or the channel is closed. You can force output to appear immediately with the **chan flush** command. 


When the output buffer fills up, the **chan puts** command will normally block until all the buffered data has been accepted for output by the operating system. If *channelId* is in non-blocking mode then the **chan puts** command will not block even if the operating system cannot accept the data. Instead, Tcl continues to buffer the data and writes it in the background as fast as the underlying file or device can accept it. The application must use the Tcl event loop for non-blocking output to work; otherwise Tcl never finds out that the file or device is ready for more output data. It is possible for an arbitrarily large amount of data to be buffered for a channel in non-blocking mode, which could consume a large amount of memory. To avoid wasting memory, non-blocking I/O should normally be used in an event-driven fashion with the **chan event** command (do not invoke **chan puts** unless you have recently been notified via a file event that the channel is ready for more output data). 




**chan read** *channelId* ?*numChars*?

**chan read** ?**-nonewline**? *channelId*

 In the first form, the result will be the next *numChars* characters read from the channel named *channelId*; if *numChars* is omitted, all characters up to the point when the channel would signal a failure (whether an end-of-file, blocked or other error condition) are read. In the second form (i.e. when *numChars* has been omitted) the flag **-nonewline** may be given to indicate that any trailing newline in the string that has been read should be trimmed.  If *channelId* is in non-blocking mode, **chan read** may not read as many characters as requested: once all available input has been read, the command will return the data that is available rather than blocking for more input. If the channel is configured to use a multi-byte encoding, then there may actually be some bytes remaining in the internal buffers that do not form a complete character. These bytes will not be returned until a complete character is available or end-of-file is reached. The **-nonewline** switch is ignored if the command returns before reaching the end of the file. 


 **Chan read** translates end-of-line sequences in the input into newline characters according to the **-translation** option for the channel (see **chan configure** above for a discussion on the ways in which **chan configure** will alter input). 


 When reading from a serial port, most applications should configure the serial port channel to be non-blocking, like this: 



```
**chan configure** *channelId* **-blocking** *0*.
```
  Then **chan read** behaves much like described above. Note that most serial ports are comparatively slow; it is entirely possible to get a **readable** event for each character read from them. Care must be taken when using **chan read** on blocking serial ports: 


 
**chan read** *channelId numChars*

 In this form **chan read** blocks until *numChars* have been received from the serial port. 


**chan read** *channelId*

 In this form **chan read** blocks until the reception of the end-of-file character, see **chan configure -eofchar**. If there no end-of-file character has been configured for the channel, then **chan read** will block forever. 




**chan seek** *channelId offset* ?*origin*?
 Sets the current access position within the underlying data stream for the channel named *channelId* to be *offset* bytes relative to *origin*. *Offset* must be an integer (which may be negative) and *origin* must be one of the following: 
 **start**
 The new access position will be *offset* bytes from the start of the underlying file or device. 

**current**
 The new access position will be *offset* bytes from the current access position; a negative *offset* moves the access position backwards in the underlying file or device. 

**end**
 The new access position will be *offset* bytes from the end of the file or device. A negative *offset* places the access position before the end of file, and a positive *offset* places the access position after the end of file. 

   The *origin* argument defaults to **start**. 


 **Chan seek** flushes all buffered output for the channel before the command returns, even if the channel is in non-blocking mode. It also discards any buffered and unread input. This command returns an empty string. An error occurs if this command is applied to channels whose underlying file or device does not support seeking. 


 Note that *offset* values are byte offsets, not character offsets. Both **chan seek** and **chan tell** operate in terms of bytes, not characters, unlike **chan read**. 





**chan tell** *channelId*

 Returns a number giving the current access position within the underlying data stream for the channel named *channelId*. This value returned is a byte offset that can be passed to **chan seek** in order to set the channel to a particular position. Note that this value is in terms of bytes, not characters like **chan read**. The value returned is -1 for channels that do not support seeking. 


**chan truncate** *channelId* ?*length*?
 Sets the byte length of the underlying data stream for the channel named *channelId* to be *length* (or to the current byte offset within the underlying data stream if *length* is omitted). The channel is flushed before truncation. 

 Examples
--------

 This opens a file using a known encoding (CP1252, a very common encoding on Windows), searches for a string, rewrites that part, and truncates the file after a further two lines. 

```
set f [open somefile.txt r+]
**chan configure** $f -encoding cp1252
set offset 0

*# Search for string "FOOBAR" in the file*
while {[**chan gets** $f line] >= 0} {
    set idx [string first FOOBAR $line]
    if {$idx > -1} {
        *# Found it; rewrite line*

        **chan seek** $f [expr {$offset + $idx}]
        **chan puts** -nonewline $f BARFOO

        *# Skip to end of following line, and truncate*
        **chan gets** $f
        **chan gets** $f
        **chan truncate** $f

        *# Stop searching the file now*
        break
    }

    *# Save offset of start of next line for later*
    set offset [**chan tell** $f]
}
**chan close** $f
```
  A network server that does echoing of its input line-by-line without preventing servicing of other connections at the same time. 



```
# This is a very simple logger...
proc log {message} {
    **chan puts** stdout $message
}

# This is called whenever a new client connects to the server
proc connect {chan host port} {
    set clientName [format <%s:%d> $host $port]
    log "connection from $clientName"
    **chan configure** $chan -blocking 0 -buffering line
    **chan event** $chan readable [list echoLine $chan $clientName]
}

# This is called whenever either at least one byte of input
# data is available, or the channel was closed by the client.
proc echoLine {chan clientName} {
    **chan gets** $chan line
    if {[**chan eof** $chan]} {
        log "finishing connection from $clientName"
        **chan close** $chan
    } elseif {![**chan blocked** $chan]} {
        # Didn't block waiting for end-of-line
        log "$clientName - $line"
        **chan puts** $chan $line
    }
}

# Create the server socket and enter the event-loop to wait
# for incoming connections...
socket -server connect 12345
vwait forever
```
 See also
--------

 **[close](close.htm)**, **[eof](eof.htm)**, **[fblocked](fblocked.htm)**, **[fconfigure](fconfigure.htm)**, **[fcopy](fcopy.htm)**, **[file](file.htm)**, **[fileevent](fileevent.htm)**, **[flush](flush.htm)**, **[gets](gets.htm)**, **[open](open.htm)**, **[puts](puts.htm)**, **[read](read.htm)**, **[seek](seek.htm)**, **[socket](socket.htm)**, **[tell](tell.htm)**, **[refchan](refchan.htm)**, **[transchan](transchan.htm)** Copyright © 2005-2006 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/chan.htm>

pkgMkIndex
==========

  
[NAME](pkgmkindex.htm#M2) pkg\_mkIndex — Build an index for automatic loading of packages 
[SYNOPSIS](pkgmkindex.htm#M3) 
[DESCRIPTION](pkgmkindex.htm#M4) 
[OPTIONS](pkgmkindex.htm#M5)  
[**-direct**](pkgmkindex.htm#M6) 
[**-lazy**](pkgmkindex.htm#M7) 
[**-load** *pkgPat*](pkgmkindex.htm#M8) 
[**-verbose**](pkgmkindex.htm#M9) 
[**--**](pkgmkindex.htm#M10) 




 
[PACKAGES AND THE AUTO-LOADER](pkgmkindex.htm#M11) 
[HOW IT WORKS](pkgmkindex.htm#M12) 
[DIRECT LOADING](pkgmkindex.htm#M13) 
[COMPLEX CASES](pkgmkindex.htm#M14) 
[SEE ALSO](pkgmkindex.htm#M15) 
[KEYWORDS](pkgmkindex.htm#M16) 









 Name
----

 pkg\_mkIndex — Build an index for automatic loading of packages Synopsis
--------

 **pkg\_mkIndex** ?*options...*? *dir* ?*pattern pattern ...*?  
 Description
-----------

 **Pkg\_mkIndex** is a utility procedure that is part of the standard Tcl library. It is used to create index files that allow packages to be loaded automatically when **[package require](package.htm)** commands are executed. To use **pkg\_mkIndex**, follow these steps: 
1. Create the package(s). Each package may consist of one or more Tcl script files or binary files. Binary files must be suitable for loading with the **[load](load.htm)** command with a single argument; for example, if the file is **test.so** it must be possible to load this file with the command **load test.so**. Each script file must contain a **[package provide](package.htm)** command to declare the package and version number, and each binary file must contain a call to **[Tcl\_PkgProvide](https://www.tcl.tk/man/tcl/TclLib/PkgRequire.htm)**.
2. Create the index by invoking **pkg\_mkIndex**. The *dir* argument gives the name of a directory and each *pattern* argument is a **[glob](glob.htm)**-style pattern that selects script or binary files in *dir*. The default pattern is **\*.tcl** and **\*.[info sharedlibextension]**.  **Pkg\_mkIndex** will create a file **pkgIndex.tcl** in *dir* with package information about all the files given by the *pattern* arguments. It does this by loading each file into a slave interpreter and seeing what packages and new commands appear (this is why it is essential to have **[package provide](package.htm)** commands or **[Tcl\_PkgProvide](https://www.tcl.tk/man/tcl/TclLib/PkgRequire.htm)** calls in the files, as described above). If you have a package split among scripts and binary files, or if you have dependencies among files, you may have to use the **-load** option or adjust the order in which **pkg\_mkIndex** processes the files. See **[COMPLEX CASES](#M14)** below.
3. Install the package as a subdirectory of one of the directories given by the **[tcl\_pkgPath](tclvars.htm)** variable. If **$tcl\_pkgPath** contains more than one directory, machine-dependent packages (e.g., those that contain binary shared libraries) should normally be installed under the first directory and machine-independent packages (e.g., those that contain only Tcl scripts) should be installed under the second directory. The subdirectory should include the package's script and/or binary files as well as the **pkgIndex.tcl** file. As long as the package is installed as a subdirectory of a directory in **$tcl\_pkgPath** it will automatically be found during **[package require](package.htm)** commands.  If you install the package anywhere else, then you must ensure that the directory containing the package is in the **[auto\_path](tclvars.htm)** global variable or an immediate subdirectory of one of the directories in **[auto\_path](tclvars.htm)**. **[Auto\_path](tclvars.htm)** contains a list of directories that are searched by both the auto-loader and the package loader; by default it includes **$tcl\_pkgPath**. The package loader also checks all of the subdirectories of the directories in **[auto\_path](tclvars.htm)**. You can add a directory to **[auto\_path](tclvars.htm)** explicitly in your application, or you can add the directory to your **TCLLIBPATH** environment variable: if this environment variable is present, Tcl initializes **[auto\_path](tclvars.htm)** from it during application startup.
4. Once the above steps have been taken, all you need to do to use a package is to invoke **[package require](package.htm)**. For example, if versions 2.1, 2.3, and 3.1 of package **Test** have been indexed by **pkg\_mkIndex**, the command **package require Test** will make version 3.1 available and the command **package require -exact Test 2.1** will make version 2.1 available. There may be many versions of a package in the various index files in **[auto\_path](tclvars.htm)**, but only one will actually be loaded in a given interpreter, based on the first call to **[package require](package.htm)**. Different versions of a package may be loaded in different interpreters.

 Options
-------

 The optional switches are: 
 **-direct**
 The generated index will implement direct loading of the package upon **[package require](package.htm)**. This is the default. 

**-lazy**
 The generated index will manage to delay loading the package until the use of one of the commands provided by the package, instead of loading it immediately upon **[package require](package.htm)**. This is not compatible with the use of *auto\_reset*, and therefore its use is discouraged. 


**-load** *pkgPat*

 The index process will pre-load any packages that exist in the current interpreter and match *pkgPat* into the slave interpreter used to generate the index. The pattern match uses string match rules, but without making case distinctions. See **[COMPLEX CASES](#M14)** below. 

**-verbose**
 Generate output during the indexing process. Output is via the **tclLog** procedure, which by default prints to stderr. 

**--**
 End of the flags, in case *dir* begins with a dash. 

 Packages and the auto-loader
----------------------------

 The package management facilities overlap somewhat with the auto-loader, in that both arrange for files to be loaded on-demand. However, package management is a higher-level mechanism that uses the auto-loader for the last step in the loading process. It is generally better to index a package with **pkg\_mkIndex** rather than **[auto\_mkindex](library.htm)** because the package mechanism provides version control: several versions of a package can be made available in the index files, with different applications using different versions based on **[package require](package.htm)** commands. In contrast, **[auto\_mkindex](library.htm)** does not understand versions so it can only handle a single version of each package. It is probably not a good idea to index a given package with both **pkg\_mkIndex** and **[auto\_mkindex](library.htm)**. If you use **pkg\_mkIndex** to index a package, its commands cannot be invoked until **[package require](package.htm)** has been used to select a version; in contrast, packages indexed with **[auto\_mkindex](library.htm)** can be used immediately since there is no version control. How it works
------------

 **Pkg\_mkIndex** depends on the **[package unknown](package.htm)** command, the **[package ifneeded](package.htm)** command, and the auto-loader. The first time a **[package require](package.htm)** command is invoked, the **[package unknown](package.htm)** script is invoked. This is set by Tcl initialization to a script that evaluates all of the **pkgIndex.tcl** files in the **[auto\_path](tclvars.htm)**. The **pkgIndex.tcl** files contain **[package ifneeded](package.htm)** commands for each version of each available package; these commands invoke **[package provide](package.htm)** commands to announce the availability of the package, and they setup auto-loader information to load the files of the package. If the **-lazy** flag was provided when the **pkgIndex.tcl** was generated, a given file of a given version of a given package is not actually loaded until the first time one of its commands is invoked. Thus, after invoking **[package require](package.htm)** you may not see the package's commands in the interpreter, but you will be able to invoke the commands and they will be auto-loaded. Direct loading
--------------

 Some packages, for instance packages which use namespaces and export commands or those which require special initialization, might select that their package files be loaded immediately upon **[package require](package.htm)** instead of delaying the actual loading to the first use of one of the package's command. This is the default mode when generating the package index. It can be overridden by specifying the **-lazy** argument. Complex cases
-------------

 Most complex cases of dependencies among scripts and binary files, and packages being split among scripts and binary files are handled OK. However, you may have to adjust the order in which files are processed by **pkg\_mkIndex**. These issues are described in detail below.  If each script or file contains one package, and packages are only contained in one file, then things are easy. You simply specify all files to be indexed in any order with some glob patterns. 


 In general, it is OK for scripts to have dependencies on other packages. If scripts contain **[package require](package.htm)** commands, these are stubbed out in the interpreter used to process the scripts, so these do not cause problems. If scripts call into other packages in global code, these calls are handled by a stub **[unknown](unknown.htm)** command. However, if scripts make variable references to other package's variables in global code, these will cause errors. That is also bad coding style. 


 If binary files have dependencies on other packages, things can become tricky because it is not possible to stub out C-level APIs such as **[Tcl\_PkgRequire](https://www.tcl.tk/man/tcl/TclLib/PkgRequire.htm)** API when loading a binary file. For example, suppose the BLT package requires Tk, and expresses this with a call to **[Tcl\_PkgRequire](https://www.tcl.tk/man/tcl/TclLib/PkgRequire.htm)** in its **Blt\_Init** routine. To support this, you must run **pkg\_mkIndex** in an interpreter that has Tk loaded. You can achieve this with the **-load** *pkgPat* option. If you specify this option, **pkg\_mkIndex** will load any packages listed by **[info loaded](info.htm)** and that match *pkgPat* into the interpreter used to process files. In most cases this will satisfy the **[Tcl\_PkgRequire](https://www.tcl.tk/man/tcl/TclLib/PkgRequire.htm)** calls made by binary files. 


 If you are indexing two binary files and one depends on the other, you should specify the one that has dependencies last. This way the one without dependencies will get loaded and indexed, and then the package it provides will be available when the second file is processed. You may also need to load the first package into the temporary interpreter used to create the index by using the **-load** flag; it will not hurt to specify package patterns that are not yet loaded. 


 If you have a package that is split across scripts and a binary file, then you should avoid the **-load** flag. The problem is that if you load a package before computing the index it masks any other files that provide part of the same package. If you must use **-load**, then you must specify the scripts first; otherwise the package loaded from the binary file may mask the package defined by the scripts. 


See also
--------

 **[package](package.htm)** Copyright © 1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/pkgMkIndex.htm>

proc
====

 Name
----

 proc — Create a Tcl procedure Synopsis
--------

 **proc** *name args body*  
 Description
-----------

 The **proc** command creates a new Tcl procedure named *name*, replacing any existing command or procedure there may have been by that name. Whenever the new command is invoked, the contents of *body* will be executed by the Tcl interpreter. Normally, *name* is unqualified (does not include the names of any containing namespaces), and the new procedure is created in the current namespace. If *name* includes any namespace qualifiers, the procedure is created in the specified namespace. *Args* specifies the formal arguments to the procedure. It consists of a list, possibly empty, each of whose elements specifies one argument. Each argument specifier is also a list with either one or two fields. If there is only a single field in the specifier then it is the name of the argument; if there are two fields, then the first is the argument name and the second is its default value. Arguments with default values that are followed by non-defaulted arguments become required arguments; enough actual arguments must be supplied to allow all arguments up to and including the last required formal argument.  When *name* is invoked a local variable will be created for each of the formal arguments to the procedure; its value will be the value of corresponding argument in the invoking command or the argument's default value. Actual arguments are assigned to formal arguments strictly in order. Arguments with default values need not be specified in a procedure invocation. However, there must be enough actual arguments for all the formal arguments that do not have defaults, and there must not be any extra actual arguments. Arguments with default values that are followed by non-defaulted arguments become de-facto required arguments, though this may change in a future version of Tcl; portable code should ensure that all optional arguments come after all required arguments. 


 There is one special case to permit procedures with variable numbers of arguments. If the last formal argument has the name “**args**”, then a call to the procedure may contain more actual arguments than the procedure has formal arguments. In this case, all of the actual arguments starting at the one that would be assigned to **args** are combined into a list (as if the **[list](list.htm)** command had been used); this combined value is assigned to the local variable **args**. 


 When *body* is being executed, variable names normally refer to local variables, which are created automatically when referenced and deleted when the procedure returns. One local variable is automatically created for each of the procedure's arguments. Other variables can only be accessed by invoking one of the **[global](global.htm)**, **[variable](variable.htm)**, **[upvar](upvar.htm)** or **[namespace upvar](namespace.htm)** commands. The current namespace when *body* is executed will be the namespace that the procedure's name exists in, which will be the namespace that it was created in unless it has been changed with **[rename](rename.htm)**. 


 The **proc** command returns an empty string. When a procedure is invoked, the procedure's return value is the value specified in a **[return](return.htm)** command. If the procedure does not execute an explicit **[return](return.htm)**, then its return value is the value of the last command executed in the procedure's body. If an error occurs while executing the procedure body, then the procedure-as-a-whole will return that same error. 


Examples
--------

 This is a procedure that takes two arguments and prints both their sum and their product. It also returns the string “OK” to the caller as an explicit result. 

```
**proc** printSumProduct {x y} {
    set sum [expr {$x + $y}]
    set prod [expr {$x * $y}]
    puts "sum is $sum, product is $prod"
    return "OK"
}
```
  This is a procedure that accepts arbitrarily many arguments and prints them out, one by one. 



```
**proc** printArguments args {
    foreach arg $args {
        puts $arg
    }
}
```
  This procedure is a bit like the **[incr](incr.htm)** command, except it multiplies the contents of the named variable by the value, which defaults to **2**: 



```
**proc** mult {varName {multiplier 2}} {
    upvar 1 $varName var
    set var [expr {$var * $multiplier}]
}
```
 See also
--------

 **[info](info.htm)**, **[unknown](unknown.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1996 Sun Microsystems, Inc. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/proc.htm>

lmap
====

 Name
----

 lmap — Iterate over all elements in one or more lists and collect results Synopsis
--------

 **lmap** *varname list body*  
 **lmap** *varlist1 list1* ?*varlist2 list2 ...*? *body*  
 Description
-----------

 The **lmap** command implements a loop where the loop variable(s) take on values from one or more lists, and the loop returns a list of results collected from each iteration.  In the simplest case there is one loop variable, *varname*, and one list, *list*, that is a list of values to assign to *varname*. The *body* argument is a Tcl script. For each element of *list* (in order from first to last), **lmap** assigns the contents of the element to *varname* as if the **[lindex](lindex.htm)** command had been used to extract the element, then calls the Tcl interpreter to execute *body*. If execution of the body completes normally then the result of the body is appended to an accumulator list. **lmap** returns the accumulator list. 


 In the general case there can be more than one value list (e.g., *list1* and *list2*), and each value list can be associated with a list of loop variables (e.g., *varlist1* and *varlist2*). During each iteration of the loop the variables of each *varlist* are assigned consecutive values from the corresponding *list*. Values in each *list* are used in order from first to last, and each value is used exactly once. The total number of loop iterations is large enough to use up all the values from all the value lists. If a value list does not contain enough elements for each of its loop variables in each iteration, empty values are used for the missing elements. 


 The **[break](break.htm)** and **[continue](continue.htm)** statements may be invoked inside *body*, with the same effect as in the **[for](for.htm)** and **[foreach](foreach.htm)** commands. In these cases the body does not complete normally and the result is not appended to the accumulator list. 


Examples
--------

 Zip lists together: 

```
set list1 {a b c d}
set list2 {1 2 3 4}
set zipped [**lmap** a $list1 b $list2 {list $a $b}]
# The value of zipped is "{a 1} {b 2} {c 3} {d 4}"
```
  Filter a list to remove odd values: 



```
set values {1 2 3 4 5 6 7 8}
proc isEven {n} {expr {($n % 2) == 0}}
set goodOnes [**lmap** x $values {expr {
    [isEven $x] ? $x : [continue]
}}]
# The value of goodOnes is "2 4 6 8"
```
  Take a prefix from a list based on the contents of the list: 



```
set values {8 7 6 5 4 3 2 1}
proc isGood {counter} {expr {$n > 3}}
set prefix [**lmap** x $values {expr {
    [isGood $x] ? $x : [break]
}}]
# The value of prefix is "8 7 6 5 4"
```
 See also
--------

 **[break](break.htm)**, **[continue](continue.htm)**, **[for](for.htm)**, **[foreach](foreach.htm)**, **[while](while.htm)** Copyright © 2012 Trevor Davel 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/lmap.htm>

clock
=====

  
[NAME](clock.htm#M2) clock — Obtain and manipulate dates and times 
[SYNOPSIS](clock.htm#M3) 
[DESCRIPTION](clock.htm#M4)  
[**clock add** *timeVal* ?*count unit...*? ?*-option value*?](clock.htm#M5) 
[**clock clicks** ?*-option*?](clock.htm#M6) 
[**clock format** *timeVal* ?*-option value*...?](clock.htm#M7) 
[**clock microseconds**](clock.htm#M8) 
[**clock milliseconds**](clock.htm#M9) 
[**clock scan** *inputString* ?*-option value*...?](clock.htm#M10) 
[**clock seconds**](clock.htm#M11) 






 
[PARAMETERS](clock.htm#M12)  
[*count*](clock.htm#M13) 
[*timeVal*](clock.htm#M14) 
[*unit*](clock.htm#M15) 


 
[OPTIONS](clock.htm#M16)  
[**-base** time](clock.htm#M17) 
[**-format** format](clock.htm#M18) 
[**-gmt** boolean](clock.htm#M19) 
[**-locale** localeName](clock.htm#M20) 
[**-timezone** zoneName](clock.htm#M21) 




 
[CLOCK ARITHMETIC](clock.htm#M22) 
[HIGH RESOLUTION TIMERS](clock.htm#M23) 
[FORMATTING TIMES](clock.htm#M24) 
[SCANNING TIMES](clock.htm#M25) 
[FORMAT GROUPS](clock.htm#M26)  
[**%a**](clock.htm#M27) 
[**%A**](clock.htm#M28) 
[**%b**](clock.htm#M29) 
[**%B**](clock.htm#M30) 
[**%c**](clock.htm#M31) 
[**%C**](clock.htm#M32) 
[**%d**](clock.htm#M33) 
[**%D**](clock.htm#M34) 
[**%e**](clock.htm#M35) 
[**%Ec**](clock.htm#M36) 
[**%EC**](clock.htm#M37) 
[**%EE**](clock.htm#M38) 
[**%Ex**](clock.htm#M39) 
[**%EX**](clock.htm#M40) 
[**%Ey**](clock.htm#M41) 
[**%EY**](clock.htm#M42) 
[**%g**](clock.htm#M43) 
[**%G**](clock.htm#M44) 
[**%h**](clock.htm#M45) 
[**%H**](clock.htm#M46) 
[**%I**](clock.htm#M47) 
[**%j**](clock.htm#M48) 
[**%J**](clock.htm#M49) 
[**%k**](clock.htm#M50) 
[**%l**](clock.htm#M51) 
[**%m**](clock.htm#M52) 
[**%M**](clock.htm#M53) 
[**%N**](clock.htm#M54) 
[**%Od**, **%Oe**, **%OH**, **%OI**, **%Ok**, **%Ol**, **%Om**, **%OM**, **%OS**, **%Ou**, **%Ow**, **%Oy**](clock.htm#M55) 
[**%p**](clock.htm#M56) 
[**%P**](clock.htm#M57) 
[**%Q**](clock.htm#M58) 
[**%r**](clock.htm#M59) 
[**%R**](clock.htm#M60) 
[**%s**](clock.htm#M61) 
[**%S**](clock.htm#M62) 
[**%t**](clock.htm#M63) 
[**%T**](clock.htm#M64) 
[**%u**](clock.htm#M65) 
[**%U**](clock.htm#M66) 
[**%V**](clock.htm#M67) 
[**%w**](clock.htm#M68) 
[**%W**](clock.htm#M69) 
[**%x**](clock.htm#M70) 
[**%X**](clock.htm#M71) 
[**%y**](clock.htm#M72) 
[**%Y**](clock.htm#M73) 
[**%z**](clock.htm#M74) 
[**%Z**](clock.htm#M75) 
[**%%**](clock.htm#M76) 
[**%+**](clock.htm#M77) 


















































 
[TIME ZONES](clock.htm#M78) 
[LOCALIZATION](clock.htm#M79) 
[FREE FORM SCAN](clock.htm#M80)  
[*time*](clock.htm#M81) 
[*date*](clock.htm#M82) 
[*ISO 8601 point-in-time*](clock.htm#M83) 
[*relative time*](clock.htm#M84) 



 
[SEE ALSO](clock.htm#M85) 
[KEYWORDS](clock.htm#M86) 
[COPYRIGHT](clock.htm#M87) 















 Name
----

 clock — Obtain and manipulate dates and times Synopsis
--------

 package require **Tcl 8.5**  
 **clock add** *timeVal* ?*count unit...*? ?*-option value*?  
 **clock clicks** ?*-option*?  
 **clock format** *timeVal* ?*-option value*...?  
 **clock microseconds**  
 **clock milliseconds**  
 **clock scan** *inputString* ?*-option value*...?  
 **clock seconds**  
 Description
-----------

 The **clock** command performs several operations that obtain and manipulate values that represent times. The command supports several subcommands that determine what action is carried out by the command. 
 
**clock add** *timeVal* ?*count unit...*? ?*-option value*?
 Adds a (possibly negative) offset to a time that is expressed as an integer number of seconds. See **[CLOCK ARITHMETIC](#M22)** for a full description. 


**clock clicks** ?*-option*?
 If no *-option* argument is supplied, returns a high-resolution time value as a system-dependent integer value. The unit of the value is system-dependent but should be the highest resolution clock available on the system such as a CPU cycle counter. See **[HIGH RESOLUTION TIMERS](#M23)** for a full description.  If the *-option* argument is **-milliseconds**, then the command is synonymous with **clock milliseconds** (see below). This usage is obsolete, and **clock milliseconds** is to be considered the preferred way of obtaining a count of milliseconds. 


If the *-option* argument is **-microseconds**, then the command is synonymous with **clock microseconds** (see below). This usage is obsolete, and **clock microseconds** is to be considered the preferred way of obtaining a count of microseconds. 




**clock format** *timeVal* ?*-option value*...?
 Formats a time that is expressed as an integer number of seconds into a format intended for consumption by users or external programs. See **[FORMATTING TIMES](#M24)** for a full description. 

**clock microseconds**
 Returns the current time as an integer number of microseconds. See **[HIGH RESOLUTION TIMERS](#M23)** for a full description. 

**clock milliseconds**
 Returns the current time as an integer number of milliseconds. See **[HIGH RESOLUTION TIMERS](#M23)** for a full description. 


**clock scan** *inputString* ?*-option value*...?
 Scans a time that is expressed as a character string and produces an integer number of seconds. See **[SCANNING TIMES](#M25)** for a full description. 

**clock seconds**
 Returns the current time as an integer number of seconds. 

 ### Parameters

  *count*
 An integer representing a count of some unit of time. See **[CLOCK ARITHMETIC](#M22)** for the details. 

*timeVal*
 An integer value passed to the **clock** command that represents an absolute time as a number of seconds from the *epoch time* of 1 January 1970, 00:00 UTC. Note that the count of seconds does not include any leap seconds; seconds are counted as if each UTC day has exactly 86400 seconds. Tcl responds to leap seconds by speeding or slowing its clock by a tiny fraction for some minutes until it is back in sync with UTC; its data model does not represent minutes that have 59 or 61 seconds. 

*unit*
 One of the words, **seconds**, **minutes**, **hours**, **days**, **weeks**, **months**, or **years**, or any unique prefix of such a word. Used in conjunction with *count* to identify an interval of time, for example, *3 seconds* or *1 year*. 

 ### Options

  
**-base** time
 Specifies that any relative times present in a **clock scan** command are to be given relative to *time*. *time* must be expressed as a count of nominal seconds from the epoch time of 1 January 1970, 00:00 UTC. 


**-format** format
 Specifies the desired output format for **clock format** or the expected input format for **clock scan**. The *format* string consists of any number of characters other than the per-cent sign (“**%**”) interspersed with any number of *format groups*, which are two-character sequences beginning with the per-cent sign. The permissible format groups, and their interpretation, are described under **[FORMAT GROUPS](#M26)**.  On **clock format**, the default format is 



```
%a %b %d %H:%M:%S %Z %Y
```
 On **clock scan**, the lack of a **-format** option indicates that a “free format scan” is requested; see **[FREE FORM SCAN](#M80)** for a description of what happens. 




**-gmt** boolean
 If *boolean* is true, specifies that a time specified to **clock add**, **clock format** or **clock scan** should be processed in UTC. If *boolean* is false, the processing defaults to the local time zone. This usage is obsolete; the correct current usage is to specify the UTC time zone with “**-timezone** *:UTC*” or any of the equivalent ways to specify it. 


**-locale** localeName
 Specifies that locale-dependent scanning and formatting (and date arithmetic for dates preceding the adoption of the Gregorian calendar) is to be done in the locale identified by *localeName*. The locale name may be any of the locales acceptable to the **[msgcat](msgcat.htm)** package, or it may be the special name *system*, which represents the current locale of the process, or the null string, which represents Tcl's default locale.  The effect of locale on scanning and formatting is discussed in the descriptions of the individual format groups under **[FORMAT GROUPS](#M26)**. The effect of locale on clock arithmetic is discussed under **[CLOCK ARITHMETIC](#M22)**. 




**-timezone** zoneName
 Specifies that clock arithmetic, formatting, and scanning are to be done according to the rules for the time zone specified by *zoneName*. The permissible values, and their interpretation, are discussed under **[TIME ZONES](#M78)**. On subcommands that expect a **-timezone** argument, the default is to use the *current time zone*. The current time zone is determined, in order of preference, by: 
1. the environment variable **TCL\_TZ**.
2. the environment variable **TZ**.
3. on Windows systems, the time zone settings from the Control Panel.



  If none of these is present, the C **localtime** and **mktime** functions are used to attempt to convert times between local and Greenwich. On 32-bit systems, this approach is likely to have bugs, particularly for times that lie outside the window (approximately the years 1902 to 2037) that can be represented in a 32-bit integer. 


Clock arithmetic
----------------

 The **clock add** command performs clock arithmetic on a value (expressed as nominal seconds from the epoch time of 1 January 1970, 00:00 UTC) given as its first argument. The remaining arguments (other than the possible **-timezone**, **-locale** and **-gmt** options) are integers and keywords in alternation, where the keywords are chosen from **seconds**, **minutes**, **hours**, **days**, **weeks**, **months**, or **years**, or any unique prefix of such a word.  Addition of seconds, minutes and hours is fairly straightforward; the given time increment (times sixty for minutes, or 3600 for hours) is simply added to the *timeVal* given to the **clock add** command. The result is interpreted as a nominal number of seconds from the Epoch. 


 Surprising results may be obtained when crossing a point at which a leap second is inserted or removed; the **clock add** command simply ignores leap seconds and therefore assumes that times come in sequence, 23:59:58, 23:59:59, 00:00:00. (This assumption is handled by the fact that Tcl's model of time reacts to leap seconds by speeding or slowing the clock by a minuscule amount until Tcl's time is back in step with the world. 


 The fact that adding and subtracting hours is defined in terms of absolute time means that it will add fixed amounts of time in time zones that observe summer time (Daylight Saving Time). For example, the following code sets the value of **x** to **04:00:00** because the clock has changed in the interval in question. 



```
set s [**clock scan** {2004-10-30 05:00:00} \
           -format {%Y-%m-%d %H:%M:%S} \
           -timezone :America/New_York]
set a [**clock add** $s 24 hours -timezone :America/New_York]
set x [**clock format** $a \
           -format {%H:%M:%S} -timezone :America/New_York]
```
  Adding and subtracting days and weeks is accomplished by converting the given time to a calendar day and time of day in the appropriate time zone and locale. The requisite number of days (weeks are converted to days by multiplying by seven) is added to the calendar day, and the date and time are then converted back to a count of seconds from the epoch time. 


 Adding and subtracting a given number of days across the point that the time changes at the start or end of summer time (Daylight Saving Time) results in the *same local time* on the day in question. For instance, the following code sets the value of **x** to **05:00:00**. 



```
set s [**clock scan** {2004-10-30 05:00:00} \
           -format {%Y-%m-%d %H:%M:%S} \
           -timezone :America/New_York]
set a [**clock add** $s 1 day -timezone :America/New_York]
set x [**clock format** $a \
           -format {%H:%M:%S} -timezone :America/New_York]
```
  In cases of ambiguity, where the same local time happens twice on the same day, the earlier time is used. In cases where the conversion yields an impossible time (for instance, 02:30 during the Spring Daylight Saving Time change using US rules), the time is converted as if the clock had not changed. Thus, the following code will set the value of **x** to **03:30:00**. 



```
set s [**clock scan** {2004-04-03 02:30:00} \
           -format {%Y-%m-%d %H:%M:%S} \
           -timezone :America/New_York]
set a [**clock add** $s 1 day -timezone :America/New_York]
set x [**clock format** $a \
           -format {%H:%M:%S} -timezone :America/New_York]
```
  Adding a given number of days or weeks works correctly across the conversion between the Julian and Gregorian calendars; the omitted days are skipped. The following code sets **z** to **1752-09-14**. 



```
set x [**clock scan** 1752-09-02 -format %Y-%m-%d -locale en_US]
set y [**clock add** $x 1 day -locale en_US]
set z [**clock format** $y -format %Y-%m-%d -locale en_US]
```
  In the bizarre case that adding the given number of days yields a date that does not exist because it falls within the dropped days of the Julian-to-Gregorian conversion, the date is converted as if it was on the Julian calendar. 


 Adding a number of months, or a number of years, is similar; it converts the given time to a calendar date and time of day. It then adds the requisite number of months or years, and reconverts the resulting date and time of day to an absolute time. 


 If the resulting date is impossible because the month has too few days (for example, when adding 1 month to 31 January), the last day of the month is substituted. Thus, adding 1 month to 31 January will result in 28 February in a common year or 29 February in a leap year. 


 The rules for handling anomalies relating to summer time and to the Gregorian calendar are the same when adding/subtracting months and years as they are when adding/subtracting days and weeks. 


 If multiple *count unit* pairs are present on the command, they are evaluated consecutively, from left to right. 


High resolution timers
----------------------

 Most of the subcommands supported by the **clock** command deal with times represented as a count of seconds from the epoch time, and this is the representation that **clock seconds** returns. There are three exceptions, which are all intended for use where higher-resolution times are required. **clock milliseconds** returns the count of milliseconds from the epoch time, and **clock microseconds** returns the count of microseconds from the epoch time. In addition, there is a **clock clicks** command that returns a platform-dependent high-resolution timer. Unlike **clock seconds** and **clock milliseconds**, the value of **clock clicks** is not guaranteed to be tied to any fixed epoch; it is simply intended to be the most precise interval timer available, and is intended only for relative timing studies such as benchmarks. Formatting times
----------------

 The **clock format** command produces times for display to a user or writing to an external medium. The command accepts times that are expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC, as returned by **clock seconds**, **clock scan**, **clock add**, **[file atime](file.htm)** or **[file mtime](file.htm)**.  If a **-format** option is present, the following argument is a string that specifies how the date and time are to be formatted. The string consists of any number of characters other than the per-cent sign (“**%**”) interspersed with any number of *format groups*, which are two-character sequences beginning with the per-cent sign. The permissible format groups, and their interpretation, are described under **[FORMAT GROUPS](#M26)**. 


 If a **-timezone** option is present, the following argument is a string that specifies the time zone in which the date and time are to be formatted. As an alternative to “**-timezone** *:UTC*”, the obsolete usage “**-gmt** *true*” may be used. See **[TIME ZONES](#M78)** for the permissible variants for the time zone. 


 If a **-locale** option is present, the following argument is a string that specifies the locale in which the time is to be formatted, in the same format that is used for the **[msgcat](msgcat.htm)** package. Note that the default, if **-locale** is not specified, is the root locale **{}** rather than the current locale. The current locale may be obtained by using **-locale** **current**. In addition, some platforms support a **system** locale that reflects the user's current choices. For instance, on Windows, the format that the user has selected from dates and times in the Control Panel can be obtained by using the **system** locale. On platforms that do not define a user selection of date and time formats separate from **LC\_TIME**, **-locale** **system** is synonymous with **-locale** **current**. 


Scanning times
--------------

 The **clock scan** command accepts times that are formatted as strings and converts them to counts of seconds from the epoch time of 1 January 1970, 00:00 UTC. It normally takes a **-format** option that is followed by a string describing the expected format of the input. (See **[FREE FORM SCAN](#M80)** for the effect of **clock scan** without such an argument.) The string consists of any number of characters other than the per-cent sign (“**%**”), interspersed with any number of *format groups*, which are two-character sequences beginning with the per-cent sign. The permissible format groups, and their interpretation, are described under **[FORMAT GROUPS](#M26)**.  If a **-timezone** option is present, the following argument is a string that specifies the time zone in which the date and time are to be interpreted. As an alternative to **-timezone** *:UTC*, the obsolete usage **-gmt** *true* may be used. See **[TIME ZONES](#M78)** for the permissible variants for the time zone. 


 If a **-locale** option is present, the following argument is a string that specifies the locale in which the time is to be interpreted, in the same format that is used for the **[msgcat](msgcat.htm)** package. Note that the default, if **-locale** is not specified, is the root locale **{}** rather than the current locale. The current locale may be obtained by using **-locale** **current**. In addition, some platforms support a **system** locale that reflects the user's current choices. For instance, on Windows, the format that the user has selected from dates and times in the Control Panel can be obtained by using the **system** locale. On platforms that do not define a user selection of date and time formats separate from **LC\_TIME**, **-locale** **system** is synonymous with **-locale** **current**. 


 If a **-base** option is present, the following argument is a time (expressed in seconds from the epoch time) that is used as a *base time* for interpreting relative times. If no **-base** option is present, the base time is the current time. 


 Scanning of times in fixed format works by determining three things: the date, the time of day, and the time zone. These three are then combined into a point in time, which is returned as the number of seconds from the epoch. 


 Before scanning begins, the format string is preprocessed to replace **%c**, **%Ec**, **%x**, **%Ex**, **%X**. **%Ex**, **%r**, **%R**, **%T**, **%D**, **%EY** and **%+** format groups with counterparts that are appropriate to the current locale and contain none of the above groups. For instance, **%D** will (in the **en\_US** locale) be replaced with **%m/%d/%Y**. 


 The date is determined according to the fields that are present in the preprocessed format string. In order of preference: 


1. If the string contains a **%s** format group, representing seconds from the epoch, that group is used to determine the date.
2. If the string contains a **%J** format group, representing the Julian Day Number, that group is used to determine the date.
3. If the string contains a complete set of format groups specifying century, year, month, and day of month; century, year, and day of year; or ISO8601 fiscal year, week of year, and day of week; those groups are combined and used to determine the date. If more than one complete set is present, the one at the rightmost position in the string is used.
4. If the string lacks a century but contains a set of format groups specifying year of century, month and day of month; year of century and day of year; or two-digit ISO8601 fiscal year, week of year, and day of week; those groups are combined and used to determine the date. If more than one complete set is present, the one at the rightmost position in the string is used. The year is presumed to lie in the range 1938 to 2037 inclusive.
5. If the string entirely lacks any specification for the year (or contains the year only on the locale's alternative calendar) and contains a set of format groups specifying month and day of month, day of year, or week of year and day of week, those groups are combined and used to determine the date. If more than one complete set is present, the one at the rightmost position in the string is used. The year is determined by interpreting the base time in the given time zone.
6. If the string contains none of the above sets, but has a day of the month or day of the week, the day of the month or day of the week are used to determine the date by interpreting the base time in the given time zone and returning the given day of the current week or month. (The week runs from Monday to Sunday, ISO8601-fashion.) If both day of month and day of week are present, the day of the month takes priority.
7. If none of the above rules results in a usable date, the date of the base time in the given time zone is used.

  The time is also determined according to the fields that are present in the preprocessed format string. In order of preference: 


1. If the string contains a **%s** format group, representing seconds from the epoch, that group determines the time of day.
2. If the string contains either an hour on the 24-hour clock or an hour on the 12-hour clock plus an AM/PM indicator, that hour determines the hour of the day. If the string further contains a group specifying the minute of the hour, that group combines with the hour. If the string further contains a group specifying the second of the minute, that group combines with the hour and minute.
3. If the string contains neither a **%s** format group nor a group specifying the hour of the day, then midnight (**00:00**, the start of the given date) is used. The time zone is determined by either the **-timezone** or **-gmt** options, or by using the current time zone.

  If a format string lacks a **%z** or **%Z** format group, it is possible for the time to be ambiguous because it appears twice in the same day, once without and once with Daylight Saving Time. If this situation occurs, the first occurrence of the time is chosen. (For this reason, it is wise to have the input string contain the time zone when converting local times. This caveat does not apply to UTC times.) 


Format groups
-------------

 The following format groups are recognized by the **clock scan** and **clock format** commands. 
 **%a**
 On output, receives an abbreviation (*e.g.,* **Mon**) for the day of the week in the given locale. On input, matches the name of the day of the week in the given locale (in either abbreviated or full form, or any unique prefix of either form). 

**%A**
 On output, receives the full name (*e.g.,* **Monday**) of the day of the week in the given locale. On input, matches the name of the day of the week in the given locale (in either abbreviated or full form, or any unique prefix of either form). 

**%b**
 On output, receives an abbreviation (*e.g.,* **Jan**) for the name of the month in the given locale. On input, matches the name of the month in the given locale (in either abbreviated or full form, or any unique prefix of either form). 

**%B**
 On output, receives the full name (*e.g.,* **January**) of the month in the given locale. On input, matches the name of the month in the given locale (in either abbreviated or full form, or any unique prefix of either form). 

**%c**
 On output, receives a localized representation of date and time of day; the localized representation is expected to use the Gregorian calendar. On input, matches whatever **%c** produces. 

**%C**
 On output, receives the number of the century in Indo-Arabic numerals. On input, matches one or two digits, possibly with leading whitespace, that are expected to be the number of the century. 

**%d**
 On output, produces the number of the day of the month, as two decimal digits. On input, matches one or two digits, possibly with leading whitespace, that are expected to be the number of the day of the month. 

**%D**
 This format group is synonymous with **%m/%d/%Y**. It should be used only in exchanging data within the **en\_US** locale, since other locales typically do not use this order for the fields of the date. 

**%e**
 On output, produces the number of the day of the month, as one or two decimal digits (with a leading blank for one-digit dates). On input, matches one or two digits, possibly with leading whitespace, that are expected to be the number of the day of the month. 

**%Ec**
 On output, produces a locale-dependent representation of the date and time of day in the locale's alternative calendar. On input, matches whatever **%Ec** produces. The locale's alternative calendar need not be the Gregorian calendar. 

**%EC**
 On output, produces a locale-dependent name of an era in the locale's alternative calendar. On input, matches the name of the era or any unique prefix. 

**%EE**
 On output, produces the string **B.C.E.** or **C.E.**, or a string of the same meaning in the locale, to indicate whether **%Y** refers to years before or after Year 1 of the Common Era. On input, accepts the string **B.C.E.**, **B.C.**, **C.E.**, **A.D.**, or the abbreviation appropriate to the current locale, and uses it to fix whether **%Y** refers to years before or after Year 1 of the Common Era. 

**%Ex**
 On output, produces a locale-dependent representation of the date in the locale's alternative calendar. On input, matches whatever **%Ex** produces. The locale's alternative calendar need not be the Gregorian calendar. 

**%EX**
 On output, produces a locale-dependent representation of the time of day in the locale's alternative numerals. On input, matches whatever **%EX** produces. 

**%Ey**
 On output, produces a locale-dependent number of the year of the era in the locale's alternative calendar and numerals. On input, matches such a number. 

**%EY**
 On output, produces a representation of the year in the locale's alternative calendar and numerals. On input, matches what **%EY** produces. Often synonymous with **%EC%Ey**. 

**%g**
 On output, produces a two-digit year number suitable for use with the week-based ISO8601 calendar; that is, the year number corresponds to the week number produced by **%V**. On input, accepts such a two-digit year number, possibly with leading whitespace. 

**%G**
 On output, produces a four-digit year number suitable for use with the week-based ISO8601 calendar; that is, the year number corresponds to the week number produced by **%V**. On input, accepts such a four-digit year number, possibly with leading whitespace. 

**%h**
 This format group is synonymous with **%b**. 

**%H**
 On output, produces a two-digit number giving the hour of the day (00-23) on a 24-hour clock. On input, accepts such a number. 

**%I**
 On output, produces a two-digit number giving the hour of the day (12-11) on a 12-hour clock. On input, accepts such a number. 

**%j**
 On output, produces a three-digit number giving the day of the year (001-366). On input, accepts such a number. 

**%J**
 On output, produces a string of digits giving the Julian Day Number. On input, accepts a string of digits and interprets it as a Julian Day Number. The Julian Day Number is a count of the number of calendar days that have elapsed since 1 January, 4713 BCE of the proleptic Julian calendar. The epoch time of 1 January 1970 corresponds to Julian Day Number 2440588. 

**%k**
 On output, produces a one- or two-digit number giving the hour of the day (0-23) on a 24-hour clock. On input, accepts such a number. 

**%l**
 On output, produces a one- or two-digit number giving the hour of the day (12-11) on a 12-hour clock. On input, accepts such a number. 

**%m**
 On output, produces the number of the month (01-12) with exactly two digits. On input, accepts two digits and interprets them as the number of the month. 

**%M**
 On output, produces the number of the minute of the hour (00-59) with exactly two digits. On input, accepts two digits and interprets them as the number of the minute of the hour. 

**%N**
 On output, produces the number of the month (1-12) with one or two digits, and a leading blank for one-digit dates. On input, accepts one or two digits, possibly with leading whitespace, and interprets them as the number of the month. 


**%Od**, **%Oe**, **%OH**, **%OI**, **%Ok**, **%Ol**, **%Om**, **%OM**, **%OS**, **%Ou**, **%Ow**, **%Oy**

 All of these format groups are synonymous with their counterparts without the “**O**”, except that the string is produced and parsed in the locale-dependent alternative numerals. 

**%p**
 On output, produces an indicator for the part of the day, **AM** or **PM**, appropriate to the given locale. If the script of the given locale supports multiple letterforms, lowercase is preferred. On input, matches the representation **AM** or **PM** in the given locale, in either case. 

**%P**
 On output, produces an indicator for the part of the day, **am** or **pm**, appropriate to the given locale. If the script of the given locale supports multiple letterforms, uppercase is preferred. On input, matches the representation **AM** or **PM** in the given locale, in either case. 

**%Q**
 This format group is reserved for internal use within the Tcl library. 

**%r**
 On output, produces a locale-dependent time of day representation on a 12-hour clock. On input, accepts whatever **%r** produces. 

**%R**
 On output, the time in 24-hour notation (%H:%M). For a version including the seconds, see **%T** below. On input, accepts whatever **%R** produces. 

**%s**
 On output, simply formats the *timeVal* argument as a decimal integer and inserts it into the output string. On input, accepts a decimal integer and uses is as the time value without any further processing. Since **%s** uniquely determines a point in time, it overrides all other input formats. 

**%S**
 On output, produces a two-digit number of the second of the minute (00-59). On input, accepts two digits and uses them as the second of the minute. 

**%t**
 On output, produces a TAB character. On input, matches a TAB character. 

**%T**
 Synonymous with **%H:%M:%S**. 

**%u**
 On output, produces the number of the day of the week (**1**→Monday, **7**→Sunday). On input, accepts a single digit and interprets it as the day of the week. Sunday may be either **0** or **7**. 

**%U**
 On output, produces the ordinal number of the week of the year (00-53). The first Sunday of the year is the first day of week 01. On input accepts two digits which are otherwise ignored. This format group is never used in determining an input date. This interpretation of the week of the year was once common in US banking but is now largely obsolete. See **%V** for the ISO8601 week number. 

**%V**
 On output, produces the number of the ISO8601 week as a two digit number (01-53). Week 01 is the week containing January 4; or the first week of the year containing at least 4 days; or the week containing the first Thursday of the year (the three statements are equivalent). Each week begins on a Monday. On input, accepts the ISO8601 week number. 

**%w**
 On output, produces the ordinal number of the day of the week (Sunday==0; Saturday==6). On input, accepts a single digit and interprets it as the day of the week; Sunday may be represented as either 0 or 7. Note that **%w** is not the ISO8601 weekday number, which is produced and accepted by **%u**. 

**%W**
 On output, produces a week number (00-53) within the year; week 01 begins on the first Monday of the year. On input, accepts two digits, which are otherwise ignored. This format group is never used in determining an input date. It is not the ISO8601 week number; that week is produced and accepted by **%V**. 

**%x**
 On output, produces the date in a locale-dependent representation. On input, accepts whatever **%x** produces and is used to determine calendar date. 

**%X**
 On output, produces the time of day in a locale-dependent representation. On input, accepts whatever **%X** produces and is used to determine time of day. 

**%y**
 On output, produces the two-digit year of the century. On input, accepts two digits, and is used to determine calendar date. The date is presumed to lie between 1938 and 2037 inclusive. Note that **%y** does not yield a year appropriate for use with the ISO8601 week number **%V**; programs should use **%g** for that purpose. 

**%Y**
 On output, produces the four-digit calendar year. On input, accepts four digits and may be used to determine calendar date. Note that **%Y** does not yield a year appropriate for use with the ISO8601 week number **%V**; programs should use **%G** for that purpose. 

**%z**
 On output, produces the current time zone, expressed in hours and minutes east (+hhmm) or west (-hhmm) of Greenwich. On input, accepts a time zone specifier (see **[TIME ZONES](#M78)** below) that will be used to determine the time zone. 

**%Z**
 On output, produces the current time zone's name, possibly translated to the given locale. On input, accepts a time zone specifier (see **[TIME ZONES](#M78)** below) that will be used to determine the time zone. This option should, in general, be used on input only when parsing RFC822 dates. Other uses are fraught with ambiguity; for instance, the string **BST** may represent British Summer Time or Brazilian Standard Time. It is recommended that date/time strings for use by computers use numeric time zones instead. 

**%%**
 On output, produces a literal “**%**” character. On input, matches a literal “**%**” character. 

**%+**
 Synonymous with “**%a %b %e %H:%M:%S %Z %Y**”. 

 Time zones
----------

 When the **clock** command is processing a local time, it has several possible sources for the time zone to use. In order of preference, they are: 
1. A time zone specified inside a string being parsed and matched by a **%z** or **%Z** format group.
2. A time zone specified with the **-timezone** option to the **clock** command (or, equivalently, by **-gmt** **1**).
3. A time zone specified in an environment variable **TCL\_TZ**.
4. A time zone specified in an environment variable **TZ**.
5. The local time zone from the Control Panel on Windows systems.
6. The C library's idea of the local time zone, as defined by the **mktime** and **localtime** functions.

  In case [1] *only,* the string is tested to see if it is one of the strings: 



```
gmt     ut      utc     bst     wet     wat     at
 nft     nst     ndt     ast     adt     est     edt
 cst     cdt     mst     mdt     pst     pdt     yst
 ydt     hst     hdt     cat     ahst    nt      idlw
 cet     cest    met     mewt    mest    swt     sst
 eet     eest    bt      it      zp4     zp5     ist
 zp6     wast    wadt    jt      cct     jst     cast
 cadt    east    eadt    gst     nzt     nzst    nzdt
 idle
```
  If it is a string in the above list, it designates a known time zone, and is interpreted as such. 


 For time zones in case [1] that do not match any of the above strings, and always for cases [2]-[6], the following rules apply. 


 If the time zone begins with a colon, it is one of a standardized list of names like **:America/New\_York** that give the rules for various locales. A complete list of the location names is too lengthy to be listed here. On most Tcl installations, the definitions of the locations are to be found in named files in the directory “*/no\_backup/tools/lib/tcl8.5/clock/tzdata*”. On some Unix systems, these files are omitted, and the definitions are instead obtained from system files in “*/usr/share/zoneinfo*”, “*/usr/share/lib/zoneinfo*” or “*/usr/local/etc/zoneinfo*”. As a special case, the name **:localtime** refers to the local time zone as defined by the C library. 


 A time zone string consisting of a plus or minus sign followed by four or six decimal digits is interpreted as an offset in hours, minutes, and seconds (if six digits are present) from UTC. The plus sign denotes a sign east of Greenwich; the minus sign one west of Greenwich. 


 A time zone string conforming to the Posix specification of the **TZ** environment variable will be recognized. The specification may be found at *<http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html>*. 


 If the Posix time zone string contains a DST (Daylight Savings Time) part, but doesn't contain a rule stating when DST starts or ends, then default rules are used. For Timezones with an offset between 0 and +12, the current European/Russian rules are used, otherwise the current US rules are used. In Europe (offset +0 to +2) the switch to summertime is done each last Sunday in March at 1:00 GMT, and the switch back is each last Sunday in October at 2:00 GMT. In Russia (offset +3 to +12), the switch dates are the same, only the switch to summertime is at 2:00 local time, and the switch back is at 3:00 local time in all time zones. The US switch to summertime takes place each second Sunday in March at 2:00 local time, and the switch back is each first Sunday in November at 3:00 local time. These default rules mean that in all European, Russian and US (or compatible) time zones, DST calculations will be correct for dates in 2007 and later, unless in the future the rules change again. 


 Any other time zone string is processed by prefixing a colon and attempting to use it as a location name, as above. 


Localization
------------

 Developers wishing to localize the date and time formatting and parsing are referred to *<http://tip.tcl.tk/173>* for a specification. Free form scan
--------------

 If the **clock scan** command is invoked without a **-format** option, then it requests a *free-form scan.*  *This form of scan is deprecated.* The reason for the deprecation is that there are too many ambiguities. (Does the string “2000” represent a year, a time of day, or a quantity?) No set of rules for interpreting free-form dates and times has been found to give unsurprising results in all cases.  If free-form scan is used, only the **-base** and **-gmt** options are accepted. The **-timezone** and **-locale** options will result in an error if **-format** is not supplied. 


 For the benefit of users who need to understand legacy code that uses free-form scan, the documentation for how free-form scan interprets a string is included here: 


 If only a time is specified, the current date is assumed. If the *inputString* does not contain a time zone mnemonic, the local time zone is assumed, unless the **-gmt** argument is true, in which case the clock value is calculated assuming that the specified time is relative to Greenwich Mean Time. **-gmt**, if specified, affects only the computed time value; it does not impact the interpretation of **-base**. 


 If the **-base** flag is specified, the next argument should contain an integer clock value. Only the date in this value is used, not the time. This is useful for determining the time on a specific day or doing other date-relative conversions. 


 The *inputString* argument consists of zero or more specifications of the following form: 


 *time*
 A time of day, which is of the form: **hh?:mm?:ss?? ?meridian? ?zone?** or **hhmm ?meridian? ?zone?** If no meridian is specified, **hh** is interpreted on a 24-hour clock. 

*date*
 A specific month and day with optional year. The acceptable formats are “**mm/dd**?**/yy**?”, “**monthname dd**?**, yy**?”, “**day, dd monthname** ?**yy**?”, “**dd monthname yy**”, “?**CC**?**yymmdd**”, and “**dd-monthname-**?**CC**?**yy**”. The default year is the current year. If the year is less than 100, we treat the years 00-68 as 2000-2068 and the years 69-99 as 1969-1999. Not all platforms can represent the years 38-70, so an error may result if these years are used. 

*ISO 8601 point-in-time*
 An ISO 8601 point-in-time specification, such as “*CCyymmdd***T***hhmmss*,” where **T** is the literal “T”, “*CCyymmdd hhmmss*”, or “*CCyymmdd***T***hh:mm:ss*”. Note that only these three formats are accepted. The command does *not* accept the full range of point-in-time specifications specified in ISO8601. Other formats can be recognized by giving an explicit **-format** option to the **clock scan** command. 

*relative time*
 A specification relative to the current time. The format is **number unit**. Acceptable units are **year**, **fortnight**, **month**, **week**, **day**, **hour**, **minute** (or **min**), and **second** (or **sec**). The unit can be specified as a singular or plural, as in **3 weeks**. These modifiers may also be specified: **tomorrow**, **yesterday**, **today**, **now**, **last**, **this**, **next**, **ago**. 

  The actual date is calculated according to the following steps. 


 First, any absolute date and/or time is processed and converted. Using that time as the base, day-of-week specifications are added. Next, relative specifications are used. If a date or day is specified, and no absolute or relative time is given, midnight is used. Finally, a correction is applied so that the correct hour of the day is produced after allowing for daylight savings time differences and the correct date is given when going from the end of a long month to a short month. 


See also
--------

 **[msgcat](msgcat.htm)** Copyright
---------

 Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. Copyright © 2004 Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/clock.htm>

info
====

  
[NAME](info.htm#M2) info — Return information about the state of the Tcl interpreter 
[SYNOPSIS](info.htm#M3) 
[DESCRIPTION](info.htm#M4)  
[**info args** *procname*](info.htm#M5) 
[**info body** *procname*](info.htm#M6) 
[**info class** *subcommand class* ?*arg ...*](info.htm#M7) 
[**info cmdcount**](info.htm#M8) 
[**info commands** ?*pattern*?](info.htm#M9) 
[**info complete** *command*](info.htm#M10) 
[**info coroutine**](info.htm#M11) 
[**info default** *procname arg varname*](info.htm#M12) 
[**info errorstack** ?*interp*?](info.htm#M13) 
[**info exists** *varName*](info.htm#M14) 
[**info frame** ?*number*?](info.htm#M15)  
[**type**](info.htm#M16)  
[**source**](info.htm#M17) 
[**proc**](info.htm#M18) 
[**eval**](info.htm#M19) 
[**precompiled**](info.htm#M20) 



 
[**line**](info.htm#M21) 
[**file**](info.htm#M22) 
[**cmd**](info.htm#M23) 
[**proc**](info.htm#M24) 
[**lambda**](info.htm#M25) 
[**level**](info.htm#M26) 






 
[**info functions** ?*pattern*?](info.htm#M27) 
[**info globals** ?*pattern*?](info.htm#M28) 
[**info hostname**](info.htm#M29) 
[**info level** ?*number*?](info.htm#M30) 
[**info library**](info.htm#M31) 
[**info loaded** ?*interp*?](info.htm#M32) 
[**info locals** ?*pattern*?](info.htm#M33) 
[**info nameofexecutable**](info.htm#M34) 
[**info object** *subcommand object* ?*arg ...*](info.htm#M35) 
[**info patchlevel**](info.htm#M36) 
[**info procs** ?*pattern*?](info.htm#M37) 
[**info script** ?*filename*?](info.htm#M38) 
[**info sharedlibextension**](info.htm#M39) 
[**info tclversion**](info.htm#M40) 
[**info vars** ?*pattern*?](info.htm#M41) 

























 
[CLASS INTROSPECTION](info.htm#M42)  
[**info class call** *class method*](info.htm#M43) 
[**info class constructor** *class*](info.htm#M44) 
[**info class definition** *class method*](info.htm#M45) 
[**info class destructor** *class*](info.htm#M46) 
[**info class filters** *class*](info.htm#M47) 
[**info class forward** *class method*](info.htm#M48) 
[**info class instances** *class* ?*pattern*?](info.htm#M49) 
[**info class methods** *class* ?*options...*?](info.htm#M50)  
[**-all**](info.htm#M51) 
[**-private**](info.htm#M52) 

 
[**info class methodtype** *class method*](info.htm#M53) 
[**info class mixins** *class*](info.htm#M54) 
[**info class subclasses** *class* ?*pattern*?](info.htm#M55) 
[**info class superclasses** *class*](info.htm#M56) 
[**info class variables** *class*](info.htm#M57) 












 
[OBJECT INTROSPECTION](info.htm#M58)  
[**info object call** *object method*](info.htm#M59) 
[**info object class** *object* ?*className*?](info.htm#M60) 
[**info object definition** *object method*](info.htm#M61) 
[**info object filters** *object*](info.htm#M62) 
[**info object forward** *object method*](info.htm#M63) 
[**info object isa** *category object* ?*arg*?](info.htm#M64)  
[**info object isa class** *object*](info.htm#M65) 
[**info object isa metaclass** *object*](info.htm#M66) 
[**info object isa mixin** *object class*](info.htm#M67) 
[**info object isa object** *object*](info.htm#M68) 
[**info object isa typeof** *object class*](info.htm#M69) 




 
[**info object methods** *object* ?*option...*?](info.htm#M70)  
[**-all**](info.htm#M71) 
[**-private**](info.htm#M72) 

 
[**info object methodtype** *object method*](info.htm#M73) 
[**info object mixins** *object*](info.htm#M74) 
[**info object namespace** *object*](info.htm#M75) 
[**info object variables** *object*](info.htm#M76) 
[**info object vars** *object* ?*pattern*?](info.htm#M77) 











 
[EXAMPLES](info.htm#M78) 
[EXAMPLES WITH OBJECTS](info.htm#M79) 
[SEE ALSO](info.htm#M80) 
[KEYWORDS](info.htm#M81) 








 Name
----

 info — Return information about the state of the Tcl interpreter Synopsis
--------

 **info** *option* ?*arg arg ...*?  
 Description
-----------

 This command provides information about various internals of the Tcl interpreter. The legal *option*s (which may be abbreviated) are: 
 
**info args** *procname*

 Returns a list containing the names of the arguments to procedure *procname*, in order. *Procname* must be the name of a Tcl command procedure. 


**info body** *procname*

 Returns the body of procedure *procname*. *Procname* must be the name of a Tcl command procedure. 


**info class** *subcommand class* ?*arg ...*

 Returns information about the class, *class*. The *subcommand*s are described in **[CLASS INTROSPECTION](#M42)** below. 

**info cmdcount**
 Returns a count of the total number of commands that have been invoked in this interpreter. 


**info commands** ?*pattern*?
 If *pattern* is not specified, returns a list of names of all the Tcl commands visible (i.e. executable without using a qualified name) to the current namespace, including both the built-in commands written in C and the command procedures defined using the **[proc](proc.htm)** command. If *pattern* is specified, only those names matching *pattern* are returned. Matching is determined using the same rules as for **[string match](string.htm)**. *pattern* can be a qualified name like **Foo::print\***. That is, it may specify a particular namespace using a sequence of namespace names separated by double colons (**::**), and may have pattern matching special characters at the end to specify a set of commands in that namespace. If *pattern* is a qualified name, the resulting list of command names has each one qualified with the name of the specified namespace, and only the commands defined in the named namespace are returned. 


**info complete** *command*

 Returns 1 if *command* is a complete Tcl command in the sense of having no unclosed quotes, braces, brackets or array element names. If the command does not appear to be complete then 0 is returned. This command is typically used in line-oriented input environments to allow users to type in commands that span multiple lines; if the command is not complete, the script can delay evaluating it until additional lines have been typed to complete the command. 

**info coroutine**
 Returns the name of the currently executing **[coroutine](coroutine.htm)**, or the empty string if either no coroutine is currently executing, or the current coroutine has been deleted (but has not yet returned or yielded since deletion). 


**info default** *procname arg varname*

 *Procname* must be the name of a Tcl command procedure and *arg* must be the name of an argument to that procedure. If *arg* does not have a default value then the command returns **0**. Otherwise it returns **1** and places the default value of *arg* into variable *varname*. 


**info errorstack** ?*interp*?
 Returns, in a form that is programmatically easy to parse, the function names and arguments at each level from the call stack of the last error in the given *interp*, or in the current one if not specified.  This form is an even-sized list alternating tokens and parameters. Tokens are currently either **CALL**, **UP**, or **INNER**, but other values may be introduced in the future. **CALL** indicates a procedure call, and its parameter is the corresponding **info level** **0**. **UP** indicates a shift in variable frames generated by **[uplevel](uplevel.htm)** or similar, and applies to the previous **CALL** item. Its parameter is the level offset. **INNER** identifies the “inner context”, which is the innermost atomic command or bytecode instruction that raised the error, along with its arguments when available. While **CALL** and **UP** allow to follow complex call paths, **INNER** homes in on the offending operation in the innermost procedure call, even going to sub-expression granularity. 


This information is also present in the **-errorstack** entry of the options dictionary returned by 3-argument **[catch](catch.htm)**; **info errorstack** is a convenient way of retrieving it for uncaught errors at top-level in an interactive **[tclsh](../usercmd/tclsh.htm)**. 




**info exists** *varName*

 Returns **1** if the variable named *varName* exists in the current context (either as a global or local variable) and has been defined by being given a value, returns **0** otherwise. 


**info frame** ?*number*?
 This command provides access to all frames on the stack, even those hidden from **info level**. If *number* is not specified, this command returns a number giving the frame level of the command. This is 1 if the command is invoked at top-level. If *number* is specified, then the result is a dictionary containing the location information for the command at the *number*ed level on the stack.  If *number* is positive (> 0) then it selects a particular stack level (1 refers to the outer-most active command, 2 to the command it called, and so on, up to the current frame level which refers to **info frame** itself); otherwise it gives a level relative to the current command (0 refers to the current command, i.e., **info frame** itself, -1 to its caller, and so on). 


 This is similar to how **info level** works, except that this subcommand reports all frames, like **[source](source.htm)**d scripts, **[eval](eval.htm)**s, **[uplevel](uplevel.htm)**s, etc. 


 Note that for nested commands, like “foo [bar [x]]”, only “x” will be seen by an **info frame** invoked within “x”. This is the same as for **info level** and error stack traces. 


 The result dictionary may contain the keys listed below, with the specified meanings for their values: 


 **type**
 This entry is always present and describes the nature of the location for the command. The recognized values are **[source](source.htm)**, **[proc](proc.htm)**, **[eval](eval.htm)**, and **precompiled**. 
 **source**
 means that the command is found in a script loaded by the **[source](source.htm)** command. 

**proc**
 means that the command is found in dynamically created procedure body. 

**eval**
 means that the command is executed by **[eval](eval.htm)** or **[uplevel](uplevel.htm)**. 

**precompiled**
 means that the command is found in a pre-compiled script (loadable by the package **tbcload**), and no further information will be available. 



**line**
 This entry provides the number of the line the command is at inside of the script it is a part of. This information is not present for type **precompiled**. For type **[source](source.htm)** this information is counted relative to the beginning of the file, whereas for the last two types the line is counted relative to the start of the script. 

**file**
 This entry is present only for type **[source](source.htm)**. It provides the normalized path of the file the command is in. 

**cmd**
 This entry provides the string representation of the command. This is usually the unsubstituted form, however for commands which are a canonically-constructed list (e.g., as produced by the **[list](list.htm)** command) executed by **[eval](eval.htm)** it is the substituted form as they have no other string representation. Care is taken that the canonicality property of the latter is not spoiled. 

**proc**
 This entry is present only if the command is found in the body of a regular Tcl procedure. It then provides the name of that procedure. 

**lambda**
 This entry is present only if the command is found in the body of an anonymous Tcl procedure, i.e. a lambda. It then provides the entire definition of the lambda in question. 

**level**
 This entry is present only if the queried frame has a corresponding frame returned by **info level**. It provides the index of this frame, relative to the current level (0 and negative numbers). 

  A thing of note is that for procedures statically defined in files the locations of commands in their bodies will be reported with type **[source](source.htm)** and absolute line numbers, and not as type **[proc](proc.htm)**. The same is true for procedures nested in statically defined procedures, and literal eval scripts in files or statically defined procedures. 


 In contrast, procedure definitions and **[eval](eval.htm)** within a dynamically **[eval](eval.htm)**uated environment count line numbers relative to the start of their script, even if they would be able to count relative to the start of the outer dynamic script. That type of number usually makes more sense. 


 A different way of describing this behaviour is that file based locations are tracked as deeply as possible, and where this is not possible the lines are counted based on the smallest possible **[eval](eval.htm)** or procedure body, as that scope is usually easier to find than any dynamic outer scope. 


The syntactic form **{\*}** is handled like **[eval](eval.htm)**. I.e. if it is given a literal list argument the system tracks the line number within the list words as well, and otherwise all line numbers are counted relative to the start of each word (smallest scope) 




**info functions** ?*pattern*?
 If *pattern* is not specified, returns a list of all the math functions currently defined. If *pattern* is specified, only those functions whose name matches *pattern* are returned. Matching is determined using the same rules as for **[string match](string.htm)**. 


**info globals** ?*pattern*?
 If *pattern* is not specified, returns a list of all the names of currently-defined global variables. Global variables are variables in the global namespace. If *pattern* is specified, only those names matching *pattern* are returned. Matching is determined using the same rules as for **[string match](string.htm)**. 

**info hostname**
 Returns the name of the computer on which this invocation is being executed. Note that this name is not guaranteed to be the fully qualified domain name of the host. Where machines have several different names (as is common on systems with both TCP/IP (DNS) and NetBIOS-based networking installed,) it is the name that is suitable for TCP/IP networking that is returned. 


**info level** ?*number*?
 If *number* is not specified, this command returns a number giving the stack level of the invoking procedure, or 0 if the command is invoked at top-level. If *number* is specified, then the result is a list consisting of the name and arguments for the procedure call at level *number* on the stack. If *number* is positive then it selects a particular stack level (1 refers to the top-most active procedure, 2 to the procedure it called, and so on); otherwise it gives a level relative to the current level (0 refers to the current procedure, -1 to its caller, and so on). See the **[uplevel](uplevel.htm)** command for more information on what stack levels mean. 

**info library**
 Returns the name of the library directory in which standard Tcl scripts are stored. This is actually the value of the **[tcl\_library](tclvars.htm)** variable and may be changed by setting **[tcl\_library](tclvars.htm)**. 


**info loaded** ?*interp*?
 Returns a list describing all of the packages that have been loaded into *interp* with the **[load](load.htm)** command. Each list element is a sub-list with two elements consisting of the name of the file from which the package was loaded and the name of the package. For statically-loaded packages the file name will be an empty string. If *interp* is omitted then information is returned for all packages loaded in any interpreter in the process. To get a list of just the packages in the current interpreter, specify an empty string for the *interp* argument. 


**info locals** ?*pattern*?
 If *pattern* is not specified, returns a list of all the names of currently-defined local variables, including arguments to the current procedure, if any. Variables defined with the **[global](global.htm)**, **[upvar](upvar.htm)** and **[variable](variable.htm)** commands will not be returned. If *pattern* is specified, only those names matching *pattern* are returned. Matching is determined using the same rules as for **[string match](string.htm)**. 

**info nameofexecutable**
 Returns the full path name of the binary file from which the application was invoked. If Tcl was unable to identify the file, then an empty string is returned. 


**info object** *subcommand object* ?*arg ...*

 Returns information about the object, *object*. The *subcommand*s are described in **[OBJECT INTROSPECTION](#M58)** below. 

**info patchlevel**
 Returns the value of the global variable **tcl\_patchLevel**, which holds the exact version of the Tcl library by default. 


**info procs** ?*pattern*?
 If *pattern* is not specified, returns a list of all the names of Tcl command procedures in the current namespace. If *pattern* is specified, only those procedure names in the current namespace matching *pattern* are returned. Matching is determined using the same rules as for **[string match](string.htm)**. If *pattern* contains any namespace separators, they are used to select a namespace relative to the current namespace (or relative to the global namespace if *pattern* starts with **::**) to match within; the matching pattern is taken to be the part after the last namespace separator. 


**info script** ?*filename*?
 If a Tcl script file is currently being evaluated (i.e. there is a call to **[Tcl\_EvalFile](https://www.tcl.tk/man/tcl/TclLib/Eval.htm)** active or there is an active invocation of the **[source](source.htm)** command), then this command returns the name of the innermost file being processed. If *filename* is specified, then the return value of this command will be modified for the duration of the active invocation to return that name. This is useful in virtual file system applications. Otherwise the command returns an empty string. 

**info sharedlibextension**
 Returns the extension used on this platform for the names of files containing shared libraries (for example, **.so** under Solaris). If shared libraries are not supported on this platform then an empty string is returned. 

**info tclversion**
 Returns the value of the global variable **[tcl\_version](tclvars.htm)**, which holds the major and minor version of the Tcl library by default. 


**info vars** ?*pattern*?
 If *pattern* is not specified, returns a list of all the names of currently-visible variables. This includes locals and currently-visible globals. If *pattern* is specified, only those names matching *pattern* are returned. Matching is determined using the same rules as for **[string match](string.htm)**. *pattern* can be a qualified name like **Foo::option\***. That is, it may specify a particular namespace using a sequence of namespace names separated by double colons (**::**), and may have pattern matching special characters at the end to specify a set of variables in that namespace. If *pattern* is a qualified name, the resulting list of variable names has each matching namespace variable qualified with the name of its namespace. Note that a currently-visible variable may not yet “exist” if it has not been set (e.g. a variable declared but not set by **[variable](variable.htm)**). 

 ### Class introspection

 The following *subcommand* values are supported by **info class**: 
 
**info class call** *class method*

 Returns a description of the method implementations that are used to provide a stereotypical instance of *class*'s implementation of *method* (stereotypical instances being objects instantiated by a class without having any object-specific definitions added). This consists of a list of lists of four elements, where each sublist consists of a word that describes the general type of method implementation (being one of **method** for an ordinary method, **filter** for an applied filter, and **[unknown](unknown.htm)** for a method that is invoked as part of unknown method handling), a word giving the name of the particular method invoked (which is always the same as *method* for the **method** type, and “**[unknown](unknown.htm)**” for the **[unknown](unknown.htm)** type), a word giving the fully qualified name of the class that defined the method, and a word describing the type of method implementation (see **info class methodtype**).  Note that there is no inspection of whether the method implementations actually use **[next](next.htm)** to transfer control along the call chain. 




**info class constructor** *class*

 This subcommand returns a description of the definition of the constructor of class *class*. The definition is described as a two element list; the first element is the list of arguments to the constructor in a form suitable for passing to another call to **[proc](proc.htm)** or a method definition, and the second element is the body of the constructor. If no constructor is present, this returns the empty list. 


**info class definition** *class method*

 This subcommand returns a description of the definition of the method named *method* of class *class*. The definition is described as a two element list; the first element is the list of arguments to the method in a form suitable for passing to another call to **[proc](proc.htm)** or a method definition, and the second element is the body of the method. 


**info class destructor** *class*

 This subcommand returns the body of the destructor of class *class*. If no destructor is present, this returns the empty string. 


**info class filters** *class*

 This subcommand returns the list of filter methods set on the class. 


**info class forward** *class method*

 This subcommand returns the argument list for the method forwarding called *method* that is set on the class called *class*. 


**info class instances** *class* ?*pattern*?
 This subcommand returns a list of instances of class *class*. If the optional *pattern* argument is present, it constrains the list of returned instances to those that match it according to the rules of **[string match](string.htm)**. 


**info class methods** *class* ?*options...*?
 This subcommand returns a list of all public (i.e. exported) methods of the class called *class*. Any of the following *option*s may be specified, controlling exactly which method names are returned: 
 **-all**
 If the **-all** flag is given, the list of methods will include those methods defined not just by the class, but also by the class's superclasses and mixins. 

**-private**
 If the **-private** flag is given, the list of methods will also include the private (i.e. non-exported) methods of the class (and superclasses and mixins, if **-all** is also given). 




**info class methodtype** *class method*

 This subcommand returns a description of the type of implementation used for the method named *method* of class *class*. When the result is **method**, further information can be discovered with **info class definition**, and when the result is **forward**, further information can be discovered with **info class forward**. 


**info class mixins** *class*

 This subcommand returns a list of all classes that have been mixed into the class named *class*. 


**info class subclasses** *class* ?*pattern*?
 This subcommand returns a list of direct subclasses of class *class*. If the optional *pattern* argument is present, it constrains the list of returned classes to those that match it according to the rules of **[string match](string.htm)**. 


**info class superclasses** *class*

 This subcommand returns a list of direct superclasses of class *class* in inheritance precedence order. 


**info class variables** *class*

 This subcommand returns a list of all variables that have been declared for the class named *class* (i.e. that are automatically present in the class's methods, constructor and destructor). 

 ### Object introspection

 The following *subcommand* values are supported by **info object**: 
 
**info object call** *object method*

 Returns a description of the method implementations that are used to provide *object*'s implementation of *method*. This consists of a list of lists of four elements, where each sublist consists of a word that describes the general type of method implementation (being one of **method** for an ordinary method, **filter** for an applied filter, and **[unknown](unknown.htm)** for a method that is invoked as part of unknown method handling), a word giving the name of the particular method invoked (which is always the same as *method* for the **method** type, and “**[unknown](unknown.htm)**” for the **[unknown](unknown.htm)** type), a word giving what defined the method (the fully qualified name of the class, or the literal string **object** if the method implementation is on an instance), and a word describing the type of method implementation (see **info object methodtype**).  Note that there is no inspection of whether the method implementations actually use **[next](next.htm)** to transfer control along the call chain. 




**info object class** *object* ?*className*?
 If *className* is unspecified, this subcommand returns class of the *object* object. If *className* is present, this subcommand returns a boolean value indicating whether the *object* is of that class. 


**info object definition** *object method*

 This subcommand returns a description of the definition of the method named *method* of object *object*. The definition is described as a two element list; the first element is the list of arguments to the method in a form suitable for passing to another call to **[proc](proc.htm)** or a method definition, and the second element is the body of the method. 


**info object filters** *object*

 This subcommand returns the list of filter methods set on the object. 


**info object forward** *object method*

 This subcommand returns the argument list for the method forwarding called *method* that is set on the object called *object*. 


**info object isa** *category object* ?*arg*?
 This subcommand tests whether an object belongs to a particular category, returning a boolean value that indicates whether the *object* argument meets the criteria for the category. The supported categories are: 
 
**info object isa class** *object*

 This returns whether *object* is a class (i.e. an instance of **[oo::class](class.htm)** or one of its subclasses). 


**info object isa metaclass** *object*

 This returns whether *object* is a class that can manufacture classes (i.e. is **[oo::class](class.htm)** or a subclass of it). 


**info object isa mixin** *object class*

 This returns whether *class* is directly mixed into *object*. 


**info object isa object** *object*

 This returns whether *object* really is an object. 


**info object isa typeof** *object class*

 This returns whether *class* is the type of *object* (i.e. whether *object* is an instance of *class* or one of its subclasses, whether direct or indirect). 




**info object methods** *object* ?*option...*?
 This subcommand returns a list of all public (i.e. exported) methods of the object called *object*. Any of the following *option*s may be specified, controlling exactly which method names are returned: 
 **-all**
 If the **-all** flag is given, the list of methods will include those methods defined not just by the object, but also by the object's class and mixins, plus the superclasses of those classes. 

**-private**
 If the **-private** flag is given, the list of methods will also include the private (i.e. non-exported) methods of the object (and classes, if **-all** is also given). 




**info object methodtype** *object method*

 This subcommand returns a description of the type of implementation used for the method named *method* of object *object*. When the result is **method**, further information can be discovered with **info object definition**, and when the result is **forward**, further information can be discovered with **info object forward**. 


**info object mixins** *object*

 This subcommand returns a list of all classes that have been mixed into the object named *object*. 


**info object namespace** *object*

 This subcommand returns the name of the internal namespace of the object named *object*. 


**info object variables** *object*

 This subcommand returns a list of all variables that have been declared for the object named *object* (i.e. that are automatically present in the object's methods). 


**info object vars** *object* ?*pattern*?
 This subcommand returns a list of all variables in the private namespace of the object named *object*. If the optional *pattern* argument is given, it is a filter (in the syntax of a **[string match](string.htm)** glob pattern) that constrains the list of variables returned. Note that this is different from the list returned by **info object variables**; that can include variables that are currently unset, whereas this can include variables that are not automatically included by any of *object*'s methods (or those of its class, superclasses or mixins). 

 Examples
--------

 This command prints out a procedure suitable for saving in a Tcl script: 

```
proc printProc {procName} {
    set result [list proc $procName]
    set formals {}
    foreach var [**info args** $procName] {
        if {[**info default** $procName $var def]} {
            lappend formals [list $var $def]
        } else {
            # Still need the list-quoting because variable
            # names may properly contain spaces.
            lappend formals [list $var]
        }
    }
    puts [lappend result $formals [**info body** $procName]]
}
```
 ### Examples with objects

 Every object necessarily knows what its class is; this information is trivially extractable through introspection: 

```
oo::class create c
c create o
puts [**info object class** o]
                     *→ prints "::c"*
puts [**info object class** c]
                     *→ prints "::oo::class"*
```
  The introspection capabilities can be used to discover what class implements a method and get how it is defined. This procedure illustrates how: 



```
proc getDef {obj method} {
    foreach inf [**info object call** $obj $method] {
        lassign $inf calltype name locus methodtype
        # Assume no forwards or filters, and hence no $calltype
        # or $methodtype checks...
        if {$locus eq "object"} {
            return [**info object definition** $obj $name]
        } else {
            return [**info class definition** $locus $name]
        }
    }
    error "no definition for $method"
}
```
  This is an alternate way of looking up the definition; it is implemented by manually scanning the list of methods up the inheritance tree. This code assumes that only single inheritance is in use, and that there is no complex use of mixed-in classes (in such cases, using **info object call** as above is the simplest way of doing this by far): 



```
proc getDef {obj method} {
    if {$method in [**info object methods** $obj]} {
        # Assume no forwards
        return [**info object definition** $obj $method]
    }
    set cls [**info object class** $obj]
    while {$method ni [**info class methods** $cls]} {
        # Assume the simple case
        set cls [lindex [**info class superclass** $cls] 0]
        if {$cls eq ""} {
            error "no definition for $method"
        }
    }
    # Assume no forwards
    return [**info class definition** $cls $method]
}
```
 See also
--------

 **[global](global.htm)**, **[oo::class](class.htm)**, **[oo::define](define.htm)**, **[oo::object](object.htm)**, **[proc](proc.htm)**, **[self](self.htm)**, **[tcl\_library](tclvars.htm)**, **tcl\_patchLevel**, **[tcl\_version](tclvars.htm)** Copyright © 1993 The Regents of the University of California.  
 Copyright © 1994-1997 Sun Microsystems, Inc.  
 Copyright © 1993-1997 Bell Labs Innovations for Lucent Technologies  
 Copyright © 1998-2000 Ajuba Solutions  
 Copyright © 2007-2012 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/info.htm>

dict
====

  
[NAME](dict.htm#M2) dict — Manipulate dictionaries 
[SYNOPSIS](dict.htm#M3) 
[DESCRIPTION](dict.htm#M4)  
[**dict append** *dictionaryVariable key* ?*string ...*?](dict.htm#M5) 
[**dict create** ?*key value ...*?](dict.htm#M6) 
[**dict exists** *dictionaryValue key* ?*key ...*?](dict.htm#M7) 
[**dict filter** *dictionaryValue filterType arg* ?*arg ...*?](dict.htm#M8)  
[**dict filter** *dictionaryValue* **key** ?*globPattern ...*?](dict.htm#M9) 
[**dict filter** *dictionaryValue* **script {***keyVariable valueVariable***}** *script*](dict.htm#M10) 
[**dict filter** *dictionaryValue* **value** ?*globPattern ...*?](dict.htm#M11) 


 
[**dict for {***keyVariable valueVariable***}** *dictionaryValue body*](dict.htm#M12) 
[**dict get** *dictionaryValue* ?*key ...*?](dict.htm#M13) 
[**dict incr** *dictionaryVariable key* ?*increment*?](dict.htm#M14) 
[**dict info** *dictionaryValue*](dict.htm#M15) 
[**dict keys** *dictionaryValue* ?*globPattern*?](dict.htm#M16) 
[**dict lappend** *dictionaryVariable key* ?*value ...*?](dict.htm#M17) 
[**dict map** {*keyVariable valueVariable*} *dictionaryValue body*](dict.htm#M18) 
[**dict merge** ?*dictionaryValue ...*?](dict.htm#M19) 
[**dict remove** *dictionaryValue* ?*key ...*?](dict.htm#M20) 
[**dict replace** *dictionaryValue* ?*key value ...*?](dict.htm#M21) 
[**dict set** *dictionaryVariable key* ?*key ...*? *value*](dict.htm#M22) 
[**dict size** *dictionaryValue*](dict.htm#M23) 
[**dict unset** *dictionaryVariable key* ?*key ...*?](dict.htm#M24) 
[**dict update** *dictionaryVariable key varName* ?*key varName ...*? *body*](dict.htm#M25) 
[**dict values** *dictionaryValue* ?*globPattern*?](dict.htm#M26) 
[**dict with** *dictionaryVariable* ?*key ...*? *body*](dict.htm#M27) 



















 
[DICTIONARY VALUES](dict.htm#M28) 
[EXAMPLES](dict.htm#M29) 
[SEE ALSO](dict.htm#M30) 
[KEYWORDS](dict.htm#M31) 






 Name
----

 dict — Manipulate dictionaries Synopsis
--------

 **dict** *option arg* ?*arg ...*?  
 Description
-----------

 Performs one of several operations on dictionary values or variables containing dictionary values (see the **[DICTIONARY VALUES](#M28)** section below for a description), depending on *option*. The legal *option*s (which may be abbreviated) are: 
 
**dict append** *dictionaryVariable key* ?*string ...*?
 This appends the given string (or strings) to the value that the given key maps to in the dictionary value contained in the given variable, writing the resulting dictionary value back to that variable. Non-existent keys are treated as if they map to an empty string. The updated dictionary value is returned. 


**dict create** ?*key value ...*?
 Return a new dictionary that contains each of the key/value mappings listed as arguments (keys and values alternating, with each key being followed by its associated value.) 


**dict exists** *dictionaryValue key* ?*key ...*?
 This returns a boolean value indicating whether the given key (or path of keys through a set of nested dictionaries) exists in the given dictionary value. This returns a true value exactly when **dict get** on that path will succeed. 


**dict filter** *dictionaryValue filterType arg* ?*arg ...*?
 This takes a dictionary value and returns a new dictionary that contains just those key/value pairs that match the specified filter type (which may be abbreviated.) Supported filter types are: 
 
**dict filter** *dictionaryValue* **key** ?*globPattern ...*?
 The key rule only matches those key/value pairs whose keys match any of the given patterns (in the style of **[string match](string.htm)**.) 


**dict filter** *dictionaryValue* **script {***keyVariable valueVariable***}** *script*

 The script rule tests for matching by assigning the key to the *keyVariable* and the value to the *valueVariable*, and then evaluating the given script which should return a boolean value (with the key/value pair only being included in the result of the **dict filter** when a true value is returned.) Note that the first argument after the rule selection word is a two-element list. If the *script* returns with a condition of **[TCL\_BREAK](catch.htm)**, no further key/value pairs are considered for inclusion in the resulting dictionary, and a condition of **[TCL\_CONTINUE](catch.htm)** is equivalent to a false result. The key/value pairs are tested in the order in which the keys were inserted into the dictionary. 


**dict filter** *dictionaryValue* **value** ?*globPattern ...*?
 The value rule only matches those key/value pairs whose values match any of the given patterns (in the style of **[string match](string.htm)**.) 




**dict for {***keyVariable valueVariable***}** *dictionaryValue body*

 This command takes three arguments, the first a two-element list of variable names (for the key and value respectively of each mapping in the dictionary), the second the dictionary value to iterate across, and the third a script to be evaluated for each mapping with the key and value variables set appropriately (in the manner of **[foreach](foreach.htm)**.) The result of the command is an empty string. If any evaluation of the body generates a **[TCL\_BREAK](catch.htm)** result, no further pairs from the dictionary will be iterated over and the **dict for** command will terminate successfully immediately. If any evaluation of the body generates a **[TCL\_CONTINUE](catch.htm)** result, this shall be treated exactly like a normal **[TCL\_OK](catch.htm)** result. The order of iteration is the order in which the keys were inserted into the dictionary. 


**dict get** *dictionaryValue* ?*key ...*?
 Given a dictionary value (first argument) and a key (second argument), this will retrieve the value for that key. Where several keys are supplied, the behaviour of the command shall be as if the result of **dict get $dictVal $key** was passed as the first argument to **dict get** with the remaining arguments as second (and possibly subsequent) arguments. This facilitates lookups in nested dictionaries. For example, the following two commands are equivalent: 

```
dict get $dict foo bar spong
dict get [dict get [dict get $dict foo] bar] spong
```
  If no keys are provided, **dict get** will return a list containing pairs of elements in a manner similar to **[array get](array.htm)**. That is, the first element of each pair would be the key and the second element would be the value for that key. 


It is an error to attempt to retrieve a value for a key that is not present in the dictionary. 




**dict incr** *dictionaryVariable key* ?*increment*?
 This adds the given increment value (an integer that defaults to 1 if not specified) to the value that the given key maps to in the dictionary value contained in the given variable, writing the resulting dictionary value back to that variable. Non-existent keys are treated as if they map to 0. It is an error to increment a value for an existing key if that value is not an integer. The updated dictionary value is returned. 


**dict info** *dictionaryValue*

 This returns information (intended for display to people) about the given dictionary though the format of this data is dependent on the implementation of the dictionary. For dictionaries that are implemented by hash tables, it is expected that this will return the string produced by **[Tcl\_HashStats](https://www.tcl.tk/man/tcl/TclLib/Hash.htm)**, similar to **[array statistics](array.htm)**. 


**dict keys** *dictionaryValue* ?*globPattern*?
 Return a list of all keys in the given dictionary value. If a pattern is supplied, only those keys that match it (according to the rules of **[string match](string.htm)**) will be returned. The returned keys will be in the order that they were inserted into the dictionary. 


**dict lappend** *dictionaryVariable key* ?*value ...*?
 This appends the given items to the list value that the given key maps to in the dictionary value contained in the given variable, writing the resulting dictionary value back to that variable. Non-existent keys are treated as if they map to an empty list, and it is legal for there to be no items to append to the list. It is an error for the value that the key maps to to not be representable as a list. The updated dictionary value is returned. 


**dict map** {*keyVariable valueVariable*} *dictionaryValue body*

 This command applies a transformation to each element of a dictionary, returning a new dictionary. It takes three arguments: the first is a two-element list of variable names (for the key and value respectively of each mapping in the dictionary), the second the dictionary value to iterate across, and the third a script to be evaluated for each mapping with the key and value variables set appropriately (in the manner of **[lmap](lmap.htm)**). In an iteration where the evaluated script completes normally (**[TCL\_OK](catch.htm)**, as opposed to an **[error](error.htm)**, etc.) the result of the script is put into an accumulator dictionary using the key that is the current contents of the *keyVariable* variable at that point. The result of the **dict map** command is the accumulator dictionary after all keys have been iterated over.  If the evaluation of the body for any particular step generates a **[break](break.htm)**, no further pairs from the dictionary will be iterated over and the **dict map** command will terminate successfully immediately. If the evaluation of the body for a particular step generates a **[continue](continue.htm)** result, the current iteration is aborted and the accumulator dictionary is not modified. The order of iteration is the natural order of the dictionary (typically the order in which the keys were added to the dictionary; the order is the same as that used in **dict for**). 




**dict merge** ?*dictionaryValue ...*?
 Return a dictionary that contains the contents of each of the *dictionaryValue* arguments. Where two (or more) dictionaries contain a mapping for the same key, the resulting dictionary maps that key to the value according to the last dictionary on the command line containing a mapping for that key. 


**dict remove** *dictionaryValue* ?*key ...*?
 Return a new dictionary that is a copy of an old one passed in as first argument except without mappings for each of the keys listed. It is legal for there to be no keys to remove, and it also legal for any of the keys to be removed to not be present in the input dictionary in the first place. 


**dict replace** *dictionaryValue* ?*key value ...*?
 Return a new dictionary that is a copy of an old one passed in as first argument except with some values different or some extra key/value pairs added. It is legal for this command to be called with no key/value pairs, but illegal for this command to be called with a key but no value. 


**dict set** *dictionaryVariable key* ?*key ...*? *value*

 This operation takes the name of a variable containing a dictionary value and places an updated dictionary value in that variable containing a mapping from the given key to the given value. When multiple keys are present, this operation creates or updates a chain of nested dictionaries. The updated dictionary value is returned. 


**dict size** *dictionaryValue*

 Return the number of key/value mappings in the given dictionary value. 


**dict unset** *dictionaryVariable key* ?*key ...*?
 This operation (the companion to **dict set**) takes the name of a variable containing a dictionary value and places an updated dictionary value in that variable that does not contain a mapping for the given key. Where multiple keys are present, this describes a path through nested dictionaries to the mapping to remove. At least one key must be specified, but the last key on the key-path need not exist. All other components on the path must exist. The updated dictionary value is returned. 


**dict update** *dictionaryVariable key varName* ?*key varName ...*? *body*

 Execute the Tcl script in *body* with the value for each *key* (as found by reading the dictionary value in *dictionaryVariable*) mapped to the variable *varName*. There may be multiple *key*/*varName* pairs. If a *key* does not have a mapping, that corresponds to an unset *varName*. When *body* terminates, any changes made to the *varName*s is reflected back to the dictionary within *dictionaryVariable* (unless *dictionaryVariable* itself becomes unreadable, when all updates are silently discarded), even if the result of *body* is an error or some other kind of exceptional exit. The result of **dict update** is (unless some kind of error occurs) the result of the evaluation of *body*.  Each *varName* is mapped in the scope enclosing the **dict update**; it is recommended that this command only be used in a local scope (**[proc](proc.htm)**edure, lambda term for **[apply](apply.htm)**, or method). Because of this, the variables set by **dict update** will continue to exist after the command finishes (unless explicitly **[unset](unset.htm)**). Note that the mapping of values to variables does not use traces; changes to the *dictionaryVariable*'s contents only happen when *body* terminates. 




**dict values** *dictionaryValue* ?*globPattern*?
 Return a list of all values in the given dictionary value. If a pattern is supplied, only those values that match it (according to the rules of **[string match](string.htm)**) will be returned. The returned values will be in the order of that the keys associated with those values were inserted into the dictionary. 


**dict with** *dictionaryVariable* ?*key ...*? *body*

 Execute the Tcl script in *body* with the value for each key in *dictionaryVariable* mapped (in a manner similarly to **dict update**) to a variable with the same name. Where one or more *key*s are available, these indicate a chain of nested dictionaries, with the innermost dictionary being the one opened out for the execution of *body*. As with **dict update**, making *dictionaryVariable* unreadable will make the updates to the dictionary be discarded, and this also happens if the contents of *dictionaryVariable* are adjusted so that the chain of dictionaries no longer exists. The result of **dict with** is (unless some kind of error occurs) the result of the evaluation of *body*.  The variables are mapped in the scope enclosing the **dict with**; it is recommended that this command only be used in a local scope (**[proc](proc.htm)**edure, lambda term for **[apply](apply.htm)**, or method). Because of this, the variables set by **dict with** will continue to exist after the command finishes (unless explicitly **[unset](unset.htm)**). Note that the mapping of values to variables does not use traces; changes to the *dictionaryVariable*'s contents only happen when *body* terminates. 


If the *dictionaryVariable* contains a value that is not a dictionary at the point when the *body* terminates (which can easily happen if the name is the same as any of the keys in dictionary) then an error occurs at that point. This command is thus not recommended for use when the keys in the dictionary are expected to clash with the *dictionaryVariable* name itself. Where the contained key does map to a dictionary, the net effect is to combine that inner dictionary into the outer dictionary; see the **[EXAMPLES](#M29)** below for an illustration of this. 



 Dictionary values
-----------------

 Dictionaries are values that contain an efficient, order-preserving mapping from arbitrary keys to arbitrary values. Each key in the dictionary maps to a single value. They have a textual format that is exactly that of any list with an even number of elements, with each mapping in the dictionary being represented as two items in the list. When a command takes a dictionary and produces a new dictionary based on it (either returning it or writing it back into the variable that the starting dictionary was read from) the new dictionary will have the same order of keys, modulo any deleted keys and with new keys added on to the end. When a string is interpreted as a dictionary and it would otherwise have duplicate keys, only the last value for a particular key is used; the others are ignored, meaning that, “apple banana” and “apple carrot apple banana” are equivalent dictionaries (with different string representations).  Operations that derive a new dictionary from an old one (e.g., updates like **dict set** and **dict unset**) preserve the order of keys in the dictionary. The exceptions to this are for any new keys they add, which are appended to the sequence, and any keys that are removed, which are excised from the order. 


Examples
--------

 Basic dictionary usage: 

```
# Make a dictionary to map extensions to descriptions
set filetypes [**dict create** .txt "Text File" .tcl "Tcl File"]

# Add/update the dictionary
**dict set** filetypes .tcl "Tcl Script"
**dict set** filetypes .tm  "Tcl Module"
**dict set** filetypes .gif "GIF Image"
**dict set** filetypes .png "PNG Image"

# Simple read from the dictionary
set ext ".tcl"
set desc [**dict get** $filetypes $ext]
puts "$ext is for a $desc"

# Somewhat more complex, with existence test
foreach filename [glob *] {
    set ext [file extension $filename]
    if {[**dict exists** $filetypes $ext]} {
        puts "$filename is a [**dict get** $filetypes $ext]"
    }
}
```
  Constructing and using nested dictionaries: 



```
# Data for one employee
**dict set** employeeInfo 12345-A forenames "Joe"
**dict set** employeeInfo 12345-A surname   "Schmoe"
**dict set** employeeInfo 12345-A street "147 Short Street"
**dict set** employeeInfo 12345-A city   "Springfield"
**dict set** employeeInfo 12345-A phone  "555-1234"
# Data for another employee
**dict set** employeeInfo 98372-J forenames "Anne"
**dict set** employeeInfo 98372-J surname   "Other"
**dict set** employeeInfo 98372-J street "32995 Oakdale Way"
**dict set** employeeInfo 98372-J city   "Springfield"
**dict set** employeeInfo 98372-J phone  "555-8765"
# The above data probably ought to come from a database...

# Print out some employee info
set i 0
puts "There are [**dict size** $employeeInfo] employees"
**dict for** {id info} $employeeInfo {
    puts "Employee #[incr i]: $id"
    **dict with** info {
        puts "   Name: $forenames $surname"
        puts "   Address: $street, $city"
        puts "   Telephone: $phone"
    }
}
# Another way to iterate and pick out names...
foreach id [**dict keys** $employeeInfo] {
    puts "Hello, [**dict get** $employeeInfo $id forenames]!"
}
```
  A localizable version of **[string toupper](string.htm)**: 



```
# Set up the basic C locale
set capital [**dict create** C [**dict create**]]
foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
    **dict set** capital C $c [string toupper $c]
}

# English locales can luckily share the "C" locale
**dict set** capital en [**dict get** $capital C]
**dict set** capital en_US [**dict get** $capital C]
**dict set** capital en_GB [**dict get** $capital C]

# ... and so on for other supported languages ...

# Now get the mapping for the current locale and use it.
set upperCaseMap [**dict get** $capital $env(LANG)]
set upperCase [string map $upperCaseMap $string]
```
  Showing the detail of **dict with**: 



```
proc sumDictionary {varName} {
    upvar 1 $varName vbl
    foreach key [**dict keys** $vbl] {
        # Manufacture an entry in the subdictionary
        **dict set** vbl $key total 0
        # Add the values and remove the old
        **dict with** vbl $key {
            set total [expr {$x + $y + $z}]
            unset x y z
        }
    }
    puts "last total was $total, for key $key"
}

set myDict {
    a {x 1 y 2 z 3}
    b {x 6 y 5 z 4}
}

sumDictionary myDict
#    prints: *last total was 15, for key b*

puts "dictionary is now \"$myDict\""
#    prints: *dictionary is now "a {total 6} b {total 15}"*
```
  When **dict with** is used with a key that clashes with the name of the dictionary variable: 



```
set foo {foo {a b} bar 2 baz 3}
**dict with** foo {}
puts $foo
#    prints: *a b foo {a b} bar 2 baz 3*
```
 See also
--------

 **[append](append.htm)**, **[array](array.htm)**, **[foreach](foreach.htm)**, **mapeach**, **[incr](incr.htm)**, **[list](list.htm)**, **[lappend](lappend.htm)**, **[set](set.htm)** Copyright © 2003 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/dict.htm>

zlib
====

  
[NAME](zlib.htm#M2) zlib — compression and decompression operations 
[SYNOPSIS](zlib.htm#M3) 
[DESCRIPTION](zlib.htm#M4) 
[COMPRESSION SUBCOMMANDS](zlib.htm#M5)  
[**zlib compress** *string* ?*level*?](zlib.htm#M6) 
[**zlib decompress** *string* ?*bufferSize*?](zlib.htm#M7) 
[**zlib deflate** *string* ?*level*?](zlib.htm#M8) 
[**zlib gunzip** *string* ?**-headerVar** *varName*?](zlib.htm#M9)  
[**comment**](zlib.htm#M10) 
[**crc**](zlib.htm#M11) 
[**filename**](zlib.htm#M12) 
[**os**](zlib.htm#M13) 
[**size**](zlib.htm#M14) 
[**time**](zlib.htm#M15) 
[**type**](zlib.htm#M16) 






 
[**zlib gzip** *string* ?**-level** *level*? ?**-header** *dict*?](zlib.htm#M17)  
[**comment**](zlib.htm#M18) 
[**crc**](zlib.htm#M19) 
[**filename**](zlib.htm#M20) 
[**os**](zlib.htm#M21) 
[**time**](zlib.htm#M22) 
[**type**](zlib.htm#M23) 





 
[**zlib inflate** *string* ?*bufferSize*?](zlib.htm#M24) 





 
[CHANNEL SUBCOMMAND](zlib.htm#M25)  
[**zlib push** *mode channel* ?*options ...*?](zlib.htm#M26)  
[**compress**](zlib.htm#M27) 
[**decompress**](zlib.htm#M28) 
[**deflate**](zlib.htm#M29) 
[**gunzip**](zlib.htm#M30) 
[**gzip**](zlib.htm#M31) 
[**inflate**](zlib.htm#M32) 





  
[**-dictionary** *binData*](zlib.htm#M33) 
[**-header** *dictionary*](zlib.htm#M34) 
[**-level** *compressionLevel*](zlib.htm#M35) 
[**-limit** *readaheadLimit*](zlib.htm#M36) 



  
[**-checksum** *checksum*](zlib.htm#M37) 
[**-dictionary** *binData*](zlib.htm#M38) 
[**-flush** *type*](zlib.htm#M39) 
[**-header** *dictionary*](zlib.htm#M40) 
[**-limit** *readaheadLimit*](zlib.htm#M41) 




 
 
[STREAMING SUBCOMMAND](zlib.htm#M42)  
[**zlib stream** *mode* ?*options*?](zlib.htm#M43)  
[**zlib stream compress** ?**-dictionary** *bindata*? ?**-level** *level*?](zlib.htm#M44) 
[**zlib stream decompress** ?**-dictionary** *bindata*?](zlib.htm#M45) 
[**zlib stream deflate** ?**-dictionary** *bindata*? ?**-level** *level*?](zlib.htm#M46) 
[**zlib stream gunzip**](zlib.htm#M47) 
[**zlib stream gzip** ?**-header** *header*? ?**-level** *level*?](zlib.htm#M48) 
[**zlib stream inflate** ?**-dictionary** *bindata*?](zlib.htm#M49) 





 
 
[CHECKSUMMING SUBCOMMANDS](zlib.htm#M50)  
[**zlib adler32** *string* ?*initValue*?](zlib.htm#M51) 
[**zlib crc32** *string* ?*initValue*?](zlib.htm#M52) 

 
[STREAMING INSTANCE COMMAND](zlib.htm#M53)  
[*stream* **add** ?*option...*? *data*](zlib.htm#M54) 
[*stream* **checksum**](zlib.htm#M55) 
[*stream* **close**](zlib.htm#M56) 
[*stream* **eof**](zlib.htm#M57) 
[*stream* **finalize**](zlib.htm#M58) 
[*stream* **flush**](zlib.htm#M59) 
[*stream* **fullflush**](zlib.htm#M60) 
[*stream* **get** ?*count*?](zlib.htm#M61) 
[*stream* **put** ?*option...*? *data*](zlib.htm#M62)  
[**-dictionary** *binData*](zlib.htm#M63) 
[**-finalize**](zlib.htm#M64) 
[**-flush**](zlib.htm#M65) 
[**-fullflush**](zlib.htm#M66) 



 
[*stream* **reset**](zlib.htm#M67) 









 
[EXAMPLES](zlib.htm#M68) 
[SEE ALSO](zlib.htm#M69) 
[KEYWORDS](zlib.htm#M70) 










 Name
----

 zlib — compression and decompression operations Synopsis
--------

 **zlib** *subcommand arg ...*  
 Description
-----------

 The **zlib** command provides access to the compression and check-summing facilities of the Zlib library by Jean-loup Gailly and Mark Adler. It has the following subcommands. ### Compression subcommands

  
**zlib compress** *string* ?*level*?
 Returns the zlib-format compressed binary data of the binary string in *string*. If present, *level* gives the compression level to use (from 0, which is uncompressed, to 9, maximally compressed). 


**zlib decompress** *string* ?*bufferSize*?
 Returns the uncompressed version of the raw compressed binary data in *string*. If present, *bufferSize* is a hint as to what size of buffer is to be used to receive the data. 


**zlib deflate** *string* ?*level*?
 Returns the raw compressed binary data of the binary string in *string*. If present, *level* gives the compression level to use (from 0, which is uncompressed, to 9, maximally compressed). 


**zlib gunzip** *string* ?**-headerVar** *varName*?
 Return the uncompressed contents of binary string *string*, which must have been in gzip format. If **-headerVar** is given, store a dictionary describing the contents of the gzip header in the variable called *varName*. The keys of the dictionary that may be present are: 
 **comment**
 The comment field from the header, if present. 

**crc**
 A boolean value describing whether a CRC of the header is computed. 

**filename**
 The filename field from the header, if present. 

**os**
 The operating system type code field from the header (if not the QW unknown value). See RFC 1952 for the meaning of these codes. 

**size**
 The size of the uncompressed data. 

**time**
 The time field from the header if non-zero, expected to be time that the file named by the **filename** field was modified. Suitable for use with **[clock format](clock.htm)**. 

**type**
 The type of the uncompressed data (**binary** or **text**) if known. 




**zlib gzip** *string* ?**-level** *level*? ?**-header** *dict*?
 Return the compressed contents of binary string *string* in gzip format. If **-level** is given, *level* gives the compression level to use (from 0, which is uncompressed, to 9, maximally compressed). If **-header** is given, *dict* is a dictionary containing values used for the gzip header. The following keys may be defined: 
 **comment**
 Add the given comment to the header of the gzip-format data. 

**crc**
 A boolean saying whether to compute a CRC of the header. Note that if the data is to be interchanged with the **gzip** program, a header CRC should *not* be computed. 

**filename**
 The name of the file that the data to be compressed came from. 

**os**
 The operating system type code, which should be one of the values described in RFC 1952. 

**time**
 The time that the file named in the **filename** key was last modified. This will be in the same as is returned by **[clock seconds](clock.htm)** or **[file mtime](file.htm)**. 

**type**
 The type of the data being compressed, being **binary** or **text**. 




**zlib inflate** *string* ?*bufferSize*?
 Returns the uncompressed version of the raw compressed binary data in *string*. If present, *bufferSize* is a hint as to what size of buffer is to be used to receive the data. 

 ### Channel subcommand

  
**zlib push** *mode channel* ?*options ...*?
 Pushes a compressing or decompressing transformation onto the channel *channel*. The transformation can be removed again with **[chan pop](chan.htm)**. The *mode* argument determines what type of transformation is pushed; the following are supported: 
 **compress**
 The transformation will be a compressing transformation that produces zlib-format data on *channel*, which must be writable. 

**decompress**
 The transformation will be a decompressing transformation that reads zlib-format data from *channel*, which must be readable. 

**deflate**
 The transformation will be a compressing transformation that produces raw compressed data on *channel*, which must be writable. 

**gunzip**
 The transformation will be a decompressing transformation that reads gzip-format data from *channel*, which must be readable. 

**gzip**
 The transformation will be a compressing transformation that produces gzip-format data on *channel*, which must be writable. 

**inflate**
 The transformation will be a decompressing transformation that reads raw compressed data from *channel*, which must be readable. 

   The following options may be set when creating a transformation via the “*options ...*” to the **zlib push** command: 


 
**-dictionary** *binData*

 Sets the compression dictionary to use when working with compressing or decompressing the data to be *binData*. Not valid for transformations that work with gzip-format data. The dictionary should consist of strings (byte sequences) that are likely to be encountered later in the data to be compressed, with the most commonly used strings preferably put towards the end of the dictionary. Tcl provides no mechanism for choosing a good such dictionary for a particular data sequence. 


**-header** *dictionary*

 Passes a description of the gzip header to create, in the same format that **zlib gzip** understands. 


**-level** *compressionLevel*

 How hard to compress the data. Must be an integer from 0 (uncompressed) to 9 (maximally compressed). 


**-limit** *readaheadLimit*

 The maximum number of bytes ahead to read when decompressing. This defaults to 1, which ensures that data is always decompressed correctly, but may be increased to improve performance. This is more useful when the channel is non-blocking. 

  Both compressing and decompressing channel transformations add extra configuration options that may be accessed through **[chan configure](chan.htm)**. The options are: 


 
**-checksum** *checksum*

 This read-only option gets the current checksum for the uncompressed data that the compression engine has seen so far. It is valid for both compressing and decompressing transforms, but not for the raw inflate and deflate formats. The compression algorithm depends on what format is being produced or consumed. 


**-dictionary** *binData*

 This read-write options gets or sets the initial compression dictionary to use when working with compressing or decompressing the data to be *binData*. It is not valid for transformations that work with gzip-format data, and should not normally be set on compressing transformations other than at the point where the transformation is stacked. Note that this cannot be used to get the current active compression dictionary mid-stream, as that information is not exposed by the underlying library. 


**-flush** *type*

 This write-only operation flushes the current state of the compressor to the underlying channel. It is only valid for compressing transformations. The *type* must be either **sync** or **full** for a normal flush or an expensive flush respectively. Flushing degrades the compression ratio, but makes it easier for a decompressor to recover more of the file in the case of data corruption. 


**-header** *dictionary*

 This read-only option, only valid for decompressing transforms that are processing gzip-format data, returns the dictionary describing the header read off the data stream. 


**-limit** *readaheadLimit*

 This read-write option is used by decompressing channels to control the maximum number of bytes ahead to read from the underlying data source. This defaults to 1, which ensures that data is always decompressed correctly, but may be increased to improve performance. This is more useful when the channel is non-blocking. 

 

 ### Streaming subcommand

  
**zlib stream** *mode* ?*options*?
 Creates a streaming compression or decompression command based on the *mode*, and return the name of the command. For a description of how that command works, see **[STREAMING INSTANCE COMMAND](#M53)** below. The following modes and *options* are supported: 
 
**zlib stream compress** ?**-dictionary** *bindata*? ?**-level** *level*?
 The stream will be a compressing stream that produces zlib-format output, using compression level *level* (if specified) which will be an integer from 0 to 9, and the compression dictionary *bindata* (if specified). 


**zlib stream decompress** ?**-dictionary** *bindata*?
 The stream will be a decompressing stream that takes zlib-format input and produces uncompressed output. If *bindata* is supplied, it is a compression dictionary to use if required. 


**zlib stream deflate** ?**-dictionary** *bindata*? ?**-level** *level*?
 The stream will be a compressing stream that produces raw output, using compression level *level* (if specified) which will be an integer from 0 to 9, and the compression dictionary *bindata* (if specified). Note that the raw compressed data includes no metadata about what compression dictionary was used, if any; that is a feature of the zlib-format data. 

**zlib stream gunzip**
 The stream will be a decompressing stream that takes gzip-format input and produces uncompressed output. 


**zlib stream gzip** ?**-header** *header*? ?**-level** *level*?
 The stream will be a compressing stream that produces gzip-format output, using compression level *level* (if specified) which will be an integer from 0 to 9, and the header descriptor dictionary *header* (if specified; for keys see **zlib gzip**). 


**zlib stream inflate** ?**-dictionary** *bindata*?
 The stream will be a decompressing stream that takes raw compressed input and produces uncompressed output. If *bindata* is supplied, it is a compression dictionary to use. Note that there are no checks in place to determine whether the compression dictionary is correct. 



 ### Checksumming subcommands

  
**zlib adler32** *string* ?*initValue*?
 Compute a checksum of binary string *string* using the Adler-32 algorithm. If given, *initValue* is used to initialize the checksum engine. 


**zlib crc32** *string* ?*initValue*?
 Compute a checksum of binary string *string* using the CRC-32 algorithm. If given, *initValue* is used to initialize the checksum engine. 

 Streaming instance command
--------------------------

 Streaming compression instance commands are produced by the **zlib stream** command. They are used by calling their **put** subcommand one or more times to load data in, and their **get** subcommand one or more times to extract the transformed data.  The full set of subcommands supported by a streaming instance command, *stream*, is as follows: 


 
*stream* **add** ?*option...*? *data*

 A short-cut for “*stream* **put** ?*option...*? *data*” followed by “*stream* **get**”. 


*stream* **checksum**

 Returns the checksum of the uncompressed data seen so far by this stream. 


*stream* **close**

 Deletes this stream and frees up all resources associated with it. 


*stream* **eof**

 Returns a boolean indicating whether the end of the stream (as determined by the compressed data itself) has been reached. Not all formats support detection of the end of the stream. 


*stream* **finalize**

 A short-cut for “*stream* **put -finalize {}**”. 


*stream* **flush**

 A short-cut for “*stream* **put -flush {}**”. 


*stream* **fullflush**

 A short-cut for “*stream* **put -fullflush {}**”. 


*stream* **get** ?*count*?
 Return up to *count* bytes from *stream*'s internal buffers with the transformation applied. If *count* is omitted, the entire contents of the buffers are returned. *stream* **header** Return the gzip header description dictionary extracted from the stream. Only supported for streams created with their *mode* parameter set to **gunzip**. 


*stream* **put** ?*option...*? *data*

 Append the contents of the binary string *data* to *stream*'s internal buffers while applying the transformation. The following *option*s are supported (or an unambiguous prefix of them), which are used to modify the way in which the transformation is applied: 
 
**-dictionary** *binData*

 Sets the compression dictionary to use when working with compressing or decompressing the data to be *binData*. 

**-finalize**
 Mark the stream as finished, ensuring that all bytes have been wholly compressed or decompressed. For gzip streams, this also ensures that the footer is written to the stream. The stream will need to be reset before having more data written to it after this, though data can still be read out of the stream with the **get** subcommand.  This option is mutually exclusive with the **-flush** and **-fullflush** options. 



**-flush**
 Ensure that a decompressor consuming the bytes that the current (compressing) stream is producing will be able to produce all the bytes that have been compressed so far, at some performance penalty.  This option is mutually exclusive with the **-finalize** and **-fullflush** options. 



**-fullflush**
 Ensure that not only can a decompressor handle all the bytes produced so far (as with **-flush** above) but also that it can restart from this point if it detects that the stream is partially corrupt. This incurs a substantial performance penalty.  This option is mutually exclusive with the **-finalize** and **-flush** options. 






*stream* **reset**

 Puts any stream, including those that have been finalized or that have reached eof, back into a state where it can process more data. Throws away all internally buffered data. 

 Examples
--------

 To compress a Tcl string, it should be first converted to a particular charset encoding since the **zlib** command always operates on binary strings. 

```
set binData [encoding convertto utf-8 $string]
set compData [**zlib compress** $binData]
```
  When converting back, it is also important to reverse the charset encoding: 



```
set binData [**zlib decompress** $compData]
set string [encoding convertfrom utf-8 $binData]
```
  The compression operation from above can also be done with streams, which is especially helpful when you want to accumulate the data by stages: 



```
set strm [**zlib stream** compress]
$*strm* **put** [encoding convertto utf-8 $string]
# ...
$*strm* **finalize**
set compData [$*strm* **get**]
$*strm* **close**
```
 See also
--------

 **binary**, **[chan](chan.htm)**, **[encoding](encoding.htm)**, **[Tcl\_ZlibDeflate](https://www.tcl.tk/man/tcl/TclLib/TclZlib.htm)**, **RFC1950 - RFC1952** Copyright © 2008-2012 Donal K. Fellows 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/zlib.htm>

interp
======

  
[NAME](interp.htm#M2) interp — Create and manipulate Tcl interpreters 
[SYNOPSIS](interp.htm#M3) 
[DESCRIPTION](interp.htm#M4) 
[THE INTERP COMMAND](interp.htm#M5)  
[**interp** **alias** *srcPath* *srcToken*](interp.htm#M6) 
[**interp** **alias** *srcPath* *srcToken* **{}**](interp.htm#M7) 
[**interp** **alias** *srcPath* *srcCmd* *targetPath* *targetCmd* ?*arg arg ...*?](interp.htm#M8) 
[**interp** **aliases** ?*path*?](interp.htm#M9) 
[**interp bgerror** *path* ?*cmdPrefix*?](interp.htm#M10) 
[**interp** **cancel** ?**-unwind**? ?**--**? ?*path*? ?*result*?](interp.htm#M11) 
[**interp** **create** ?**-safe**? ?**--**? ?*path*?](interp.htm#M12) 
[**interp** **debug** *path* ?**-frame** ?*bool*??](interp.htm#M13) 
[**interp** **delete** ?*path ...?*](interp.htm#M14) 
[**interp** **eval** *path arg* ?*arg ...*?](interp.htm#M15) 
[**interp exists** *path*](interp.htm#M16) 
[**interp expose** *path* *hiddenName* ?*exposedCmdName*?](interp.htm#M17) 
[**interp** **hide** *path* *exposedCmdName* ?*hiddenCmdName*?](interp.htm#M18) 
[**interp** **hidden** *path*](interp.htm#M19) 
[**interp** **invokehidden** *path* ?*-option ...*? *hiddenCmdName* ?*arg ...*?](interp.htm#M20) 
[**interp issafe** ?*path*?](interp.htm#M21) 
[**interp** **limit** *path* *limitType* ?*-option*? ?*value* *...*?](interp.htm#M22) 
[**interp marktrusted** *path*](interp.htm#M23) 
[**interp** **recursionlimit** *path* ?*newlimit*?](interp.htm#M24) 
[**interp** **share** *srcPath channelId destPath*](interp.htm#M25) 
[**interp** **slaves** ?*path*?](interp.htm#M26) 
[**interp** **target** *path alias*](interp.htm#M27) 
[**interp** **transfer** *srcPath channelId destPath*](interp.htm#M28) 






















 
[SLAVE COMMAND](interp.htm#M29)  
[*slave* **aliases**](interp.htm#M30) 
[*slave* **alias** *srcToken*](interp.htm#M31) 
[*slave* **alias** *srcToken* **{}**](interp.htm#M32) 
[*slave* **alias** *srcCmd targetCmd* ?*arg ..*?](interp.htm#M33) 
[*slave* **bgerror** ?*cmdPrefix*?](interp.htm#M34) 
[*slave* **eval** *arg* ?*arg ..*?](interp.htm#M35) 
[*slave* **expose** *hiddenName* ?*exposedCmdName*?](interp.htm#M36) 
[*slave* **hide** *exposedCmdName* ?*hiddenCmdName*?](interp.htm#M37) 
[*slave* **hidden**](interp.htm#M38) 
[*slave* **invokehidden** ?*-option ...*? *hiddenName* ?*arg ..*?](interp.htm#M39) 
[*slave* **issafe**](interp.htm#M40) 
[*slave* **limit** *limitType* ?*-option*? ?*value* *...*?](interp.htm#M41) 
[*slave* **marktrusted**](interp.htm#M42) 
[*slave* **recursionlimit** ?*newlimit*?](interp.htm#M43) 













 
[SAFE INTERPRETERS](interp.htm#M44) 
[ALIAS INVOCATION](interp.htm#M45) 
[HIDDEN COMMANDS](interp.htm#M46) 
[RESOURCE LIMITS](interp.htm#M47) 
[LIMIT OPTIONS](interp.htm#M48)  
[**-command**](interp.htm#M49) 
[**-granularity**](interp.htm#M50) 
[**-milliseconds**](interp.htm#M51) 
[**-seconds**](interp.htm#M52) 
[**-value**](interp.htm#M53) 




 
[BACKGROUND EXCEPTION HANDLING](interp.htm#M54) 
[CREDITS](interp.htm#M55) 
[EXAMPLES](interp.htm#M56) 
[SEE ALSO](interp.htm#M57) 
[KEYWORDS](interp.htm#M58) 














 Name
----

 interp — Create and manipulate Tcl interpreters Synopsis
--------

 **interp** *subcommand* ?*arg arg ...*?  
 Description
-----------

 This command makes it possible to create one or more new Tcl interpreters that co-exist with the creating interpreter in the same application. The creating interpreter is called the *master* and the new interpreter is called a *slave*. A master can create any number of slaves, and each slave can itself create additional slaves for which it is master, resulting in a hierarchy of interpreters.  Each interpreter is independent from the others: it has its own name space for commands, procedures, and global variables. A master interpreter may create connections between its slaves and itself using a mechanism called an *alias*. An *alias* is a command in a slave interpreter which, when invoked, causes a command to be invoked in its master interpreter or in another slave interpreter. The only other connections between interpreters are through environment variables (the **[env](tclvars.htm)** variable), which are normally shared among all interpreters in the application, and by resource limit exceeded callbacks. Note that the name space for files (such as the names returned by the **[open](open.htm)** command) is no longer shared between interpreters. Explicit commands are provided to share files and to transfer references to open files from one interpreter to another. 


 The **interp** command also provides support for *safe* interpreters. A safe interpreter is a slave whose functions have been greatly restricted, so that it is safe to execute untrusted scripts without fear of them damaging other interpreters or the application's environment. For example, all IO channel creation commands and subprocess creation commands are made inaccessible to safe interpreters. See **[SAFE INTERPRETERS](#M44)** below for more information on what features are present in a safe interpreter. The dangerous functionality is not removed from the safe interpreter; instead, it is *hidden*, so that only trusted interpreters can obtain access to it. For a detailed explanation of hidden commands, see **[HIDDEN COMMANDS](#M46)**, below. The alias mechanism can be used for protected communication (analogous to a kernel call) between a slave interpreter and its master. See **[ALIAS INVOCATION](#M45)**, below, for more details on how the alias mechanism works. 


 A qualified interpreter name is a proper Tcl lists containing a subset of its ancestors in the interpreter hierarchy, terminated by the string naming the interpreter in its immediate master. Interpreter names are relative to the interpreter in which they are used. For example, if “**a**” is a slave of the current interpreter and it has a slave “**a1**”, which in turn has a slave “**a11**”, the qualified name of “**a11**” in “**a**” is the list “**a1 a11**”. 


 The **interp** command, described below, accepts qualified interpreter names as arguments; the interpreter in which the command is being evaluated can always be referred to as **{}** (the empty list or string). Note that it is impossible to refer to a master (ancestor) interpreter by name in a slave interpreter except through aliases. Also, there is no global name by which one can refer to the first interpreter created in an application. Both restrictions are motivated by safety concerns. 


The interp command
------------------

 The **interp** command is used to create, delete, and manipulate slave interpreters, and to share or transfer channels between interpreters. It can have any of several forms, depending on the *subcommand* argument: 
 
**interp** **alias** *srcPath* *srcToken*

 Returns a Tcl list whose elements are the *targetCmd* and *arg*s associated with the alias represented by *srcToken* (this is the value returned when the alias was created; it is possible that the name of the source command in the slave is different from *srcToken*). 


**interp** **alias** *srcPath* *srcToken* **{}**

 Deletes the alias for *srcToken* in the slave interpreter identified by *srcPath*. *srcToken* refers to the value returned when the alias was created; if the source command has been renamed, the renamed command will be deleted. 


**interp** **alias** *srcPath* *srcCmd* *targetPath* *targetCmd* ?*arg arg ...*?
 This command creates an alias between one slave and another (see the **alias** slave command below for creating aliases between a slave and its master). In this command, either of the slave interpreters may be anywhere in the hierarchy of interpreters under the interpreter invoking the command. *SrcPath* and *srcCmd* identify the source of the alias. *SrcPath* is a Tcl list whose elements select a particular interpreter. For example, “**a b**” identifies an interpreter “**b**”, which is a slave of interpreter “**a**”, which is a slave of the invoking interpreter. An empty list specifies the interpreter invoking the command. *srcCmd* gives the name of a new command, which will be created in the source interpreter. *TargetPath* and *targetCmd* specify a target interpreter and command, and the *arg* arguments, if any, specify additional arguments to *targetCmd* which are prepended to any arguments specified in the invocation of *srcCmd*. *TargetCmd* may be undefined at the time of this call, or it may already exist; it is not created by this command. The alias arranges for the given target command to be invoked in the target interpreter whenever the given source command is invoked in the source interpreter. See **[ALIAS INVOCATION](#M45)** below for more details. The command returns a token that uniquely identifies the command created *srcCmd*, even if the command is renamed afterwards. The token may but does not have to be equal to *srcCmd*. 


**interp** **aliases** ?*path*?
 This command returns a Tcl list of the tokens of all the source commands for aliases defined in the interpreter identified by *path*. The tokens correspond to the values returned when the aliases were created (which may not be the same as the current names of the commands). 


**interp bgerror** *path* ?*cmdPrefix*?
 This command either gets or sets the current background exception handler for the interpreter identified by *path*. If *cmdPrefix* is absent, the current background exception handler is returned, and if it is present, it is a list of words (of minimum length one) that describes what to set the interpreter's background exception handler to. See the **[BACKGROUND EXCEPTION HANDLING](#M54)** section for more details. 


**interp** **cancel** ?**-unwind**? ?**--**? ?*path*? ?*result*?
 Cancels the script being evaluated in the interpreter identified by *path*. Without the **-unwind** switch the evaluation stack for the interpreter is unwound until an enclosing catch command is found or there are no further invocations of the interpreter left on the call stack. With the **-unwind** switch the evaluation stack for the interpreter is unwound without regard to any intervening catch command until there are no further invocations of the interpreter left on the call stack. The **--** switch can be used to mark the end of switches; it may be needed if *path* is an unusual value such as **-safe**. If *result* is present, it will be used as the error message string; otherwise, a default error message string will be used. 


**interp** **create** ?**-safe**? ?**--**? ?*path*?
 Creates a slave interpreter identified by *path* and a new command, called a *slave command*. The name of the slave command is the last component of *path*. The new slave interpreter and the slave command are created in the interpreter identified by the path obtained by removing the last component from *path*. For example, if *path* is **a b c** then a new slave interpreter and slave command named **c** are created in the interpreter identified by the path **a b**. The slave command may be used to manipulate the new interpreter as described below. If *path* is omitted, Tcl creates a unique name of the form **interp***x*, where *x* is an integer, and uses it for the interpreter and the slave command. If the **-safe** switch is specified (or if the master interpreter is a safe interpreter), the new slave interpreter will be created as a safe interpreter with limited functionality; otherwise the slave will include the full set of Tcl built-in commands and variables. The **--** switch can be used to mark the end of switches; it may be needed if *path* is an unusual value such as **-safe**. The result of the command is the name of the new interpreter. The name of a slave interpreter must be unique among all the slaves for its master; an error occurs if a slave interpreter by the given name already exists in this master. The initial recursion limit of the slave interpreter is set to the current recursion limit of its parent interpreter. 


**interp** **debug** *path* ?**-frame** ?*bool*??
 Controls whether frame-level stack information is captured in the slave interpreter identified by *path*. If no arguments are given, option and current setting are returned. If **-frame** is given, the debug setting is set to the given boolean if provided and the current setting is returned. This only effects the output of **[info frame](info.htm)**, in that exact frame-level information for command invocation at the bytecode level is only captured with this setting on.  For example, with code like 



```
**[proc](proc.htm)** mycontrol {... script} {
  ...
  **[uplevel](uplevel.htm)** 1 $script
  ...
}

**[proc](proc.htm)** dosomething {...} {
  ...
  mycontrol {
    somecode
  }
}
```
  the standard setting will provide a relative line number for the command **somecode** and the relevant frame will be of type **[eval](eval.htm)**. With frame-debug active on the other hand the tracking extends so far that the system will be able to determine the file and absolute line number of this command, and return a frame of type **[source](source.htm)**. This more exact information is paid for with slower execution of all commands. 


Note that once it is on, this flag cannot be switched back off: such attempts are silently ignored. This is needed to maintain the consistency of the underlying interpreter's state. 




**interp** **delete** ?*path ...?*

 Deletes zero or more interpreters given by the optional *path* arguments, and for each interpreter, it also deletes its slaves. The command also deletes the slave command for each interpreter deleted. For each *path* argument, if no interpreter by that name exists, the command raises an error. 


**interp** **eval** *path arg* ?*arg ...*?
 This command concatenates all of the *arg* arguments in the same fashion as the **[concat](concat.htm)** command, then evaluates the resulting string as a Tcl script in the slave interpreter identified by *path*. The result of this evaluation (including all **[return](return.htm)** options, such as **-errorinfo** and **-errorcode** information, if an error occurs) is returned to the invoking interpreter. Note that the script will be executed in the current context stack frame of the *path* interpreter; this is so that the implementations (in a master interpreter) of aliases in a slave interpreter can execute scripts in the slave that find out information about the slave's current state and stack frame. 


**interp exists** *path*

 Returns **1** if a slave interpreter by the specified *path* exists in this master, **0** otherwise. If *path* is omitted, the invoking interpreter is used. 


**interp expose** *path* *hiddenName* ?*exposedCmdName*?
 Makes the hidden command *hiddenName* exposed, eventually bringing it back under a new *exposedCmdName* name (this name is currently accepted only if it is a valid global name space name without any ::), in the interpreter denoted by *path*. If an exposed command with the targeted name already exists, this command fails. Hidden commands are explained in more detail in **[HIDDEN COMMANDS](#M46)**, below. 


**interp** **hide** *path* *exposedCmdName* ?*hiddenCmdName*?
 Makes the exposed command *exposedCmdName* hidden, renaming it to the hidden command *hiddenCmdName*, or keeping the same name if *hiddenCmdName* is not given, in the interpreter denoted by *path*. If a hidden command with the targeted name already exists, this command fails. Currently both *exposedCmdName* and *hiddenCmdName* can not contain namespace qualifiers, or an error is raised. Commands to be hidden by **interp hide** are looked up in the global namespace even if the current namespace is not the global one. This prevents slaves from fooling a master interpreter into hiding the wrong command, by making the current namespace be different from the global one. Hidden commands are explained in more detail in **[HIDDEN COMMANDS](#M46)**, below. 


**interp** **hidden** *path*

 Returns a list of the names of all hidden commands in the interpreter identified by *path*. 


**interp** **invokehidden** *path* ?*-option ...*? *hiddenCmdName* ?*arg ...*?
 Invokes the hidden command *hiddenCmdName* with the arguments supplied in the interpreter denoted by *path*. No substitutions or evaluation are applied to the arguments. Three *-option*s are supported, all of which start with **-**: **-namespace** (which takes a single argument afterwards, *nsName*), **-global**, and **--**. If the **-namespace** flag is present, the hidden command is invoked in the namespace called *nsName* in the target interpreter. If the **-global** flag is present, the hidden command is invoked at the global level in the target interpreter; otherwise it is invoked at the current call frame and can access local variables in that and outer call frames. The **--** flag allows the *hiddenCmdName* argument to start with a “-” character, and is otherwise unnecessary. If both the **-namespace** and **-global** flags are present, the **-namespace** flag is ignored. Note that the hidden command will be executed (by default) in the current context stack frame of the *path* interpreter. Hidden commands are explained in more detail in **[HIDDEN COMMANDS](#M46)**, below. 


**interp issafe** ?*path*?
 Returns **1** if the interpreter identified by the specified *path* is safe, **0** otherwise. 


**interp** **limit** *path* *limitType* ?*-option*? ?*value* *...*?
 Sets up, manipulates and queries the configuration of the resource limit *limitType* for the interpreter denoted by *path*. If no *-option* is specified, return the current configuration of the limit. If *-option* is the sole argument, return the value of that option. Otherwise, a list of *-option*/*value* argument pairs must supplied. See **[RESOURCE LIMITS](#M47)** below for a more detailed explanation of what limits and options are supported. 


**interp marktrusted** *path*

 Marks the interpreter identified by *path* as trusted. Does not expose the hidden commands. This command can only be invoked from a trusted interpreter. The command has no effect if the interpreter identified by *path* is already trusted. 


**interp** **recursionlimit** *path* ?*newlimit*?
 Returns the maximum allowable nesting depth for the interpreter specified by *path*. If *newlimit* is specified, the interpreter recursion limit will be set so that nesting of more than *newlimit* calls to **[Tcl\_Eval](https://www.tcl.tk/man/tcl/TclLib/Eval.htm)** and related procedures in that interpreter will return an error. The *newlimit* value is also returned. The *newlimit* value must be a positive integer between 1 and the maximum value of a non-long integer on the platform.  The command sets the maximum size of the Tcl call stack only. It cannot by itself prevent stack overflows on the C stack being used by the application. If your machine has a limit on the size of the C stack, you may get stack overflows before reaching the limit set by the command. If this happens, see if there is a mechanism in your system for increasing the maximum size of the C stack. 




**interp** **share** *srcPath channelId destPath*

 Causes the IO channel identified by *channelId* to become shared between the interpreter identified by *srcPath* and the interpreter identified by *destPath*. Both interpreters have the same permissions on the IO channel. Both interpreters must close it to close the underlying IO channel; IO channels accessible in an interpreter are automatically closed when an interpreter is destroyed. 


**interp** **slaves** ?*path*?
 Returns a Tcl list of the names of all the slave interpreters associated with the interpreter identified by *path*. If *path* is omitted, the invoking interpreter is used. 


**interp** **target** *path alias*

 Returns a Tcl list describing the target interpreter for an alias. The alias is specified with an interpreter path and source command name, just as in **interp alias** above. The name of the target interpreter is returned as an interpreter path, relative to the invoking interpreter. If the target interpreter for the alias is the invoking interpreter then an empty list is returned. If the target interpreter for the alias is not the invoking interpreter or one of its descendants then an error is generated. The target command does not have to be defined at the time of this invocation. 


**interp** **transfer** *srcPath channelId destPath*

 Causes the IO channel identified by *channelId* to become available in the interpreter identified by *destPath* and unavailable in the interpreter identified by *srcPath*. 

 Slave command
-------------

 For each slave interpreter created with the **interp** command, a new Tcl command is created in the master interpreter with the same name as the new interpreter. This command may be used to invoke various operations on the interpreter. It has the following general form: 

```
*slave command* ?*arg arg ...*?
```
  *Slave* is the name of the interpreter, and *command* and the *arg*s determine the exact behavior of the command. The valid forms of this command are: 


 
*slave* **aliases**

 Returns a Tcl list whose elements are the tokens of all the aliases in *slave*. The tokens correspond to the values returned when the aliases were created (which may not be the same as the current names of the commands). 


*slave* **alias** *srcToken*

 Returns a Tcl list whose elements are the *targetCmd* and *arg*s associated with the alias represented by *srcToken* (this is the value returned when the alias was created; it is possible that the actual source command in the slave is different from *srcToken*). 


*slave* **alias** *srcToken* **{}**

 Deletes the alias for *srcToken* in the slave interpreter. *srcToken* refers to the value returned when the alias was created; if the source command has been renamed, the renamed command will be deleted. 


*slave* **alias** *srcCmd targetCmd* ?*arg ..*?
 Creates an alias such that whenever *srcCmd* is invoked in *slave*, *targetCmd* is invoked in the master. The *arg* arguments will be passed to *targetCmd* as additional arguments, prepended before any arguments passed in the invocation of *srcCmd*. See **[ALIAS INVOCATION](#M45)** below for details. The command returns a token that uniquely identifies the command created *srcCmd*, even if the command is renamed afterwards. The token may but does not have to be equal to *srcCmd*. 


*slave* **bgerror** ?*cmdPrefix*?
 This command either gets or sets the current background exception handler for the *slave* interpreter. If *cmdPrefix* is absent, the current background exception handler is returned, and if it is present, it is a list of words (of minimum length one) that describes what to set the interpreter's background exception handler to. See the **[BACKGROUND EXCEPTION HANDLING](#M54)** section for more details. 


*slave* **eval** *arg* ?*arg ..*?
 This command concatenates all of the *arg* arguments in the same fashion as the **[concat](concat.htm)** command, then evaluates the resulting string as a Tcl script in *slave*. The result of this evaluation (including all **[return](return.htm)** options, such as **-errorinfo** and **-errorcode** information, if an error occurs) is returned to the invoking interpreter. Note that the script will be executed in the current context stack frame of *slave*; this is so that the implementations (in a master interpreter) of aliases in a slave interpreter can execute scripts in the slave that find out information about the slave's current state and stack frame. 


*slave* **expose** *hiddenName* ?*exposedCmdName*?
 This command exposes the hidden command *hiddenName*, eventually bringing it back under a new *exposedCmdName* name (this name is currently accepted only if it is a valid global name space name without any ::), in *slave*. If an exposed command with the targeted name already exists, this command fails. For more details on hidden commands, see **[HIDDEN COMMANDS](#M46)**, below. 


*slave* **hide** *exposedCmdName* ?*hiddenCmdName*?
 This command hides the exposed command *exposedCmdName*, renaming it to the hidden command *hiddenCmdName*, or keeping the same name if the argument is not given, in the *slave* interpreter. If a hidden command with the targeted name already exists, this command fails. Currently both *exposedCmdName* and *hiddenCmdName* can not contain namespace qualifiers, or an error is raised. Commands to be hidden are looked up in the global namespace even if the current namespace is not the global one. This prevents slaves from fooling a master interpreter into hiding the wrong command, by making the current namespace be different from the global one. For more details on hidden commands, see **[HIDDEN COMMANDS](#M46)**, below. 


*slave* **hidden**

 Returns a list of the names of all hidden commands in *slave*. 


*slave* **invokehidden** ?*-option ...*? *hiddenName* ?*arg ..*?
 This command invokes the hidden command *hiddenName* with the supplied arguments, in *slave*. No substitutions or evaluations are applied to the arguments. Three *-option*s are supported, all of which start with **-**: **-namespace** (which takes a single argument afterwards, *nsName*), **-global**, and **--**. If the **-namespace** flag is given, the hidden command is invoked in the specified namespace in the slave. If the **-global** flag is given, the command is invoked at the global level in the slave; otherwise it is invoked at the current call frame and can access local variables in that or outer call frames. The **--** flag allows the *hiddenCmdName* argument to start with a “-” character, and is otherwise unnecessary. If both the **-namespace** and **-global** flags are given, the **-namespace** flag is ignored. Note that the hidden command will be executed (by default) in the current context stack frame of *slave*. For more details on hidden commands, see **[HIDDEN COMMANDS](#M46)**, below. 


*slave* **issafe**

 Returns **1** if the slave interpreter is safe, **0** otherwise. 


*slave* **limit** *limitType* ?*-option*? ?*value* *...*?
 Sets up, manipulates and queries the configuration of the resource limit *limitType* for the slave interpreter. If no *-option* is specified, return the current configuration of the limit. If *-option* is the sole argument, return the value of that option. Otherwise, a list of *-option*/*value* argument pairs must supplied. See **[RESOURCE LIMITS](#M47)** below for a more detailed explanation of what limits and options are supported. 


*slave* **marktrusted**

 Marks the slave interpreter as trusted. Can only be invoked by a trusted interpreter. This command does not expose any hidden commands in the slave interpreter. The command has no effect if the slave is already trusted. 


*slave* **recursionlimit** ?*newlimit*?
 Returns the maximum allowable nesting depth for the *slave* interpreter. If *newlimit* is specified, the recursion limit in *slave* will be set so that nesting of more than *newlimit* calls to **[Tcl\_Eval()](https://www.tcl.tk/man/tcl/TclLib/Eval.htm)** and related procedures in *slave* will return an error. The *newlimit* value is also returned. The *newlimit* value must be a positive integer between 1 and the maximum value of a non-long integer on the platform.  The command sets the maximum size of the Tcl call stack only. It cannot by itself prevent stack overflows on the C stack being used by the application. If your machine has a limit on the size of the C stack, you may get stack overflows before reaching the limit set by the command. If this happens, see if there is a mechanism in your system for increasing the maximum size of the C stack. 



 Safe interpreters
-----------------

 A safe interpreter is one with restricted functionality, so that is safe to execute an arbitrary script from your worst enemy without fear of that script damaging the enclosing application or the rest of your computing environment. In order to make an interpreter safe, certain commands and variables are removed from the interpreter. For example, commands to create files on disk are removed, and the **[exec](exec.htm)** command is removed, since it could be used to cause damage through subprocesses. Limited access to these facilities can be provided, by creating aliases to the master interpreter which check their arguments carefully and provide restricted access to a safe subset of facilities. For example, file creation might be allowed in a particular subdirectory and subprocess invocation might be allowed for a carefully selected and fixed set of programs.  A safe interpreter is created by specifying the **-safe** switch to the **interp create** command. Furthermore, any slave created by a safe interpreter will also be safe. 


 A safe interpreter is created with exactly the following set of built-in commands: 




|  |  |  |  |
| --- | --- | --- | --- |
| **[after](after.htm)** | **[append](append.htm)** | **[apply](apply.htm)** | **[array](array.htm)** |
| **[binary](binary.htm)** | **[break](break.htm)** | **[catch](catch.htm)** | **[chan](chan.htm)** |
| **[clock](clock.htm)** | **[close](close.htm)** | **[concat](concat.htm)** | **[continue](continue.htm)** |
| **[dict](dict.htm)** | **[eof](eof.htm)** | **[error](error.htm)** | **[eval](eval.htm)** |
| **[expr](expr.htm)** | **[fblocked](fblocked.htm)** | **[fcopy](fcopy.htm)** | **[fileevent](fileevent.htm)** |
| **[flush](flush.htm)** | **[for](for.htm)** | **[foreach](foreach.htm)** | **[format](format.htm)** |
| **[gets](gets.htm)** | **[global](global.htm)** | **[if](if.htm)** | **[incr](incr.htm)** |
| **[info](info.htm)** | **interp** | **[join](join.htm)** | **[lappend](lappend.htm)** |
| **[lassign](lassign.htm)** | **[lindex](lindex.htm)** | **[linsert](linsert.htm)** | **[list](list.htm)** |
| **[llength](llength.htm)** | **[lrange](lrange.htm)** | **[lrepeat](lrepeat.htm)** | **[lreplace](lreplace.htm)** |
| **[lsearch](lsearch.htm)** | **[lset](lset.htm)** | **[lsort](lsort.htm)** | **[namespace](namespace.htm)** |
| **[package](package.htm)** | **[pid](pid.htm)** | **[proc](proc.htm)** | **[puts](puts.htm)** |
| **[read](read.htm)** | **[regexp](regexp.htm)** | **[regsub](regsub.htm)** | **[rename](rename.htm)** |
| **[return](return.htm)** | **[scan](scan.htm)** | **[seek](seek.htm)** | **[set](set.htm)** |
| **[split](split.htm)** | **[string](string.htm)** | **[subst](subst.htm)** | **[switch](switch.htm)** |
| **[tell](tell.htm)** | **time** | **[trace](trace.htm)** | **[unset](unset.htm)** |
| **[update](update.htm)** | **[uplevel](uplevel.htm)** | **[upvar](upvar.htm)** | **[variable](variable.htm)** |
| **[vwait](vwait.htm)** | **[while](while.htm)** |

 The following commands are hidden by **interp create** when it creates a safe interpreter: 

|  |  |  |  |
| --- | --- | --- | --- |
| **[cd](cd.htm)** | **[encoding](encoding.htm)** | **[exec](exec.htm)** | **[exit](exit.htm)** |
| **[fconfigure](fconfigure.htm)** | **[file](file.htm)** | **[glob](glob.htm)** | **[load](load.htm)** |
| **[open](open.htm)** | **[pwd](pwd.htm)** | **[socket](socket.htm)** | **[source](source.htm)** |
| **[unload](unload.htm)** |

 These commands can be recreated later as Tcl procedures or aliases, or re-exposed by **interp expose**.  The following commands from Tcl's library of support procedures are not present in a safe interpreter: 




|  |  |  |
| --- | --- | --- |
| **auto\_exec\_ok** | **[auto\_import](library.htm)** | **[auto\_load](library.htm)** |
| **auto\_load\_index** | **[auto\_qualify](library.htm)** | **[unknown](unknown.htm)** |

 Note in particular that safe interpreters have no default **[unknown](unknown.htm)** command, so Tcl's default autoloading facilities are not available. Autoload access to Tcl's commands that are normally autoloaded: 

|  |  |
| --- | --- |
| **[auto\_mkindex](library.htm)** | **auto\_mkindex\_old** |
| **[auto\_reset](library.htm)** | **[history](history.htm)** |
| **[parray](library.htm)** | **pkg\_mkIndex** |
| **::pkg::create** | **::safe::interpAddToAccessPath** |
| **::safe::interpCreate** | **::safe::interpConfigure** |
| **::safe::interpDelete** | **::safe::interpFindInAccessPath** |
| **::safe::interpInit** | **::safe::setLogCmd** |
| **tcl\_endOfWord** | **tcl\_findLibrary** |
| **tcl\_startOfNextWord** | **tcl\_startOfPreviousWord** |
| **tcl\_wordBreakAfter** | **tcl\_wordBreakBefore** |

 can only be provided by explicit definition of an **[unknown](unknown.htm)** command in the safe interpreter. This will involve exposing the **[source](source.htm)** command. This is most easily accomplished by creating the safe interpreter with Tcl's **[Safe-Tcl](safe.htm)** mechanism. **[Safe-Tcl](safe.htm)** provides safe versions of **[source](source.htm)**, **[load](load.htm)**, and other Tcl commands needed to support autoloading of commands and the loading of packages.  In addition, the **[env](tclvars.htm)** variable is not present in a safe interpreter, so it cannot share environment variables with other interpreters. The **[env](tclvars.htm)** variable poses a security risk, because users can store sensitive information in an environment variable. For example, the PGP manual recommends storing the PGP private key protection password in the environment variable *PGPPASS*. Making this variable available to untrusted code executing in a safe interpreter would incur a security risk. 


 If extensions are loaded into a safe interpreter, they may also restrict their own functionality to eliminate unsafe commands. For a discussion of management of extensions for safety see the manual entries for **[Safe-Tcl](safe.htm)** and the **[load](load.htm)** Tcl command. 


 A safe interpreter may not alter the recursion limit of any interpreter, including itself. 


Alias invocation
----------------

 The alias mechanism has been carefully designed so that it can be used safely when an untrusted script is executing in a safe slave and the target of the alias is a trusted master. The most important thing in guaranteeing safety is to ensure that information passed from the slave to the master is never evaluated or substituted in the master; if this were to occur, it would enable an evil script in the slave to invoke arbitrary functions in the master, which would compromise security.  When the source for an alias is invoked in the slave interpreter, the usual Tcl substitutions are performed when parsing that command. These substitutions are carried out in the source interpreter just as they would be for any other command invoked in that interpreter. The command procedure for the source command takes its arguments and merges them with the *targetCmd* and *arg*s for the alias to create a new array of arguments. If the words of *srcCmd* were “*srcCmd arg1 arg2 ... argN*”, the new set of words will be “*targetCmd arg arg ... arg arg1 arg2 ... argN*”, where *targetCmd* and *arg*s are the values supplied when the alias was created. *TargetCmd* is then used to locate a command procedure in the target interpreter, and that command procedure is invoked with the new set of arguments. An error occurs if there is no command named *targetCmd* in the target interpreter. No additional substitutions are performed on the words: the target command procedure is invoked directly, without going through the normal Tcl evaluation mechanism. Substitutions are thus performed on each word exactly once: *targetCmd* and *args* were substituted when parsing the command that created the alias, and *arg1 - argN* are substituted when the alias's source command is parsed in the source interpreter. 


 When writing the *targetCmd*s for aliases in safe interpreters, it is very important that the arguments to that command never be evaluated or substituted, since this would provide an escape mechanism whereby the slave interpreter could execute arbitrary code in the master. This in turn would compromise the security of the system. 


Hidden commands
---------------

 Safe interpreters greatly restrict the functionality available to Tcl programs executing within them. Allowing the untrusted Tcl program to have direct access to this functionality is unsafe, because it can be used for a variety of attacks on the environment. However, there are times when there is a legitimate need to use the dangerous functionality in the context of the safe interpreter. For example, sometimes a program must be **[source](source.htm)**d into the interpreter. Another example is Tk, where windows are bound to the hierarchy of windows for a specific interpreter; some potentially dangerous functions, e.g. window management, must be performed on these windows within the interpreter context.  The **interp** command provides a solution to this problem in the form of *hidden commands*. Instead of removing the dangerous commands entirely from a safe interpreter, these commands are hidden so they become unavailable to Tcl scripts executing in the interpreter. However, such hidden commands can be invoked by any trusted ancestor of the safe interpreter, in the context of the safe interpreter, using **interp invoke**. Hidden commands and exposed commands reside in separate name spaces. It is possible to define a hidden command and an exposed command by the same name within one interpreter. 


 Hidden commands in a slave interpreter can be invoked in the body of procedures called in the master during alias invocation. For example, an alias for **[source](source.htm)** could be created in a slave interpreter. When it is invoked in the slave interpreter, a procedure is called in the master interpreter to check that the operation is allowable (e.g. it asks to source a file that the slave interpreter is allowed to access). The procedure then it invokes the hidden **[source](source.htm)** command in the slave interpreter to actually source in the contents of the file. Note that two commands named **[source](source.htm)** exist in the slave interpreter: the alias, and the hidden command. 


 Because a master interpreter may invoke a hidden command as part of handling an alias invocation, great care must be taken to avoid evaluating any arguments passed in through the alias invocation. Otherwise, malicious slave interpreters could cause a trusted master interpreter to execute dangerous commands on their behalf. See the section on **[ALIAS INVOCATION](#M45)** for a more complete discussion of this topic. To help avoid this problem, no substitutions or evaluations are applied to arguments of **interp invokehidden**. 


 Safe interpreters are not allowed to invoke hidden commands in themselves or in their descendants. This prevents safe slaves from gaining access to hidden functionality in themselves or their descendants. 


 The set of hidden commands in an interpreter can be manipulated by a trusted interpreter using **interp expose** and **interp hide**. The **interp expose** command moves a hidden command to the set of exposed commands in the interpreter identified by *path*, potentially renaming the command in the process. If an exposed command by the targeted name already exists, the operation fails. Similarly, **interp hide** moves an exposed command to the set of hidden commands in that interpreter. Safe interpreters are not allowed to move commands between the set of hidden and exposed commands, in either themselves or their descendants. 


 Currently, the names of hidden commands cannot contain namespace qualifiers, and you must first rename a command in a namespace to the global namespace before you can hide it. Commands to be hidden by **interp hide** are looked up in the global namespace even if the current namespace is not the global one. This prevents slaves from fooling a master interpreter into hiding the wrong command, by making the current namespace be different from the global one. 


Resource limits
---------------

 Every interpreter has two kinds of resource limits that may be imposed by any master interpreter upon its slaves. Command limits (of type **command**) restrict the total number of Tcl commands that may be executed by an interpreter (as can be inspected via the **[info cmdcount](info.htm)** command), and time limits (of type **time**) place a limit by which execution within the interpreter must complete. Note that time limits are expressed as *absolute* times (as in **[clock seconds](clock.htm)**) and not relative times (as in **[after](after.htm)**) because they may be modified after creation.  When a limit is exceeded for an interpreter, first any handler callbacks defined by master interpreters are called. If those callbacks increase or remove the limit, execution within the (previously) limited interpreter continues. If the limit is still in force, an error is generated at that point and normal processing of errors within the interpreter (by the **[catch](catch.htm)** command) is disabled, so the error propagates outwards (building a stack-trace as it goes) to the point where the limited interpreter was invoked (e.g. by **interp eval**) where it becomes the responsibility of the calling code to catch and handle. 


### Limit options

 Every limit has a number of options associated with it, some of which are common across all kinds of limits, and others of which are particular to the kind of limit. 
 **-command**
 This option (common for all limit types) specifies (if non-empty) a Tcl script to be executed in the global namespace of the interpreter reading and writing the option when the particular limit in the limited interpreter is exceeded. The callback may modify the limit on the interpreter if it wishes the limited interpreter to continue executing. If the callback generates an exception, it is reported through the background exception mechanism (see **[BACKGROUND EXCEPTION HANDLING](#M54)**). Note that the callbacks defined by one interpreter are completely isolated from the callbacks defined by another, and that the order in which those callbacks are called is undefined. 

**-granularity**
 This option (common for all limit types) specifies how frequently (out of the points when the Tcl interpreter is in a consistent state where limit checking is possible) that the limit is actually checked. This allows the tuning of how frequently a limit is checked, and hence how often the limit-checking overhead (which may be substantial in the case of time limits) is incurred. 

**-milliseconds**
 This option specifies the number of milliseconds after the moment defined in the **-seconds** option that the time limit will fire. It should only ever be specified in conjunction with the **-seconds** option (whether it was set previously or is being set this invocation.) 

**-seconds**
 This option specifies the number of seconds after the epoch (see **clock seconds**) that the time limit for the interpreter will be triggered. The limit will be triggered at the start of the second unless specified at a sub-second level using the **-milliseconds** option. This option may be the empty string, which indicates that a time limit is not set for the interpreter. 

**-value**
 This option specifies the number of commands that the interpreter may execute before triggering the command limit. This option may be the empty string, which indicates that a command limit is not set for the interpreter. 

  Where an interpreter with a resource limit set on it creates a slave interpreter, that slave interpreter will have resource limits imposed on it that are at least as restrictive as the limits on the creating master interpreter. If the master interpreter of the limited master wishes to relax these conditions, it should hide the **interp** command in the child and then use aliases and the **interp invokehidden** subcommand to provide such access as it chooses to the **interp** command to the limited master as necessary. 


Background exception handling
-----------------------------

 When an exception happens in a situation where it cannot be reported directly up the stack (e.g. when processing events in an **[update](update.htm)** or **[vwait](vwait.htm)** call) the exception is instead reported through the background exception handling mechanism. Every interpreter has a background exception handler registered; the default exception handler arranges for the **[bgerror](bgerror.htm)** command in the interpreter's global namespace to be called, but other exception handlers may be installed and process background exceptions in substantially different ways.  A background exception handler consists of a non-empty list of words to which will be appended two further words at invocation time. The first word will be the interpreter result at time of the exception, typically an error message, and the second will be the dictionary of return options at the time of the exception. These are the same values that **[catch](catch.htm)** can capture when it controls script evaluation in a non-background situation. The resulting list will then be executed in the interpreter's global namespace without further substitutions being performed. 


Credits
-------

 The safe interpreter mechanism is based on the Safe-Tcl prototype implemented by Nathaniel Borenstein and Marshall Rose. Examples
--------

 Creating and using an alias for a command in the current interpreter: 

```
**interp alias** {} getIndex {} lsearch {alpha beta gamma delta}
set idx [getIndex delta]
```
  Executing an arbitrary command in a safe interpreter where every invocation of **[lappend](lappend.htm)** is logged: 



```
set i [**interp create** -safe]
**interp hide** $i lappend
**interp alias** $i lappend {} loggedLappend $i
proc loggedLappend {i args} {
    puts "logged invocation of lappend $args"
    **interp invokehidden** $i lappend {*}$args
}
**interp eval** $i $someUntrustedScript
```
  Setting a resource limit on an interpreter so that an infinite loop terminates. 



```
set i [**interp create**]
**interp limit** $i command -value 1000
**interp eval** $i {
    set x 0
    while {1} {
        puts "Counting up... [incr x]"
    }
}
```
 See also
--------

 **[bgerror](bgerror.htm)**, **[load](load.htm)**, **[safe](safe.htm)**, **[Tcl\_CreateSlave](https://www.tcl.tk/man/tcl/TclLib/CrtSlave.htm)**, **[Tcl\_Eval](https://www.tcl.tk/man/tcl/TclLib/Eval.htm)**, **[Tcl\_BackgroundException](https://www.tcl.tk/man/tcl/TclLib/BackgdErr.htm)** Copyright © 1995-1996 Sun Microsystems, Inc.  
 Copyright © 2004 Donal K. Fellows  
 Copyright © 2006-2008 Joe Mistachkin. 



 Licensed under [Tcl/Tk terms](http://tcl.tk/software/tcltk/license.html)  

<https://www.tcl.tk/man/tcl/TclCmd/interp.htm>

tcl\_tk