═══ 1. Tcl Applications ═══ ═══ 1.1. tclsh ═══ NAME tclsh - Simple shell containing Tcl interpreter SYNOPSIS tclsh ?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 command is invoked or until it reaches end-of-file on its standard input. If there exists a file .tclshrc in the home directory of the user, 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 argument is the name of a script file and 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. There is no automatic evaluation of .tclshrc in this case, but the script file can always source 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's installed somewhere else then you'll 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" "$@" This approach has three advantages over the approach in the previous paragraph. First, the location of the tclsh binary doesn't 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 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 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. VARIABLES Tclsh sets the following Tcl variables: 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 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 isn't yet complete; if tcl_prompt2 isn't set then no prompt is output for incomplete commands. KEYWORDS argument, interpreter, prompt, script file, shell ═══ 2. Tcl Library Procedures ═══ ═══ 2.1. Tcl_AddErrorInfo ═══ NAME Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError - record information about errors SYNOPSIS #include Tcl_AddErrorInfo(interp, message) Tcl_SetErrorCode(interp, element, element, ... (char *) NULL) char * Tcl_PosixError(interp) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to record information. char *message (in) Identifying string to record in errorInfo variable. char *element (in) String to record as one element of errorCode variable. Last element argument must be NULL. DESCRIPTION These procedures are used to manipulate two Tcl global variables that hold information about errors. The variable errorInfo holds a stack trace of the operations that were in progress when an error occurred, and is intended to be human-readable. The variable errorCode holds a list of items that are intended to be machine-readable. The first item in errorCode identifies the class of error that occurred (e.g. POSIX means an error occurred in a POSIX system call) and additional elements in errorCode hold additional pieces of information that depend on the class. See the Tcl overview manual entry for details on the various formats for errorCode. The errorInfo variable is gradually built up as an error unwinds through the nested operations. Each time an error code is returned to Tcl_Eval it calls the procedure Tcl_AddErrorInfo to add additional text to errorInfo describing the command that was being executed when the error occurred. By the time the error has been passed all the way back to the application, it will contain a complete trace of the activity in progress when the error occurred. It is sometimes useful to add additional information to errorInfo beyond what can be supplied automatically by Tcl_Eval. Tcl_AddErrorInfo may be used for this purpose: its message argument contains an additional string to be appended to errorInfo. For example, the source command calls Tcl_AddErrorInfo to record the name of the file being processed and the line number on which the error occurred; for Tcl procedures, the procedure name and line number within the procedure are recorded, and so on. The best time to call Tcl_AddErrorInfo is just after Tcl_Eval has returned TCL_ERROR. In calling Tcl_AddErrorInfo, you may find it useful to use the errorLine field of the interpreter (see the Tcl_Interp manual entry for details). The procedure Tcl_SetErrorCode is used to set the errorCode variable. Its element arguments give one or more strings to record in errorCode: each element will become one item of a properly-formed Tcl list stored in errorCode. Tcl_SetErrorCode is typically invoked just before returning an error. If an error is returned without calling Tcl_SetErrorCode then the Tcl interpreter automatically sets errorCode to NONE. Tcl_PosixError sets the errorCode variable after an error in a POSIX kernel call. It reads the value of the errno C variable and calls Tcl_SetErrorCode to set errorCode in the POSIX format. The caller must previously have called Tcl_SetErrno to set errno; this is necessary on some platforms (e.g. Windows) where Tcl is linked into an application as a shared library, or when the error occurs in a dynamically loaded extension. See the manual entry for Tcl_SetErrno for more information. Tcl_PosixError returns a human-readable diagnostic message for the error (this is the same value that will appear as the third element in errorCode). It may be convenient to include this string as part of the error message returned to the application in interp->result. It is important to call the procedures described here rather than setting errorInfo or errorCode directly with Tcl_SetVar. The reason for this is that the Tcl interpreter keeps information about whether these procedures have been called. For example, the first time Tcl_AppendResult is called for an error, it clears the existing value of errorInfo and adds the error message in interp->result to the variable before appending message; in subsequent calls, it just appends the new message. When Tcl_SetErrorCode is called, it sets a flag indicating that errorCode has been set; this allows the Tcl interpreter to set errorCode to NONE if it receives an error return when Tcl_SetErrorCode hasn't been called. If the procedure Tcl_ResetResult is called, it clears all of the state associated with errorInfo and errorCode (but it doesn't actually modify the variables). If an error had occurred, this will clear the error state to make it appear as if no error had occurred after all. SEE ALSO Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno KEYWORDS error, stack, trace, variable ═══ 2.2. Tcl_Alloc ═══ NAME Tcl_Alloc, Tcl_Free, Tcl_Realloc - allocate or free heap memory SYNOPSIS #include char * Tcl_Alloc(size) Tcl_Free(ptr) char * Tcl_Realloc(ptr, size) ARGUMENTS int size (in) Size in bytes of the memory block to allocate. char *ptr (in) Pointer to memory block to free or realloc. DESCRIPTION These procedures provide a platform and compiler independent interface for memory allocation. Programs that need to transfer ownership of memory blocks between Tcl and other modules should use these routines rather than the native malloc() and free() routines provided by the C run-time library. Tcl_Alloc returns a pointer to a block of at least size bytes suitably aligned for any use. Tcl_Free makes the space referred to by ptr available for further allocation. Tcl_Realloc changes the size of the block pointed to by ptr to size bytes and returns a pointer to the new block. The contents will be unchanged up to the lesser of the new and old sizes. The returned location may be different from ptr. KEYWORDS alloc, allocation, free, malloc, memory, realloc ═══ 2.3. Tcl_AllowExceptions ═══ NAME Tcl_AllowExceptions - allow all exceptions in next script evaluation SYNOPSIS #include Tcl_AllowExceptions(interp) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which script will be evaluated. DESCRIPTION If a script is evaluated at top-level (i.e. no other scripts are pending evaluation when the script is invoked), and if the script terminates with a completion code other than TCL_OK, TCL_CONTINUE or TCL_RETURN, then Tcl normally converts this into a TCL_ERROR return with an appropriate message. However, if Tcl_AllowExceptions is invoked immediately before calling a procedure such as Tcl_Eval, then arbitrary completion codes are permitted from the script, and they are returned without modification. This is useful in cases where the caller can deal with exceptions such as TCL_BREAK or TCL_CONTINUE in a meaningful way. KEYWORDS continue, break, exception, interpreter ═══ 2.4. Tcl_AppInit ═══ NAME Tcl_AppInit - perform application-specific initialization SYNOPSIS #include int Tcl_AppInit(interp) ARGUMENTS Tcl_Interp *interp (in) Interpreter for the application. DESCRIPTION Tcl_AppInit is a "hook" procedure that is invoked by the main programs for Tcl applications such as tclsh and wish. Its purpose is to allow new Tcl applications to be created without modifying the main programs provided as part of Tcl and Tk. To create a new application you write a new version of Tcl_AppInit to replace the default version provided by Tcl, then link your new Tcl_AppInit with the Tcl library. Tcl_AppInit is invoked after by Tcl_Main and Tk_Main after their own initialization and before entering the main loop to process commands. Here are some examples of things that Tcl_AppInit might do: 1. Call initialization procedures for various packages used by the application. Each initialization procedure adds new commands to interp for its package and performs other package-specific initialization. 2. Process command-line arguments, which can be accessed from the Tcl variables argv and argv0 in interp. 3. Invoke a startup script to initialize the application. Tcl_AppInit returns TCL_OK or TCL_ERROR. If it returns TCL_ERROR then it must leave an error message in interp->result; otherwise the result is ignored. In addition to Tcl_AppInit, your application should also contain a procedure main that calls Tcl_Main as follows: Tcl_Main(argc, argv, Tcl_AppInit); The third argument to Tcl_Main gives the address of the application-specific initialization procedure to invoke. This means that you don't have to use the name Tcl_AppInit for the procedure, but in practice the name is nearly always Tcl_AppInit (in versions before Tcl 7.4 the name Tcl_AppInit was implicit; there was no way to specify the procedure explicitly). The best way to get started is to make a copy of the file tclAppInit.c from the Tcl library or source directory. It already contains a main procedure and a template for Tcl_AppInit that you can modify for your application. KEYWORDS application, argument, command, initialization, interpreter ═══ 2.5. Tcl_SetAssocData ═══ NAME Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData - manage associations of string keys and user specified data with Tcl interpreters. SYNOPSIS #include ClientData Tcl_GetAssocData(interp, key, delProcPtr) Tcl_SetAssocData(interp, key, delProc, clientData) Tcl_DeleteAssocData(interp, key) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to execute the specified command. char *key (in) Key for association with which to store data or from which to delete or retrieve data. Typically the module prefix for a package. Tcl_InterpDeleteProc *delProc (in) Procedure to call when interp is deleted. Tcl_InterpDeleteProc **delProcPtr (in) Pointer to location in which to store address of current deletion procedure for association. Ignored if NULL. ClientData clientData (in) Arbitrary one-word value associated with the given key in this interpreter. This data is owned by the caller. DESCRIPTION These procedures allow extensions to associate their own data with a Tcl interpreter. An association consists of a string key, typically the name of the extension, and a one-word value, which is typically a pointer to a data structure holding data specific to the extension. Tcl makes no interpretation of either the key or the value for an association. Storage management is facilitated by storing with each association a procedure to call when the interpreter is deleted. This procedure can dispose of the storage occupied by the client's data in any way it sees fit. Tcl_SetAssocData creates an association between a string key and a user specified datum in the given interpreter. If there is already an association with the given key, Tcl_SetAssocData overwrites it with the new information. It is up to callers to organize their use of names to avoid conflicts, for example, by using package names as the keys. If the deleteProc argument is non-NULL it specifies the address of a procedure to invoke if the interpreter is deleted before the association is deleted. DeleteProc should have arguments and result that match the type Tcl_InterpDeleteProc: typedef void Tcl_InterpDeleteProc( ClientData clientData, Tcl_Interp *interp); When deleteProc is invoked the clientData and interp arguments will be the same as the corresponding arguments passed to Tcl_SetAssocData. The deletion procedure will not be invoked if the association is deleted before the interpreter is deleted. Tcl_GetAssocData returns the datum stored in the association with the specified key in the given interpreter, and if the delProcPtr field is non-NULL, the address indicated by it gets the address of the delete procedure stored with this association. If no association with the specified key exists in the given interpreter Tcl_GetAssocData returns NULL. Tcl_DeleteAssocData deletes an association with a specified key in the given interpreter. It does not call the deletion procedure. KEYWORDS association, data, deletion procedure, interpreter, key ═══ 2.6. Tcl_AsyncCreate ═══ NAME Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete - handle asynchronous events SYNOPSIS #include Tcl_AsyncHandler Tcl_AsyncCreate(proc, clientData) Tcl_AsyncMark(async) int Tcl_AsyncInvoke(interp, code) Tcl_AsyncDelete(async) int Tcl_AsyncReady() ARGUMENTS Tcl_AsyncProc *proc (in) Procedure to invoke to handle an asynchronous event. ClientData clientData (in) One-word value to pass to proc. Tcl_AsyncHandler async (in) Token for asynchronous event handler. Tcl_Interp *interp (in) Tcl interpreter in which command was being evaluated when handler was invoked, or NULL if handler was invoked when there was no interpreter active. int code (in) Completion code from command that just completed in interp, or 0 if interp is NULL. DESCRIPTION These procedures provide a safe mechanism for dealing with asynchronous events such as signals. If an event such as a signal occurs while a Tcl script is being evaluated then it isn't safe to take any substantive action to process the event. For example, it isn't safe to evaluate a Tcl script since the interpreter may already be in the middle of evaluating a script; it may not even be safe to allocate memory, since a memory allocation could have been in progress when the event occurred. The only safe approach is to set a flag indicating that the event occurred, then handle the event later when the world has returned to a clean state, such as after the current Tcl command completes. Tcl_AsyncCreate creates an asynchronous handler and returns a token for it. The asynchronous handler must be created before any occurrences of the asynchronous event that it is intended to handle (it is not safe to create a handler at the time of an event). When an asynchronous event occurs the code that detects the event (such as a signal handler) should call Tcl_AsyncMark with the token for the handler. Tcl_AsyncMark will mark the handler as ready to execute, but it will not invoke the handler immediately. Tcl will call the proc associated with the handler later, when the world is in a safe state, and proc can then carry out the actions associated with the asynchronous event. Proc should have arguments and result that match the type Tcl_AsyncProc: typedef int Tcl_AsyncProc( ClientData clientData, Tcl_Interp *interp, int code); The clientData will be the same as the clientData argument passed to Tcl_AsyncCreate when the handler was created. If proc is invoked just after a command has completed execution in an interpreter, then interp will identify the interpreter in which the command was evaluated and code will be the completion code returned by that command. The command's result will be present in interp->result. When proc returns, whatever it leaves in interp->result will be returned as the result of the command and the integer value returned by proc will be used as the new completion code for the command. It is also possible for proc to be invoked when no interpreter is active. This can happen, for example, if an asynchronous event occurs while the application is waiting for interactive input or an X event. In this case interp will be NULL and code will be 0, and the return value from proc will be ignored. The procedure Tcl_AsyncInvoke is called to invoke all of the handlers that are ready. The procedure Tcl_AsyncReady will return non-zero whenever any asynchronous handlers are ready; it can be checked to avoid calls to Tcl_AsyncInvoke when there are no ready handlers. Tcl calls Tcl_AsyncReady after each command is evaluated and calls Tcl_AsyncInvoke if needed. Applications may also call Tcl_AsyncInvoke at interesting times for that application. For example, Tcl's event handler calls Tcl_AsyncReady after each event and calls Tcl_AsyncInvoke if needed. The interp and code arguments to Tcl_AsyncInvoke have the same meaning as for proc: they identify the active interpreter, if any, and the completion code from the command that just completed. Tcl_AsyncDelete removes an asynchronous handler so that its proc will never be invoked again. A handler can be deleted even when ready, and it will still not be invoked. If multiple handlers become active at the same time, the handlers are invoked in the order they were created (oldest handler first). The code and interp->result for later handlers reflect the values returned by earlier handlers, so that the most recently created handler has last say about the interpreter's result and completion code. If new handlers become ready while handlers are executing, Tcl_AsyncInvoke will invoke them all; at each point it invokes the highest-priority (oldest) ready handler, repeating this over and over until there are no longer any ready handlers. WARNING It is almost always a bad idea for an asynchronous event handler to modify interp->result or return a code different from its code argument. This sort of behavior can disrupt the execution of scripts in subtle ways and result in bugs that are extremely difficult to track down. If an asynchronous event handler needs to evaluate Tcl scripts then it should first save interp->result plus the values of the variables errorInfo and errorCode (this can be done, for example, by storing them in dynamic strings). When the asynchronous handler is finished it should restore interp->result, errorInfo, and errorCode, and return the code argument. KEYWORDS asynchronous event, handler, signal ═══ 2.7. Tcl_BackgroundError ═══ NAME Tcl_BackgroundError - report Tcl error that occurred in background processing SYNOPSIS #include Tcl_BackgroundError(interp) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which the error occurred. DESCRIPTION This procedure is typically invoked when a Tcl error occurs during "background processing" such as executing an event handler. When such an error occurs, the error condition is reported to Tcl or to a widget or some other C code, and there is not usually any obvious way for that code to report the error to the user. In these cases the code calls Tcl_BackgroundError with an interp argument identifying the interpreter in which the error occurred. At the time Tcl_BackgroundError is invoked, interp->result is expected to contain an error message. Tcl_BackgroundError will invoke the bgerror Tcl command to report the error in an application-specific fashion. If no bgerror command exists, or if it returns with an error condition, then Tcl_BackgroundError reports the error itself by printing a message on the standard error file. Tcl_BackgroundError does not invoke bgerror immediately because this could potentially interfere with scripts that are in process at the time the error occurred. Instead, it invokes bgerror later as an idle callback. Tcl_BackgroundError saves the values of the errorInfo and errorCode variables and restores these values just before invoking bgerror. It is possible for many background errors to accumulate before bgerror is invoked. When this happens, each of the errors is processed in order. However, if bgerror returns a break exception, then all remaining error reports for the interpreter are skipped. KEYWORDS background, bgerror, error ═══ 2.8. Tcl_Backslash ═══ NAME Tcl_Backslash - parse a backslash sequence SYNOPSIS #include char Tcl_Backslash(src, countPtr) ARGUMENTS char *src (in) Pointer to a string starting with a backslash. int *countPtr (out) If countPtr isn't NULL, *countPtr gets filled in with number of characters in the backslash sequence, including the backslash character. DESCRIPTION This is a utility procedure used by several of the Tcl commands. It parses a backslash sequence and returns the single character corresponding to the sequence. Tcl_Backslash modifies *countPtr to contain the number of characters in the backslash sequence. See the Tcl manual entry for information on the valid backslash sequences. All of the sequences described in the Tcl manual entry are supported by Tcl_Backslash. KEYWORDS backslash, parse ═══ 2.9. Tcl_CallWhenDeleted ═══ NAME Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted - Arrange for callback when interpreter is deleted SYNOPSIS #include Tcl_CallWhenDeleted(interp, proc, clientData) Tcl_DontCallWhenDeleted(interp, proc, clientData) ARGUMENTS Tcl_Interp *interp (in) Interpreter with which to associated callback. Tcl_InterpDeleteProc *proc (in) Procedure to call when interp is deleted. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION Tcl_CallWhenDeleted arranges for proc to be called by Tcl_DeleteInterp if/when interp is deleted at some future time. Proc will be invoked just before the interpreter is deleted, but the interpreter will still be valid at the time of the call. Proc should have arguments and result that match the type Tcl_InterpDeleteProc: typedef void Tcl_InterpDeleteProc( ClientData clientData, Tcl_Interp *interp); The clientData and interp parameters are copies of the clientData and interp arguments given to Tcl_CallWhenDeleted. Typically, clientData points to an application-specific data structure that proc uses to perform cleanup when an interpreter is about to go away. Proc does not return a value. Tcl_DontCallWhenDeleted cancels a previous call to Tcl_CallWhenDeleted with the same arguments, so that proc won't be called after all when interp is deleted. If there is no deletion callback that matches interp, proc, and clientData then the call to Tcl_DontCallWhenDeleted has no effect. KEYWORDS callback, delete, interpreter ═══ 2.10. Tcl_CommandComplete ═══ NAME Tcl_CommandComplete - Check for unmatched braces in a Tcl command SYNOPSIS #include int Tcl_CommandComplete(cmd) ARGUMENTS char *cmd (in) Command string to test for completeness. DESCRIPTION Tcl_CommandComplete takes a Tcl command string as argument and determines whether it contains one or more complete commands (i.e. there are no unclosed quotes, braces, brackets, or variable references). If the command string is complete then it returns 1; otherwise it returns 0. KEYWORDS complete command, partial command ═══ 2.11. Tcl_Concat ═══ NAME Tcl_Concat - concatenate a collection of strings SYNOPSIS #include char * Tcl_Concat(argc, argv) ARGUMENTS int argc (in) Number of strings. char *argv[] (in) Array of strings to concatenate. Must have argc entries. DESCRIPTION Tcl_Concat is a utility procedure used by several of the Tcl commands. Given a collection of strings, it concatenates them together into a single string, with the original strings separated by spaces. This procedure behaves differently than Tcl_Merge, in that the arguments are simply concatenated: no effort is made to ensure proper list structure. However, in most common usage the arguments will all be proper lists themselves; if this is true, then the result will also have proper list structure. Tcl_Concat eliminates leading and trailing white space as it copies strings from argv to the result. If an element of argv consists of nothing but white space, then that string is ignored entirely. This white-space removal was added to make the output of the concat command cleaner-looking. The result string is dynamically allocated using Tcl_Alloc; the caller must eventually release the space by calling Tcl_Free. KEYWORDS concatenate, strings ═══ 2.12. Tcl_CreateChannel ═══ NAME Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelFile, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetDefaultTranslation, Tcl_SetChannelBufferSize - procedures for creating and manipulating channels SYNOPSIS #include Tcl_Channel Tcl_CreateChannel(typePtr, channelName, instanceData, mask) ClientData Tcl_GetChannelInstanceData(channel) Tcl_ChannelType * Tcl_GetChannelType(channel) char * Tcl_GetChannelName(channel) Tcl_File Tcl_GetChannelFile(channel, direction) int Tcl_GetChannelFlags(channel) void Tcl_SetDefaultTranslation(channel, transMode) int Tcl_GetChannelBufferSize(channel) void Tcl_SetChannelBufferSize(channel, size) ARGUMENTS Tcl_ChannelType *typePtr (in) Points to a structure containing the addresses of procedures that can be called to perform I/O and other functions on the channel. char *channelName (in) The name of this channel, such as file3; must not be in use by any other channel. Can be NULL, in which case the channel is created without a name. ClientData instanceData (in) Arbitrary one-word value to be associated with this channel. This value is passed to procedures in typePtr when they are invoked. int mask (in) OR-ed combination of TCL_READABLE and TCL_WRITABLE to indicate whether a channel is readable and writable. Tcl_Channel channel (in) The channel to operate on. int direction (in) TCL_READABLE means the input file is wanted; TCL_WRITABLE means the output file is wanted. Tcl_EolTranslation transMode (in) The translation mode; one of the constants TCL_TRANSLATE_AUTO, TCL_TRANSLATE_CR, TCL_TRANSLATE_LF and TCL_TRANSLATE_CRLF. int size (in) The size, in bytes, of buffers to allocate in this channel. DESCRIPTION Tcl uses a two-layered channel architecture. It provides a generic upper layer to enable C and Tcl programs to perform input and output using the same APIs for a variety of files, devices, sockets etc. The generic C APIs are described in the manual entry for Tcl_OpenFileChannel. The lower layer provides type-specific channel drivers for each type of file, socket and device supported on each platform. This manual entry describes the C APIs used by the generic layer to communicate with type-specific channel drivers to perform the input and output operations. It also explains how new types of channels can be added by providing new channel drivers. Channel drivers consist of a number of components: First, each channel driver provides a Tcl_ChannelType structure containing pointers to functions implementing the various operations used by the generic layer to communicate with the channel driver. The Tcl_ChannelType structure and the functions referenced by it are described in the section TCL_CHANNELTYPE, below. Second, channel drivers usually provide a Tcl command to create instances of that type of channel. For example, the Tcl open command creates channels that use the file and command channel drivers, and the Tcl socket command creates channels that use TCP sockets for network communication. Third, a channel driver optionally provides a C function to open channel instances of that type. For example, Tcl_OpenFileChannel opens a channel that uses the file channel driver, and Tcl_OpenTcpClient opens a channel that uses the TCP network protocol. These creation functions typically use Tcl_CreateChannel internally to open the channel. To add a new type of channel you must implement a C API or a Tcl command that opens a channel by invoking Tcl_CreateChannel. When your driver calls Tcl_CreateChannel it passes in a Tcl_ChannelType structure describing the driver's I/O procedures. The generic layer will then invoke the functions referenced in that structure to perform operations on the channel. Tcl_CreateChannel opens a new channel and associates the supplied typePtr and instanceData with it. The channel is opened in the mode indicated by mask. For a discussion of channel drivers, their operations and the Tcl_ChannelType structure, see the section TCL_CHANNELTYPE, below. Tcl_GetChannelInstanceData returns the instance data associated with the channel in channel. This is the same as the instanceData argument in the call to Tcl_CreateChannel that created this channel. Tcl_GetChannelType returns a pointer to the Tcl_ChannelType structure used by the channel in the channel argument. This is the same as the typePtr argument in the call to Tcl_CreateChannel that created this channel. Tcl_GetChannelName returns a string containing the name associated with the channel, or NULL if the channelName argument to Tcl_CreateChannel was NULL. Tcl_GetChannelFile returns the inFile associated with channel if direction is TCL_READABLE, or the outFile if direction is TCL_WRITABLE. The operation returns NULL if the channel is not based on Tcl_Files or if the channel is not open for the specified direction. Tcl_GetChannelMode returns an OR-ed combination of TCL_READABLE and TCL_WRITABLE, indicating whether the channel is open for input and output. Tcl_SetDefaultTranslation sets the default end of line translation mode. This mode will be installed as the translation mode for the channel if an attempt is made to output on the channel while it is still in TCL_TRANSLATE_AUTO mode. For a description of end of line translation modes, see the manual entry for fconfigure. Tcl_GetChannelBufferSize returns the size, in bytes, of buffers allocated to store input or output in chan. If the value was not set by a previous call to Tcl_SetChannelBufferSize, described below, then the default value of 4096 is returned. Tcl_SetChannelBufferSize sets the size, in bytes, of buffers that will be allocated in subsequent operations on the channel to store input or output. The size argument should be between ten and one million, allowing buffers of ten bytes to one million bytes. If size is outside this range, Tcl_SetChannelBufferSize sets the buffer size to 4096. TCL_CHANNELTYPE A channel driver provides a Tcl_ChannelType structure that contains pointers to functions that implement the various operations on a channel; these operations are invoked as needed by the generic layer. The Tcl_ChannelType structure contains the following fields: typedef struct Tcl_ChannelType { char *typeName; Tcl_DriverBlockModeProc *blockModeProc; Tcl_DriverCloseProc *closeProc; Tcl_DriverInputProc *inputProc; Tcl_DriverOutputProc *outputProc; Tcl_DriverSeekProc *seekProc; Tcl_DriverSetOptionProc *setOptionProc; Tcl_DriverGetOptionProc *getOptionProc; Tcl_DriverWatchChannelProc *watchChannelProc; Tcl_DriverChannelReadyProc *channelReadyProc; Tcl_DriverGetFileProc *getFileProc; } Tcl_ChannelType; The driver must provide implementations for all functions except blockModeProc, seekProc, setOptionProc, and getOptionProc, which may be specified as NULL to indicate that the channel does not support seeking. Other functions that can not be implemented for this type of device should return EINVAL when invoked to indicate that they are not implemented. TYPENAME The typeName field contains a null-terminated string that identifies the type of the device implemented by this driver, e.g. file or socket. BLOCKMODEPROC The blockModeProc field contains the address of a function called by the generic layer to set blocking and nonblocking mode on the device. BlockModeProc should match the following prototype: typedef int Tcl_DriverBlockModeProc( ClientData instanceData, int mode); The instanceData is the same as the value passed to Tcl_CreateChannel when this channel was created. The mode argument is either TCL_MODE_BLOCKING or TCL_MODE_NONBLOCKING to set the device into blocking or nonblocking mode. The function should return zero if the operation was successful, or a nonzero POSIX error code if the operation failed. If the operation is successful, the function can modify the supplied instanceData to record that the channel entered blocking or nonblocking mode and to implement the blocking or nonblocking behavior. For some device types, the blocking and nonblocking behavior can be implemented by the underlying operating system; for other device types, the behavior must be emulated in the channel driver. CLOSEPROC The closeProc field contains the address of a function called by the generic layer to clean up driver-related information when the channel is closed. CloseProc must match the following prototype: typedef int Tcl_DriverCloseProc( ClientData instanceData, Tcl_Interp *interp); The instanceData argument is the same as the value provided to Tcl_CreateChannel when the channel was created. The function should release any storage maintained by the channel driver for this channel, and close the input and output devices encapsulated by this channel. All queued output will have been flushed to the device before this function is called, and no further driver operations will be invoked on this instance after calling the closeProc. If the close operation is successful, the procedure should return zero; otherwise it should return a nonzero POSIX error code. In addition, if an error occurs and interp is not NULL, the procedure should store an error message in interp->result. INPUTPROC The inputProc field contains the address of a function called by the generic layer to read data from the file or device and store it in an internal buffer. InputProc must match the following prototype: typedef int Tcl_DriverInputProc( ClientData instanceData, char *buf, int bufSize, int *errorCodePtr); InstanceData is the same as the value passed to Tcl_CreateChannel when the channel was created. The buf argument points to an array of bytes in which to store input from the device, and the bufSize argument indicates how many bytes are available at buf. The errorCodePtr argument points to an integer variable provided by the generic layer. If an error occurs, the function should set the variable to a POSIX error code that identifies the error that occurred. The function should read data from the input device encapsulated by the channel and store it at buf. On success, the function should return a nonnegative integer indicating how many bytes were read from the input device and stored at buf. On error, the function should return -1. If an error occurs after some data has been read from the device, that data is lost. If inputProc can determine that the input device has some data available but less than requested by the bufSize argument, the function should only attempt to read as much data as is available and return without blocking. If the input device has no data available whatsoever and the channel is in nonblocking mode, the function should return an EAGAIN error. If the input device has no data available whatsoever and the channel is in blocking mode, the function should block for the shortest possible time until at least one byte of data can be read from the device; then, it should return as much data as it can read without blocking. OUTPUTPROC The outputProc field contains the address of a function called by the generic layer to transfer data from an internal buffer to the output device. OutputProc must match the following prototype: typedef int Tcl_DriverOutputProc( ClientData instanceData, char *buf, int toWrite, int *errorCodePtr); InstanceData is the same as the value passed to Tcl_CreateChannel when the channel was created. The buf argument contains an array of bytes to be written to the device, and the toWrite argument indicates how many bytes are to be written from the buf argument. The errorCodePtr argument points to an integer variable provided by the generic layer. If an error occurs, the function should set this variable to a POSIX error code that identifies the error. The function should write the data at buf to the output device encapsulated by the channel. On success, the function should return a nonnegative integer indicating how many bytes were written to the output device. The return value is normally the same as toWrite, but may be less in some cases such as if the output operation is interrupted by a signal. If an error occurs the function should return -1. In case of error, some data may have been written to the device. If the channel is nonblocking and the output device is unable to absorb any data whatsoever, the function should return -1 with an EAGAIN error without writing any data. SEEKPROC The seekProc field contains the address of a function called by the generic layer to move the access point at which subsequent input or output operations will be applied. SeekProc must match the following prototype: typedef int Tcl_DriverSeekProc( ClientData instanceData, long offset, int seekMode, int *errorCodePtr); The instanceData argument is the same as the value given to Tcl_CreateChannel when this channel was created. Offset and seekMode have the same meaning as for the Tcl_SeekChannel procedure (described in the manual entry for Tcl_OpenFileChannel). The errorCodePtr argument points to an integer variable provided by the generic layer for returning errno values from the function. The function should set this variable to a POSIX error code if an error occurs. The function should store an EINVAL error code if the channel type does not implement seeking. The return value is the new access point or -1 in case of error. If an error occurred, the function should not move the access point. SETOPTIONPROC The setOptionProc field contains the address of a function called by the generic layer to set a channel type specific option on a channel. setOptionProc must match the following prototype: typedef int Tcl_DriverSetOptionProc( ClientData instanceData, Tcl_Interp *interp, char *optionName, char *optionValue); optionName is the name of an option to set, and optionValue is the new value for that option, as a string. The instanceData is the same as the value given to Tcl_CreateChannel when this channel was created. The function should do whatever channel type specific action is required to implement the new value of the option. Some options are handled by the generic code and this function is never called to set them, e.g. -blockmode. Other options are specific to each channel type and the setOptionProc procedure of the channel driver will get called to implement them. The setOptionProc field can be NULL, which indicates that this channel type supports no type specific options. If the option value is successfully modified to the new value, the function returns TCL_OK. It returns TCL_ERROR if the optionName is unrecognized or if optionValue specifies a value for the option that is not supported. In this case, the function leaves an error message in the result field of interp if interp is not NULL. The function should also call Tcl_SetErrno to store an appropriate POSIX error code. GETOPTIONPROC The getOptionProc field contains the address of a function called by the generic layer to get the value of a channel type specific option on a channel. getOptionProc must match the following prototype: typedef int Tcl_DriverGetOptionProc( ClientData instanceData, char *optionName, Tcl_DString *dsPtr); OptionName is the name of an option supported by this type of channel. If the option name is not NULL, the function stores its current value, as a string, in the Tcl dynamic string dsPtr. If optionName is NULL, the function stores in dsPtr an alternating list of all supported options and their current values. On success, the function returns TCL_OK. If an error occurs, the function returns TCL_ERROR and calls Tcl_SetErrno to store an appropriate POSIX error code. Some options are handled by the generic code and this function is never called to retrieve their value, e.g. -blockmode. Other options are specific to each channel type and the getOptionProc procedure of the channel driver will get called to implement them. The getOptionProc field can be NULL, which indicates that this channel type supports no type specific options. WATCHCHANNELPROC The watchChannelProc field contains the address of a function called by the generic layer to initialize the event notification mechanism to notice events of interest on this channel. WatchChannelProc should match the following prototype: typeded void Tcl_DriverWatchChannelProc( ClientData instanceData, int mask); The instanceData is the same as the value passed to Tcl_CreateChannel when this channel was created. The mask argument is an OR-ed combination of TCL_READABLE, TCL_WRITABLE and TCL_EXCEPTION; it indicates events the caller is interested in noticing on this channel. The function should initialize device type specific mechanisms to notice when an event of interest is present on the channel. It may invoke Tcl_SetMaxBlockTime to specify an upper limit on the length of time to wait for an event, and it may invoke Tcl_WatchFile if the channel implementation is based on Tcl_Files. CHANNELREADYPROC The channelReadyProc field contains the address of a function called by the generic layer to sense whether events of interest have occurred for this channel. ChannelReadyProc should match the following prototype: typedef int Tcl_DriverChannelReadyProc( ClientData instanceData, int mask); InstanceData is the same as the value passed to Tcl_CreateChannel when this channel was created. The mask argument is an OR-ed combination of TCL_READABLE, TCL_WRITABLE and TCL_EXCEPTION indicating what events are of interest. The function returns a mask containing an OR-ed combination of a subset of the flags in mask to indicate what events have actually occurred on the channel. The function should use a device type dependent mechanism to detect whether events of interest have occurred on the channel. It may invoke Tcl_FileReady if the channel implementation is based on Tcl_Files. GETFILEPROC The getFileProc field contains the address of a function called by the generic layer to retrieve a Tcl_File from the channel. GetFileProc should match the following prototype: typedef Tcl_File Tcl_DriverGetFileProc( ClientData instanceData, int direction); InstanceData is the same as the value passed to Tcl_CreateChannel when this channel was created. The direction argument is either TCL_READABLE to retrieve the Tcl_File used for input, or TCL_WRITABLE to retrieve the Tcl_File used for output. If the channel implementation is based on Tcl_Files, the function should retrieve the appropriate Tcl_File associated with the channel, according the direction argument; it can return NULL if the channel is not open for that direction. If the channel implementation does not use Tcl_Files, the function should always return NULL. SEE ALSO Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_SetMaxBlockTime(3), Tcl_WatchFile(3), Tcl_FileReady(3) KEYWORDS blocking, channel driver, channel registration, channel type, nonblocking ═══ 2.13. Tcl_CreateChannelHandler ═══ NAME Tcl_CreateChannelHandler, Tcl_DeleteChannelHandler - call a procedure when a channel becomes readable or writable SYNOPSIS #include void Tcl_CreateChannelHandler(channel, mask, proc, clientData) void Tcl_DeleteChannelHandler(channel, proc, clientData) ARGUMENTS Tcl_Channel channel (in) Tcl channel such as returned by Tcl_CreateChannel. int mask (in) Conditions under which proc should be called: OR-ed combination of TCL_READABLE, TCL_WRITABLE and TCL_EXCEPTION. Specify a zero value to temporarily disable an existing handler. Tcl_FileProc *proc (in) Procedure to invoke whenever the channel indicated by channel meets the conditions specified by mask. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION Tcl_CreateChannelHandler arranges for proc to be called in the future whenever input or output becomes possible on the channel identified by channel, or whenever an exceptional condition exists for channel. The conditions of interest under which proc will be invoked are specified by the mask argument. See the manual entry for fileevent for a precise description of what it means for a channel to be readable or writable. Proc must conform to the following prototype: typedef void Tcl_ChannelProc( ClientData clientData, int mask); The clientData argument is the same as the value passed to Tcl_CreateChannelHandler when the handler was created. Typically, clientData points to a data structure containing application-specific information about the channel. Mask is an integer mask indicating which of the requested conditions actually exists for the channel; it will contain a subset of the bits from the mask argument to Tcl_CreateChannelHandler when the handler was created. Each channel handler is identified by a unique combination of channel, proc and clientData. There may be many handlers for a given channel as long as they don't have the same channel, proc, and clientData. If Tcl_CreateChannelHandler is invoked when there is already a handler for channel, proc, and clientData, then no new handler is created; instead, the mask is changed for the existing handler. Tcl_DeleteChannelHandler deletes a channel handler identified by channel, proc and clientData; if no such handler exists, the call has no effect. Channel handlers are invoked via the Tcl event mechanism, so they are only useful in applications that are event-driven. Note also that the conditions specified in the mask argument to proc may no longer exist when proc is invoked: for example, if there are two handlers for TCL_READABLE on the same channel, the first handler could consume all of the available input so that the channel is no longer readable when the second handler is invoked. For this reason it may be useful to use nonblocking I/O on channels for which there are event handlers. SEE ALSO Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n). KEYWORDS blocking, callback, channel, events, handler, nonblocking. ═══ 2.14. Tcl_CreateCloseHandler ═══ NAME Tcl_CreateCloseHandler, Tcl_DeleteCloseHandler - arrange for callbacks when channels are closed SYNOPSIS #include void Tcl_CreateCloseHandler(channel, proc, clientData) void Tcl_DeleteCloseHandler(channel, proc, clientData) ARGUMENTS Tcl_Channel channel (in) The channel for which to create or delete a close callback. Tcl_CloseProc *proc (in) The procedure to call as the callback. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION Tcl_CreateCloseHandler arranges for proc to be called when channel is closed with Tcl_Close or Tcl_UnregisterChannel, or using the Tcl close command. Proc should match the following prototype: typedef void Tcl_CloseProc( ClientData clientData); The clientData is the same as the value provided in the call to Tcl_CreateCloseHandler. Tcl_DeleteCloseHandler removes a close callback for channel. The proc and clientData identify which close callback to remove; Tcl_DeleteCloseHandler does nothing if its proc and clientData arguments do not match the proc and clientData for a close handler for channel. SEE ALSO close(n), Tcl_Close(3), Tcl_UnregisterChannel(3) KEYWORDS callback, channel closing ═══ 2.15. Tcl_CreateCommand ═══ NAME Tcl_CreateCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo - implement new commands in C SYNOPSIS #include Tcl_Command Tcl_CreateCommand(interp, cmdName, proc, clientData, deleteProc) int Tcl_DeleteCommand(interp, cmdName) int Tcl_GetCommandInfo(interp, cmdName, infoPtr) int Tcl_SetCommandInfo(interp, cmdName, infoPtr) char * Tcl_GetCommandName(interp, token) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to create new command. char *cmdName (in) Name of command. Tcl_CmdProc *proc (in) Implementation of new command: proc will be called whenever cmdName is invoked as a command. ClientData clientData (in) Arbitrary one-word value to pass to proc and deleteProc. Tcl_CmdDeleteProc *deleteProc (in) Procedure to call before cmdName is deleted from the interpreter; allows for command-specific cleanup. If NULL, then no procedure is called before the command is deleted. Tcl_CmdInfo *infoPtr (in/out) Pointer to structure containing various information about a Tcl command. Tcl_Command token (in) Token for command, returned by previous call to Tcl_CreateCommand. The command must not have been deleted. DESCRIPTION Tcl_CreateCommand defines a new command in interp and associates it with procedure proc such that whenever cmdName is invoked as a Tcl command (via a call to Tcl_Eval) the Tcl interpreter will call proc to process the command. If there is already a command cmdName associated with the interpreter, it is deleted. Tcl_CreateCommand returns a token that may be used to refer to the command in subsequent calls to Tcl_GetCommandName. If Tcl_CreateCommand is called for an interpreter that is in the process of being deleted, then it does not create a new command and it returns NULL. Proc should have arguments and result that match the type Tcl_CmdProc: typedef int Tcl_CmdProc( ClientData clientData, Tcl_Interp *interp, int argc, char *argv[]); When proc is invoked the clientData and interp parameters will be copies of the clientData and interp arguments given to Tcl_CreateCommand. Typically, clientData points to an application-specific data structure that describes what to do when the command procedure is invoked. Argc and argv describe the arguments to the command, argc giving the number of arguments (including the command name) and argv giving the values of the arguments as strings. The argv array will contain argc+1 values; the first argc values point to the argument strings, and the last value is NULL. Proc must return an integer code that is either TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE. See the Tcl overview man page for details on what these codes mean. Most normal commands will only return TCL_OK or TCL_ERROR. In addition, proc must set interp->result to point to a string value; in the case of a TCL_OK return code this gives the result of the command, and in the case of TCL_ERROR it gives an error message. The Tcl_SetResult procedure provides an easy interface for setting the return value; for complete details on how the interp->result field is managed, see the Tcl_Interp man page. Before invoking a command procedure, Tcl_Eval sets interp->result to point to an empty string, so simple commands can return an empty result by doing nothing at all. The contents of the argv array belong to Tcl and are not guaranteed to persist once proc returns: proc should not modify them, nor should it set interp->result to point anywhere within the argv values. Call Tcl_SetResult with status TCL_VOLATILE if you want to return something from the argv array. DeleteProc will be invoked when (if) cmdName is deleted. This can occur through a call to Tcl_DeleteCommand or Tcl_DeleteInterp, or by replacing cmdName in another call to Tcl_CreateCommand. DeleteProc is invoked before the command is deleted, and gives the application an opportunity to release any structures associated with the command. DeleteProc should have arguments and result that match the type Tcl_CmdDeleteProc: typedef void Tcl_CmdDeleteProc(ClientData clientData); The clientData argument will be the same as the clientData argument passed to Tcl_CreateCommand. Tcl_DeleteCommand deletes a command from a command interpreter. Once the call completes, attempts to invoke cmdName in interp will result in errors. If cmdName isn't bound as a command in interp then Tcl_DeleteCommand does nothing and returns -1; otherwise it returns 0. There are no restrictions on cmdName: it may refer to a built-in command, an application-specific command, or a Tcl procedure. Tcl_GetCommandInfo checks to see whether its cmdName argument exists as a command in interp. If not then it returns 0. Otherwise it places information about the command in the structure pointed to by infoPtr and returns 1. Tcl_CmdInfo structures have fields named proc, clientData, and deleteProc, which have the same meaning as the corresponding arguments to Tcl_CreateCommand. There is also a field deleteData, which is the ClientData value to pass to deleteProc; it is normally the same as clientData but may be set independently using the Tcl_SetCommandInfo procedure. Tcl_SetCommandInfo is used to modify the procedures and ClientData values associated with a command. Its cmdName argument is the name of a command in interp. If this command does not exist then Tcl_SetCommandInfo returns 0. Otherwise, it copies the information from *infoPtr to Tcl's internal structure for the command and returns 1. Note that this procedure allows the ClientData for a command's deletion procedure to be given a different value than the ClientData for its command procedure. Tcl_GetCommandName provides a mechanism for tracking commands that have been renamed. Given a token returned by Tcl_CreateCommand when the command was created, Tcl_GetCommandName returns the string name of the command. If the command has been renamed since it was created, then Tcl_GetCommandName returns the current name. The command corresponding to token must not have been deleted. The string returned by Tcl_GetCommandName is in dynamic memory owned by Tcl and is only guaranteed to retain its value as long as the command isn't deleted or renamed; callers should copy the string if they need to keep it for a long time. KEYWORDS bind, command, create, delete, interpreter ═══ 2.16. Tcl_CreateFileHandler ═══ NAME Tcl_CreateFileHandler, Tcl_DeleteFileHandler - associate procedure callbacks with files or devices SYNOPSIS #include Tcl_CreateFileHandler(file, mask, proc, clientData) Tcl_DeleteFileHandler(file) ARGUMENTS Tcl_File file (in) Generic file handle for an open file or device (such as returned by Tcl_GetFile call). int mask (in) Conditions under which proc should be called: OR-ed combination of TCL_READABLE, TCL_WRITABLE, and TCL_EXCEPTION. May be set to 0 to temporarily disable a handler. Tcl_FileProc *proc (in) Procedure to invoke whenever the file or device indicated by file meets the conditions specified by mask. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION Tcl_CreateFileHandler arranges for proc to be invoked in the future whenever I/O becomes possible on a file or an exceptional condition exists for the file. The file is indicated by file, and the conditions of interest are indicated by mask. For example, if mask is TCL_READABLE, proc will be called when the file is readable. The callback to proc is made by Tcl_DoOneEvent, so Tcl_CreateFileHandler is only useful in programs that dispatch events through Tcl_DoOneEvent or through Tcl commands such as vwait. Proc should have arguments and result that match the type Tcl_FileProc: typedef void Tcl_FileProc( ClientData clientData, int mask); The clientData parameter to proc is a copy of the clientData argument given to Tcl_CreateFileHandler when the callback was created. Typically, clientData points to a data structure containing application-specific information about the file. Mask is an integer mask indicating which of the requested conditions actually exists for the file; it will contain a subset of the bits in the mask argument to Tcl_CreateFileHandler. There may exist only one handler for a given file at a given time. If Tcl_CreateFileHandler is called when a handler already exists for file, then the new callback replaces the information that was previously recorded. Tcl_DeleteFileHandler may be called to delete the file handler for file; if no handler exists for the file given by file then the procedure has no effect. The purpose of file handlers is to enable an application to respond to events while waiting for files to become ready for I/O. For this to work correctly, the application may need to use non-blocking I/O operations on the files for which handlers are declared. Otherwise the application may block if it reads or writes too much data; while waiting for the I/O to complete the application won't be able to service other events. Use Tcl_SetChannelOption with -blocking to set the channel into blocking or nonblocking mode as required. KEYWORDS callback, file, handler ═══ 2.17. Tcl_CreateInterp ═══ NAME Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted - create and delete Tcl command interpreters SYNOPSIS #include Tcl_Interp * Tcl_CreateInterp() Tcl_DeleteInterp(interp) int Tcl_InterpDeleted(interp) ARGUMENTS Tcl_Interp *interp (in) Token for interpreter to be destroyed. DESCRIPTION Tcl_CreateInterp creates a new interpreter structure and returns a token for it. The token is required in calls to most other Tcl procedures, such as Tcl_CreateCommand, Tcl_Eval, and Tcl_DeleteInterp. Clients are only allowed to access a few of the fields of Tcl_Interp structures; see the Tcl_Interp and Tcl_CreateCommand man pages for details. The new interpreter is initialized with no defined variables and only the built-in Tcl commands. To bind in additional commands, call Tcl_CreateCommand. Tcl_DeleteInterp marks an interpreter as deleted; the interpreter will eventually be deleted when all calls to Tcl_Preserve for it have been matched by calls to Tcl_Release. At that time, all of the resources associated with it, including variables, procedures, and application-specific command bindings, will be deleted. After Tcl_DeleteInterp returns any attempt to use Tcl_Eval on the interpreter will fail and return TCL_ERROR. After the call to Tcl_DeleteInterp it is safe to examine interp->result, query or set the values of variables, define, undefine or retrieve procedures, and examine the runtime evaluation stack. See below, in the section INTERPRETERS AND MEMORY MANAGEMENT for details. Tcl_InterpDeleted returns nonzero if Tcl_DeleteInterp was called with interp as its argument; this indicates that the interpreter will eventually be deleted, when the last call to Tcl_Preserve for it is matched by a call to Tcl_Release. If nonzero is returned, further calls to Tcl_Eval in this interpreter will return TCL_ERROR. Tcl_InterpDeleted is useful in deletion callbacks to distinguish between when only the memory the callback is responsible for is being deleted and when the whole interpreter is being deleted. In the former case the callback may recreate the data being deleted, but this would lead to an infinite loop if the interpreter were being deleted. INTERPRETERS AND MEMORY MANAGEMENT Tcl_DeleteInterp can be called at any time on an interpreter that may be used by nested evaluations and C code in various extensions. Tcl implements a simple mechanism that allows callers to use interpreters without worrying about the interpreter being deleted in a nested call, and without requiring special code to protect the interpreter, in most cases. This mechanism ensures that nested uses of an interpreter can safely continue using it even after Tcl_DeleteInterp is called. The mechanism relies on matching up calls to Tcl_Preserve with calls to Tcl_Release. If Tcl_DeleteInterp has been called, only when the last call to Tcl_Preserve is matched by a call to Tcl_Release, will the interpreter be freed. See the manual entry for Tcl_Preserve for a description of these functions. The rules for when the user of an interpreter must call Tcl_Preserve and Tcl_Release are simple: Interpreters Passed As Arguments Functions that are passed an interpreter as an argument can safely use the interpreter without any special protection. Thus, when you write an extension consisting of new Tcl commands, no special code is needed to protect interpreters received as arguments. This covers the majority of all uses. Interpreter Creation And Deletion When a new interpreter is created and used in a call to Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_SetVar, or Tcl_GetVar, a pair of calls to Tcl_Preserve and Tcl_Release should be wrapped around all uses of the interpreter. Remember that it is unsafe to use the interpreter once Tcl_Release has been called. To ensure that the interpreter is properly deleted when it is no longer needed, call Tcl_InterpDeleted to test if some other code already called Tcl_DeleteInterp; if not, call Tcl_DeleteInterp before calling Tcl_Release in your own code. Do not call Tcl_DeleteInterp on an interpreter for which Tcl_InterpDeleted returns nonzero. Retrieving An Interpreter From A Data Structure When an interpreter is retrieved from a data structure (e.g. the client data of a callback) for use in Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_SetVar, or Tcl_GetVar, a pair of calls to Tcl_Preserve and Tcl_Release should be wrapped around all uses of the interpreter; it is unsafe to reuse the interpreter once Tcl_Release has been called. If an interpreter is stored inside a callback data structure, an appropriate deletion cleanup mechanism should be set up by the code that creates the data structure so that the interpreter is removed from the data structure (e.g. by setting the field to NULL) when the interpreter is deleted. Otherwise, you may be using an interpreter that has been freed and whose memory may already have been reused. All uses of interpreters in Tcl and Tk have already been protected. Extension writers should ensure that their code also properly protects any additional interpreters used, as described above. KEYWORDS command, create, delete, interpreter SEE ALSO Tcl_Preserve(3), Tcl_Release(3) ═══ 2.18. Tcl_CreateMathFunc ═══ NAME Tcl_CreateMathFunc - Define a new math function for expressions SYNOPSIS #include Tcl_CreateMathFunc(interp, name, numArgs, argTypes, proc, clientData) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which new function will be defined. char *name (in) Name for new function. int numArgs (in) Number of arguments to new function; also gives size of argTypes array. Tcl_ValueType *argTypes (in) Points to an array giving the permissible types for each argument to function. Tcl_MathProc *proc (in) Procedure that implements the function. ClientData clientData (in) Arbitrary one-word value to pass to proc when it is invoked. DESCRIPTION Tcl allows a number of mathematical functions to be used in expressions, such as sin, cos, and hypot. Tcl_CreateMathFunc allows applications to add additional functions to those already provided by Tcl or to replace existing functions. Name is the name of the function as it will appear in expressions. If name doesn't already exist as a function then a new function is created. If it does exist, then the existing function is replaced. NumArgs and argTypes describe the arguments to the function. Each entry in the argTypes array must be either TCL_INT, TCL_DOUBLE, or TCL_EITHER to indicate whether the corresponding argument must be an integer, a double-precision floating value, or either, respectively. Whenever the function is invoked in an expression Tcl will invoke proc. Proc should have arguments and result that match the type Tcl_MathProc: typedef int Tcl_MathProc( ClientData clientData, Tcl_Interp *interp, Tcl_Value *args, Tcl_Value *resultPtr); When proc is invoked the clientData and interp arguments will be the same as those passed to Tcl_CreateMathFunc. Args will point to an array of numArgs Tcl_Value structures, which describe the actual arguments to the function: typedef struct Tcl_Value { Tcl_ValueType type; long intValue; double doubleValue; } Tcl_Value; The type field indicates the type of the argument and is either TCL_INT or TCL_DOUBLE. It will match the argTypes value specified for the function unless the argTypes value was TCL_EITHER. Tcl converts the argument supplied in the expression to the type requested in argTypes, if that is necessary. Depending on the value of the type field, the intValue or doubleValue field will contain the actual value of the argument. Proc should compute its result and store it either as an integer in resultPtr->intValue or as a floating value in resultPtr->doubleValue. It should set also resultPtr->type to either TCL_INT or TCL_DOUBLE to indicate which value was set. Under normal circumstances proc should return TCL_OK. If an error occurs while executing the function, proc should return TCL_ERROR and leave an error message in interp->result. KEYWORDS expression, mathematical function ═══ 2.19. Tcl_CreateModalTimeout ═══ NAME Tcl_CreateModalTimeout, Tcl_DeleteModalTimeout - special timer for modal operations SYNOPSIS #include Tcl_CreateModalTimeout(milliseconds, proc, clientData) Tcl_DeleteModalTimeout(proc, clientData) ARGUMENTS int milliseconds (in) How many milliseconds to wait before invoking proc. Tcl_TimerProc *proc (in) Procedure to invoke after milliseconds have elapsed. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION Tcl_CreateModalTimeout provides an alternate form of timer from those provided by Tcl_CreateTimerHandler. These timers are called "modal" because they are typically used in situations where a particular operation must be completed before the application does anything else. If such an operation needs a timeout, it cannot use normal timer events: if normal timer events were processed, arbitrary Tcl scripts might be invoked via other event handlers, which could interfere with the completion of the modal operation. The purpose of modal timers is to allow a single timeout to occur without allowing any normal timer events to occur. Tcl_CreateModalTimeout behaves just like Tcl_CreateTimerHandler except that it creates a modal timeout. Its arguments have the same meaning as for Tcl_CreateTimerHandler and proc is invoked just as for Tcl_CreateTimerHandler. Tcl_DeleteModalTimeout deletes the most recently created modal timeout; its arguments must match the corresponding arguments to the most recent call to Tcl_CreateModalTimeout. Modal timeouts differ from a normal timers in three ways. First, they will trigger regardless of whether the TCL_TIMER_EVENTS flag has been passed to Tcl_DoOneEvent. Typically modal timers are used with the TCL_TIMER_EVENTS flag off so that normal timers don't fire but modal ones do. Second, if several modal timers have been created they stack: only the top timer on the stack (the most recently created one) is active at any point in time. Modal timeouts must be deleted in inverse order from their creation. Third, modal timeouts are not deleted when they fire: once a modal timeout has fired, it will continue firing every time Tcl_DoOneEvent is called, until the timeout is deleted by calling Tcl_DeleteModalTimeout. Modal timeouts are only needed in a few special situations, and they should be used with caution. KEYWORDS callback, clock, handler, modal timeout ═══ 2.20. Tcl_CreateSlave ═══ NAME Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetSlaves, Tcl_GetMaster, Tcl_CreateAlias, Tcl_GetAlias, Tcl_GetAliases - manage multiple Tcl interpreters and aliases. SYNOPSIS #include int Tcl_IsSafe(interp) int Tcl_MakeSafe(interp) Tcl_Interp * Tcl_CreateSlave(interp, slaveName, isSafe) Tcl_Interp * Tcl_GetSlave(interp, slaveName) Tcl_Interp * Tcl_GetMaster(interp) int Tcl_GetInterpPath(askingInterp, slaveInterp) int Tcl_CreateAlias(slaveInterp, srcCmd, targetInterp, targetCmd, argc, argv) int Tcl_GetAlias(interp, srcCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to execute the specified command. char *slaveName (in) Name of slave interpreter to create or manipulate. int isSafe (in) Zero means the interpreter may have all Tcl functions. Non-zero means the new interpreter's functionality should be limited to make it safe. Tcl_Interp *slaveInterp (in) Interpreter to use for creating the source command for an alias (see below). char *srcCmd (in) Name of source command for alias. Tcl_Interp *targetInterp (in) Interpreter that contains the target command for an alias. char *targetCmd (in) Name of target command for alias in targetInterp. int argc (in) Count of additional arguments to pass to the alias command. char **argv (in) Vector of strings, the additional arguments to pass to the alias command. This storage is owned by the caller. Tcl_Interp **targetInterpPtr (in) Pointer to location to store the address of the interpreter where a target command is defined for an alias. char **targetCmdPtr (out) Pointer to location to store the address of the name of the target command for an alias. int *argcPtr (out) Pointer to location to store count of additional arguments to be passed to the alias. The location is in storage owned by the caller. char ***argvPtr (out) Pointer to location to store a vector of strings, the additional arguments to pass to an alias. The location is in storage owned by the caller, the vector of strings is owned by the called function. DESCRIPTION These procedures are intended for access to the multiple interpreter facility from inside C programs. They enable managing multiple interpreters in a hierarchical relationship, and the management of aliases, commands that when invoked in one interpreter execute a command in another interpreter. The return value for those procedures that return an int is either TCL_OK or TCL_ERROR. If TCL_ERROR is returned then the result field of the interpreter contains an error message. Tcl_CreateSlave creates a new interpreter as a slave of the given interpreter. It also creates a slave command in the given interpreter which allows the master interpreter to manipulate the slave. The slave interpreter and the slave command have the specified name. If isSafe is 1, the new slave interpreter is made "safe" by removing all unsafe functionality. If the creation failed, NULL is returned. Tcl_IsSafe returns 1 if the given interpreter is "safe", 0 otherwise. Tcl_MakeSafe makes the given interpreter "safe" by removing all non-core and core unsafe functionality. Note that if you call this after adding some extension to an interpreter, all traces of that extension will be removed from the interpreter. This operation always succeeds and returns TCL_OK. Tcl_GetSlave returns a pointer to a slave interpreter of the given interpreter. The slave interpreter is identified by the name specified. If no such slave interpreter exists, NULL is returned. Tcl_GetMaster returns a pointer to the master interpreter of the given interpreter. If the given interpreter has no master (it is a top-level interpreter) then NULL is returned. Tcl_GetInterpPath sets the result field in askingInterp to the relative path between askingInterp and slaveInterp; slaveInterp must be a slave of askingInterp. If the computation of the relative path succeeds, TCL_OK is returned, else TCL_ERROR is returned and the result field in askingInterp contains the error message. Tcl_GetAlias returns information about an alias of a specified name in a given interpreter. Any of the result fields can be NULL, in which case the corresponding datum is not returned. If a result field is non-NULL, the address indicated is set to the corresponding datum. For example, if targetNamePtr is non-NULL it is set to a pointer to the string containing the name of the target command. In order to map over all slave interpreters, use Tcl_Eval with the command interp slaves and use the value (a Tcl list) deposited in the result field of the interpreter. Similarly, to map over all aliases whose source commands are defined in an interpreter, use Tcl_Eval with the command interp aliases and use the value (a Tcl list) deposited in the result field. Note that the storage of this list belongs to Tcl, so you should copy it before invoking any other Tcl commands in that interpreter. SEE ALSO For a description of the Tcl interface to multiple interpreters, see interp(n). KEYWORDS alias, command, interpreter, master, slave ═══ 2.21. Tcl_CreateTimerHandler ═══ NAME Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler - call a procedure at a given time SYNOPSIS #include Tcl_TimerToken Tcl_CreateTimerHandler(milliseconds, proc, clientData) Tcl_DeleteTimerHandler(token) ARGUMENTS int milliseconds (in) How many milliseconds to wait before invoking proc. Tcl_TimerProc *proc (in) Procedure to invoke after milliseconds have elapsed. ClientData clientData (in) Arbitrary one-word value to pass to proc. Tcl_TimerToken token (in) Token for previously-created timer handler (the return value from some previous call to Tcl_CreateTimerHandler). DESCRIPTION Tcl_CreateTimerHandler arranges for proc to be invoked at a time milliseconds milliseconds in the future. The callback to proc will be made by Tcl_DoOneEvent, so Tcl_CreateTimerHandler is only useful in programs that dispatch events through Tcl_DoOneEvent or through Tcl commands such as vwait. The call to proc may not be made at the exact time given by milliseconds: it will be made at the next opportunity after that time. For example, if Tcl_DoOneEvent isn't called until long after the time has elapsed, or if there are other pending events to process before the call to proc, then the call to proc will be delayed. Proc should have arguments and return value that match the type Tcl_TimerProc: typedef void Tcl_TimerProc(ClientData clientData); The clientData parameter to proc is a copy of the clientData argument given to Tcl_CreateTimerHandler when the callback was created. Typically, clientData points to a data structure containing application-specific information about what to do in proc. Tcl_DeleteTimerHandler may be called to delete a previously-created timer handler. It deletes the handler indicated by token so that no call to proc will be made; if that handler no longer exists (e.g. because the time period has already elapsed and proc has been invoked then Tcl_DeleteTimerHandler does nothing. The tokens returned by Tcl_CreateTimerHandler never have a value of NULL, so if NULL is passed to Tcl_DeleteTimerHandler then the procedure does nothing. KEYWORDS callback, clock, handler, timer ═══ 2.22. Tcl_CreateTrace ═══ NAME Tcl_CreateTrace, Tcl_DeleteTrace - arrange for command execution to be traced SYNOPSIS #include Tcl_Trace Tcl_CreateTrace(interp, level, proc, clientData) Tcl_DeleteTrace(interp, trace) ARGUMENTS Tcl_Interp *interp (in) Interpreter containing command to be traced or untraced. int level (in) Only commands at or below this nesting level will be traced. 1 means top-level commands only, 2 means top-level commands or those that are invoked as immediate consequences of executing top-level commands (procedure bodies, bracketed commands, etc.) and so on. Tcl_CmdTraceProc *proc (in) Procedure to call for each command that's executed. See below for details on the calling sequence. ClientData clientData (in) Arbitrary one-word value to pass to proc. Tcl_Trace trace (in) Token for trace to be removed (return value from previous call to Tcl_CreateTrace). DESCRIPTION Tcl_CreateTrace arranges for command tracing. From now on, proc will be invoked before Tcl calls command procedures to process commands in interp. The return value from Tcl_CreateTrace is a token for the trace, which may be passed to Tcl_DeleteTrace to remove the trace. There may be many traces in effect simultaneously for the same command interpreter. Proc should have arguments and result that match the type Tcl_CmdTraceProc: typedef void Tcl_CmdTraceProc( ClientData clientData, Tcl_Interp *interp, int level, char *command, Tcl_CmdProc *cmdProc, ClientData cmdClientData, int argc, char *argv[]); The clientData and interp parameters are copies of the corresponding arguments given to Tcl_CreateTrace. ClientData typically points to an application-specific data structure that describes what to do when proc is invoked. Level gives the nesting level of the command (1 for top-level commands passed to Tcl_Eval by the application, 2 for the next-level commands passed to Tcl_Eval as part of parsing or interpreting level-1 commands, and so on). Command points to a string containing the text of the command, before any argument substitution. CmdProc contains the address of the command procedure that will be called to process the command (i.e. the proc argument of some previous call to Tcl_CreateCommand) and cmdClientData contains the associated client data for cmdProc (the clientData value passed to Tcl_CreateCommand). Argc and argv give the final argument information that will be passed to cmdProc, after command, variable, and backslash substitution. Proc must not modify the command or argv strings. Tracing will only occur for commands at nesting level less than or equal to the level parameter (i.e. the level parameter to proc will always be less than or equal to the level parameter to Tcl_CreateTrace). Calls to proc will be made by the Tcl parser immediately before it calls the command procedure for the command (cmdProc). This occurs after argument parsing and substitution, so tracing for substituted commands occurs before tracing of the commands containing the substitutions. If there is a syntax error in a command, or if there is no command procedure associated with a command name, then no tracing will occur for that command. If a string passed to Tcl_Eval contains multiple commands (bracketed, or on different lines) then multiple calls to proc will occur, one for each command. The command string for each of these trace calls will reflect only a single command, not the entire string passed to Tcl_Eval. Tcl_DeleteTrace removes a trace, so that no future calls will be made to the procedure associated with the trace. After Tcl_DeleteTrace returns, the caller should never again use the trace token. KEYWORDS command, create, delete, interpreter, trace ═══ 2.23. Tcl_DString ═══ NAME Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult - manipulate dynamic strings SYNOPSIS #include Tcl_DStringInit(dsPtr) char * Tcl_DStringAppend(dsPtr, string, length) char * Tcl_DStringAppendElement(dsPtr, string) Tcl_DStringStartSublist(dsPtr) Tcl_DStringEndSublist(dsPtr) int Tcl_DStringLength(dsPtr) char * Tcl_DStringValue(dsPtr) Tcl_DStringSetLength(dsPtr, newLength) Tcl_DStringFree(dsPtr) Tcl_DStringResult(interp, dsPtr) Tcl_DStringGetResult(interp, dsPtr) ARGUMENTS Tcl_DString *dsPtr (in/out) Pointer to structure that is used to manage a dynamic string. char *string (in) Pointer to characters to add to dynamic string. int length (in) Number of characters from string to add to dynamic string. If -1, add all characters up to null terminating character. int newLength (in) New length for dynamic string, not including null terminating character. Tcl_Interp *interp (in/out) Interpreter whose result is to be set from or moved to the dynamic string. DESCRIPTION Dynamic strings provide a mechanism for building up arbitrarily long strings by gradually appending information. If the dynamic string is short then there will be no memory allocation overhead; as the string gets larger, additional space will be allocated as needed. Tcl_DStringInit initializes a dynamic string to zero length. The Tcl_DString structure must have been allocated by the caller. No assumptions are made about the current state of the structure; anything already in it is discarded. If the structure has been used previously, Tcl_DStringFree should be called first to free up any memory allocated for the old string. Tcl_DStringAppend adds new information to a dynamic string, allocating more memory for the string if needed. If length is less than zero then everything in string is appended to the dynamic string; otherwise length specifies the number of bytes to append. Tcl_DStringAppend returns a pointer to the characters of the new string. The string can also be retrieved from the string field of the Tcl_DString structure. Tcl_DStringAppendElement is similar to Tcl_DStringAppend except that it doesn't take a length argument (it appends all of string) and it converts the string to a proper list element before appending. Tcl_DStringAppendElement adds a separator space before the new list element unless the new list element is the first in a list or sub-list (i.e. either the current string is empty, or it contains the single character "{", or the last two characters of the current string are " {"). Tcl_DStringAppendElement returns a pointer to the characters of the new string. Tcl_DStringStartSublist and Tcl_DStringEndSublist can be used to create nested lists. To append a list element that is itself a sublist, first call Tcl_DStringStartSublist, then call Tcl_DStringAppendElement for each of the elements in the sublist, then call Tcl_DStringEndSublist to end the sublist. Tcl_DStringStartSublist appends a space character if needed, followed by an open brace; Tcl_DStringEndSublist appends a close brace. Lists can be nested to any depth. Tcl_DStringLength is a macro that returns the current length of a dynamic string (not including the terminating null character). Tcl_DStringValue is a macro that returns a pointer to the current contents of a dynamic string. Tcl_DStringSetLength changes the length of a dynamic string. If newLength is less than the string's current length, then the string is truncated. If newLength is greater than the string's current length, then the string will become longer and new space will be allocated for the string if needed. However, Tcl_DStringSetLength will not initialize the new space except to provide a terminating null character; it is up to the caller to fill in the new space. Tcl_DStringSetLength does not free up the string's storage space even if the string is truncated to zero length, so Tcl_DStringFree will still need to be called. Tcl_DStringFree should be called when you're finished using the string. It frees up any memory that was allocated for the string and reinitializes the string's value to an empty string. Tcl_DStringResult sets the result of interp to the value of the dynamic string given by dsPtr. It does this by moving a pointer from dsPtr to interp->result. This saves the cost of allocating new memory and copying the string. Tcl_DStringResult also reinitializes the dynamic string to an empty string. Tcl_DStringGetResult does the opposite of Tcl_DStringResult. It sets the value of dsPtr to the result of interp and it clears interp's result. If possible it does this by moving a pointer rather than by copying the string. KEYWORDS append, dynamic string, free, result ═══ 2.24. Tcl_DetachPids ═══ NAME Tcl_DetachPids, Tcl_ReapDetachedProcs - manage child processes in background SYNOPSIS #include Tcl_DetachPids(numPids, pidPtr) Tcl_ReapDetachedProcs() ARGUMENTS int numPids (in) Number of process ids contained in the array pointed to by pidPtr. int *pidPtr (in) Address of array containing numPids process ids. DESCRIPTION Tcl_DetachPids and Tcl_ReapDetachedProcs provide a mechanism for managing subprocesses that are running in background. These procedures are needed because the parent of a process must eventually invoke the waitpid kernel call (or one of a few other similar kernel calls) to wait for the child to exit. Until the parent waits for the child, the child's state cannot be completely reclaimed by the system. If a parent continually creates children and doesn't wait on them, the system's process table will eventually overflow, even if all the children have exited. Tcl_DetachPids may be called to ask Tcl to take responsibility for one or more processes whose process ids are contained in the pidPtr array passed as argument. The caller presumably has started these processes running in background and doesn't want to have to deal with them again. Tcl_ReapDetachedProcs invokes the waitpid kernel call on each of the background processes so that its state can be cleaned up if it has exited. If the process hasn't exited yet, Tcl_ReapDetachedProcs doesn't wait for it to exit; it will check again the next time it is invoked. Tcl automatically calls Tcl_ReapDetachedProcs each time the exec command is executed, so in most cases it isn't necessary for any code outside of Tcl to invoke Tcl_ReapDetachedProcs. However, if you call Tcl_DetachPids in situations where the exec command may never get executed, you may wish to call Tcl_ReapDetachedProcs from time to time so that background processes can be cleaned up. KEYWORDS background, child, detach, process, wait ═══ 2.25. Tcl_DoOneEvent ═══ NAME Tcl_DoOneEvent - wait for events and invoke event handlers SYNOPSIS #include int Tcl_DoOneEvent(flags) ARGUMENTS int flags (in) This parameter is normally zero. It may be an OR-ed combination of any of the following flag bits: TCL_WINDOW_EVENTS, TCL_FILE_EVENTS, TCL_TIMER_EVENTS, TCL_IDLE_EVENTS, TCL_ALL_EVENTS, or TCL_DONT_WAIT. DESCRIPTION This procedure is the entry point to Tcl's event loop; it is responsible for waiting for events and dispatching event handlers created with procedures such as Tk_CreateEventHandler, Tcl_CreateFileHandler, Tcl_CreateTimerHandler, and Tcl_DoWhenIdle. Tcl_DoOneEvent checks to see if events are already present on the Tcl event queue; if so, it calls the handler(s) for the first (oldest) event, removes it from the queue, and returns. If there are no events ready to be handled, then Tcl_DoOneEvent checks for new events from all possible sources. If any are found, it puts all of them on Tcl's event queue, calls handlers for the first event on the queue, and returns. If no events are found, Tcl_DoOneEvent checks for Tcl_DoWhenIdle callbacks; if any are found, it invokes all of them and returns. Finally, if no events or idle callbacks have been found, then Tcl_DoOneEvent sleeps until an event occurs; then it adds any ew events to the Tcl event queue, calls handlers for the first event, and returns. The normal return value is 1 to signify that some event was processed (see below for other alternatives). If the flags argument to Tcl_DoOneEvent is non-zero, it restricts the kinds of events that will be processed by Tcl_DoOneEvent. Flags may be an OR-ed combination of any of the following bits: TCL_WINDOW_EVENTS - Process window system events. TCL_FILE_EVENTS - Process file events. TCL_TIMER_EVENTS - Process timer events. TCL_IDLE_EVENTS - Process idle callbacks. TCL_ALL_EVENTS - Process all kinds of events: equivalent to OR-ing together all of the above flags or specifying none of them. TCL_DONT_WAIT - Don't sleep: process only events that are ready at the time of the call. If any of the flags TCL_WINDOW_EVENTS, TCL_FILE_EVENTS, TCL_TIMER_EVENTS, or TCL_IDLE_EVENTS is set, then the only events that will be considered are those for which flags are set. Setting none of these flags is equivalent to the value TCL_ALL_EVENTS, which causes all event types to be processed. If an application has defined additional event sources with Tcl_CreateEventSource, then additional flag values may also be valid, depending on those event sources. The TCL_DONT_WAIT flag causes Tcl_DoOneEvent not to put the process to sleep: it will check for events but if none are found then it returns immediately with a return value of 0 to indicate that no work was done. Tcl_DoOneEvent will also return 0 without doing anything if the only alternative is to block forever (this can happen, for example, if flags is TCL_IDLE_EVENTS and there are no Tcl_DoWhenIdle callbacks pending, or if no event handlers or timer handlers exist). Tcl_DoOneEvent may be invoked recursively. For example, it is possible to invoke Tcl_DoOneEvent recursively from a handler called by Tcl_DoOneEvent. This sort of operation is useful in some modal situations, such as when a notification dialog has been popped up and an application wishes to wait for the user to click a button in the dialog before doing anything else. KEYWORDS callback, event, handler, idle, timer ═══ 2.26. Tcl_DoWhenIdle ═══ NAME Tcl_DoWhenIdle, Tcl_CancelIdleCall - invoke a procedure when there are no pending events SYNOPSIS #include Tcl_DoWhenIdle(proc, clientData) Tcl_CancelIdleCall(proc, clientData) ARGUMENTS Tcl_IdleProc *proc (in) Procedure to invoke. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION Tcl_DoWhenIdle arranges for proc to be invoked when the application becomes idle. The application is considered to be idle when Tcl_DoOneEvent has been called, couldn't find any events to handle, and is about to go to sleep waiting for an event to occur. At this point all pending Tcl_DoWhenIdle handlers are invoked. For each call to Tcl_DoWhenIdle there will be a single call to proc; after proc is invoked the handler is automatically removed. Tcl_DoWhenIdle is only usable in programs that use Tcl_DoOneEvent to dispatch events. Proc should have arguments and result that match the type Tcl_IdleProc: typedef void Tcl_IdleProc(ClientData clientData); The clientData parameter to proc is a copy of the clientData argument given to Tcl_DoWhenIdle. Typically, clientData points to a data structure containing application-specific information about what proc should do. Tcl_CancelIdleCall may be used to cancel one or more previous calls to Tcl_DoWhenIdle: if there is a Tcl_DoWhenIdle handler registered for proc and clientData, then it is removed without invoking it. If there is more than one handler on the idle list that refers to proc and clientData, all of the handlers are removed. If no existing handlers match proc and clientData then nothing happens. Tcl_DoWhenIdle is most useful in situations where (a) a piece of work will have to be done but (b) it's possible that something will happen in the near future that will change what has to be done or require something different to be done. Tcl_DoWhenIdle allows the actual work to be deferred until all pending events have been processed. At this point the exact work to be done will presumably be known and it can be done exactly once. For example, Tcl_DoWhenIdle might be used by an editor to defer display updates until all pending commands have been processed. Without this feature, redundant redisplays might occur in some situations, such as the processing of a command file. BUGS At present it is not safe for an idle callback to reschedule itself continuously. This will interact badly with certain features of Tk that attempt to wait for all idle callbacks to complete. If you would like for an idle callback to reschedule itself continuously, it is better to use a timer handler with a zero timeout period. KEYWORDS callback, defer, idle callback ═══ 2.27. Tcl_Eval ═══ NAME Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval - execute Tcl commands SYNOPSIS #include int Tcl_Eval(interp, cmd) int Tcl_VarEval(interp, string, string, ... (char *) NULL) int Tcl_EvalFile(interp, fileName) int Tcl_GlobalEval(interp, cmd) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to execute the command. String result will be stored in interp->result. char *cmd (in) Command (or sequence of commands) to execute. Must be in writable memory (Tcl_Eval makes temporary modifications to the command). char *string (in) String forming part of Tcl command. char *fileName (in) Name of file containing Tcl command string. DESCRIPTION All four of these procedures execute Tcl commands. Tcl_Eval is the core procedure: it parses commands from cmd and executes them in order until either an error occurs or it reaches the end of the string. The return value from Tcl_Eval is one of the Tcl return codes TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE, and interp->result will point to a string with additional information (result value or error message). This return information corresponds to the last command executed from cmd. Tcl_VarEval takes any number of string arguments of any length, concatenates them into a single string, then calls Tcl_Eval to execute that string as a Tcl command. It returns the result of the command and also modifies interp->result in the usual fashion for Tcl commands. The last argument to Tcl_VarEval must be NULL to indicate the end of arguments. Tcl_EvalFile reads the file given by fileName and evaluates its contents as a Tcl command by calling Tcl_Eval. It returns a standard Tcl result that reflects the result of evaluating the file. If the file couldn't be read then a Tcl error is returned to describe why the file couldn't be read. Tcl_GlobalEval is similar to Tcl_Eval except that it processes the command at global level. This means that the variable context for the command consists of global variables only (it ignores any Tcl procedure that is active). This produces an effect similar to the Tcl command "uplevel 0". During the processing of a Tcl command it is legal to make nested calls to evaluate other commands (this is how conditionals, loops, and procedures are implemented). If a code other than TCL_OK is returned from a nested Tcl_Eval invocation, then the caller should normally return immediately, passing that same return code back to its caller, and so on until the top-level application is reached. A few commands, like for, will check for certain return codes, like TCL_BREAK and TCL_CONTINUE, and process them specially without returning. Tcl_Eval keeps track of how many nested Tcl_Eval invocations are in progress for interp. If a code of TCL_RETURN, TCL_BREAK, or TCL_CONTINUE is about to be returned from the topmost Tcl_Eval invocation for interp, then Tcl_Eval converts the return code to TCL_ERROR and sets interp->result to point to an error message indicating that the return, break, or continue command was invoked in an inappropriate place. This means that top-level applications should never see a return code from Tcl_Eval other then TCL_OK or TCL_ERROR. KEYWORDS command, execute, file, global, interpreter, variable ═══ 2.28. Tcl_Exit ═══ NAME Tcl_Exit, Tcl_CreateExitHandler, Tcl_DeleteExitHandler - end the application (and invoke exit handlers) SYNOPSIS #include Tcl_Exit(status) Tcl_CreateExitHandler(proc, clientData) Tcl_DeleteExitHandler(proc, clientData) ARGUMENTS int status (in) Provides information about why application exited. Exact meaning may be platform-specific. 0 usually means a normal exit, 1 means that an error occurred. Tcl_ExitProc *proc (in) Procedure to invoke before exiting application. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION Tcl_Exit is the procedure that is invoked to end a Tcl application. It is invoked by the exit command, as well as anyplace else that terminates the application. No-one should ever invoke the exit procedure directly; always invoke Tcl_Exit instead, so that it can invoke exit handlers. Tcl_CreateExitHandler arranges for proc to be invoked by Tcl_Exit before it terminates the application. This provides a hook for cleanup operations such as flushing buffers and freeing global memory. Proc should have arguments and return value that match the type Tcl_ExitProc: typedef void Tcl_ExitProc(ClientData clientData); The clientData parameter to proc is a copy of the clientData argument given to Tcl_CreateExitHandler when the callback was created. Typically, clientData points to a data structure containing application-specific information about what to do in proc. Tcl_DeleteExitHandler may be called to delete a previously-created exit handler. It removes the handler indicated by proc and clientData so that no call to proc will be made. If no such handler exists then Tcl_DeleteExitHandler does nothing. KEYWORDS callback, end application, exit ═══ 2.29. Tcl_ExprLong ═══ NAME Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString - evaluate an expression SYNOPSIS #include int Tcl_ExprLong(interp, string, longPtr) int Tcl_ExprDouble(interp, string, doublePtr) int Tcl_ExprBoolean(interp, string, booleanPtr) int Tcl_ExprString(interp, string) ARGUMENTS Tcl_Interp *interp (in) Interpreter in whose context to evaluate string. char *string (in) Expression to be evaluated. Must be in writable memory (the expression parser makes temporary modifications to the string during parsing, which it undoes before returning). long *longPtr (out) Pointer to location in which to store the integer value of the expression. int *doublePtr (out) Pointer to location in which to store the floating-point value of the expression. int *booleanPtr (out) Pointer to location in which to store the 0/1 boolean value of the expression. DESCRIPTION These four procedures all evaluate an expression, returning the result in one of four different forms. The expression is given by the string argument, and it can have any of the forms accepted by the expr command. The interp argument refers to an interpreter used to evaluate the expression (e.g. for variables and nested Tcl commands) and to return error information. Interp->result is assumed to be initialized in the standard fashion when any of the procedures are invoked. For all of these procedures the return value is a standard Tcl result: TCL_OK means the expression was successfully evaluated, and TCL_ERROR means that an error occurred while evaluating the expression. If TCL_ERROR is returned then interp->result will hold a message describing the error. If an error occurs while executing a Tcl command embedded in the expression then that error will be returned. If the expression is successfully evaluated, then its value is returned in one of four forms, depending on which procedure is invoked. Tcl_ExprLong stores an integer value at *longPtr. If the expression's actual value is a floating-point number, then it is truncated to an integer. If the expression's actual value is a non-numeric string then an error is returned. Tcl_ExprDouble stores a floating-point value at *doublePtr. If the expression's actual value is an integer, it is converted to floating-point. If the expression's actual value is a non-numeric string then an error is returned. Tcl_ExprBoolean stores a 0/1 integer value at *booleanPtr. If the expression's actual value is an integer or floating-point number, then Tcl_ExprBoolean stores 0 at *booleanPtr if the value was zero and 1 otherwise. If the expression's actual value is a non-numeric string then it must be one of the values accepted by Tcl_GetBoolean, such as "yes" or "no", or else an error occurs. Tcl_ExprString returns the value of the expression as a string stored in interp->result. If the expression's actual value is an integer then Tcl_ExprString converts it to a string using sprintf with a "%d" converter. If the expression's actual value is a floating-point number, then Tcl_ExprString calls Tcl_PrintDouble to convert it to a string. KEYWORDS boolean, double, evaluate, expression, integer, string ═══ 2.30. Tcl_FindExecutable ═══ NAME Tcl_FindExecutable - identify the binary file containing the application SYNOPSIS #include char * Tcl_FindExecutable(argv0) ARGUMENTS char *argv0 (in) The first command-line argument to the program, which gives the application's name. DESCRIPTION This procedure computes the full path name of the executable file from which the application was invoked and saves it for Tcl's internal use. The executable's path name is needed for several purposes in Tcl. For example, it is needed on some platforms in the implementation of the load command. It is also returned by the info nameofexecutable command. On UNIX platforms this procedure is typically invoked as the very first thing in the application's main program; it must be passed argv[0] as its argument. Tcl_FindExecutable uses argv0 along with the PATH environment variable to find the application's executable, if possible. If it fails to find the binary, then future calls to info nameofexecutable will return an empty string. KEYWORDS binary, executable file ═══ 2.31. Tcl_GetFile ═══ NAME Tcl_GetFile, Tcl_FreeFile, Tcl_GetFileInfo - procedures to manipulate generic file handles SYNOPSIS #include Tcl_File Tcl_GetFile(osHandle, type) Tcl_FreeFile(handle) ClientData Tcl_GetFileInfo(handle, typePtr) ClientData Tcl_GetNotifierData(handle, freeProcPtr) Tcl_SetNotifierData(handle, freeProc, clientData) ARGUMENTS ClientData osHandle (in) Platform-specific file handle to be associated with the generic file handle. int type (in) The type of platform-specific file handle associated with the generic file handle. See below for a list of valid types. Tcl_File handle (in) Generic file handle associated with platform-specific file information. int *typePtr (in/out) If *typePtr is not NULL, then the specified word is set to contain the type associated with handle. Tcl_FileFreeProc *freeProc (in) Procedure to call when handle is deleted. Tcl_FileFreeProc **freeProcPtr (in/out) Pointer to location in which to store address of current free procedure for file handle. Ignored if NULL. ClientData clientData (in) Arbitrary one-word value associated with the given file handle. This data is owned by the caller. DESCRIPTION A Tcl_File is an opaque handle used to refer to files in a platform independent way in Tcl routines like Tcl_CreateFileHandler. A file handle has an associated platform-dependent osHandle, a type and additional private data used by the notifier to generate events for the file. The type is an integer that determines how the platform-specific drivers will interpret the osHandle. The types that are defined by the core are: TCL_UNIX_FD The osHandle is a Unix file descriptor. TCL_MAC_FILE The file is a Macintosh file handle. TCL_WIN_FILE The osHandle is a Windows normal file HANDLE. TCL_WIN_PIPE The osHandle is a Windows anonymous pipe HANDLE. TCL_WIN_SOCKET The osHandle is a Windows SOCKET. TCL_WIN_CONSOLE The osHandle is a Windows console buffer HANDLE. Tcl_GetFile locates the file handle corresponding to a particular osHandle and a type. If a file handle already existed for the given file, then that handle will be returned. If this is the first time that the file handle for a particular file is being retrieved, then a new file handle will be allocated and returned. When a file handle is no longer in use, it should be deallocated with a call to Tcl_FreeFile. A call to this function will invoke the notifier free procedure proc, if there is one. After the notifier has cleaned up, any resources used by the file handle will be deallocated. Tcl_FreeFile will not close the platform-specific osHandle. Tcl_GetFileInfo may be used to retrieve the platform-specific osHandle and type associated with a file handle. If typePtr is not NULL, then the word at *typePtr is set to the type of the file handle. The return value of the function is the associated platform-specific osHandle. Note that this function may be used to extract the platform-specific file handle from a Tcl_File so that it may be used in external interfaces. However, programs written using this interface will be platform-specific. The Tcl_SetNotifierData and Tcl_GetNotifierData procedures are intended to be used only by notifier writers. See the Tcl_CreateEventSource(3) manual entry for more information on the notifier. Tcl_SetNotifierData may be used by notifier writers to associate notifier-specific information with a Tcl_File. The data argument specifies a word that may be retrieved with a later call to Tcl_GetNotifierData. If the freeProc argument is non-NULL it specifies the address of a procedure to invoke when the Tcl_File is deleted. freeProc should have arguments and result that match the type Tcl_FileFreeProc: typedef void Tcl_FileFreeProc( ClientData clientData); When freeProc is invoked the clientData argument will be the same as the corresponding argument passed to Tcl_SetNotifierData. Tcl_GetNotifierData returns the clientData associated with the given Tcl_File, and if the freeProcPtr field is non-NULL, the address indicated by it gets the address of the free procedure stored with this file. KEYWORDS generic file handle, file type, file descriptor, notifier ═══ 2.32. Tcl_GetInt ═══ NAME Tcl_GetInt, Tcl_GetDouble, Tcl_GetBoolean - convert from string to integer, double, or boolean SYNOPSIS #include int Tcl_GetInt(interp, string, intPtr) int Tcl_GetDouble(interp, string, doublePtr) int Tcl_GetBoolean(interp, string, boolPtr) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. char *string (in) Textual value to be converted. int *intPtr (out) Points to place to store integer value converted from string. double *doublePtr (out) Points to place to store double-precision floating-point value converted from string. int *boolPtr (out) Points to place to store boolean value (0 or 1) converted from string. DESCRIPTION These procedures convert from strings to integers or double-precision floating-point values or booleans (represented as 0- or 1-valued integers). Each of the procedures takes a string argument, converts it to an internal form of a particular type, and stores the converted value at the location indicated by the procedure's third argument. If all goes well, each of the procedures returns TCL_OK. If string doesn't have the proper syntax for the desired type then TCL_ERROR is returned, an error message is left in interp->result, and nothing is stored at *intPtr or *doublePtr or *boolPtr. Tcl_GetInt expects string to consist of a collection of integer digits, optionally signed and optionally preceded by white space. If the first two characters of string are "0x" then string is expected to be in hexadecimal form; otherwise, if the first character of string is "0" then string is expected to be in octal form; otherwise, string is expected to be in decimal form. Tcl_GetDouble expects string to consist of a floating-point number, which is: white space; a sign; a sequence of digits; a decimal point; a sequence of digits; the letter "e"; and a signed decimal exponent. Any of the fields may be omitted, except that the digits either before or after the decimal point must be present and if the "e" is present then it must be followed by the exponent number. Tcl_GetBoolean expects string to specify a boolean value. If string is any of 0, false, no, or off, then Tcl_GetBoolean stores a zero value at *boolPtr. If string is any of 1, true, yes, or on, then 1 is stored at *boolPtr. Any of these values may be abbreviated, and upper-case spellings are also acceptable. KEYWORDS boolean, conversion, double, floating-point, integer ═══ 2.33. Tcl_GetOpenFile ═══ NAME Tcl_GetOpenFile - Get a standard IO File * handle from a channel. SYNOPSIS #include int Tcl_GetOpenFile(interp, string, write, checkUsage, filePtr) ARGUMENTS Tcl_Interp *interp (in) Tcl interpreter from which file handle is to be obtained. char *string (in) String identifying channel, such as stdin or file4. int write (in) Non-zero means the file will be used for writing, zero means it will be used for reading. int checkUsage (in) If non-zero, then an error will be generated if the file wasn't opened for the access indicated by write. ClientData *filePtr (out) Points to word in which to store pointer to FILE structure for the file given by string. DESCRIPTION Tcl_GetOpenFile takes as argument a file identifier of the form returned by the open command and returns at *filePtr a pointer to the FILE structure for the file. The write argument indicates whether the FILE pointer will be used for reading or writing. In some cases, such as a channel that connects to a pipeline of subprocesses, different FILE pointers will be returned for reading and writing. Tcl_GetOpenFile normally returns TCL_OK. If an error occurs in Tcl_GetOpenFile (e.g. string didn't make any sense or checkUsage was set and the file wasn't opened for the access specified by write) then TCL_ERROR is returned and interp->result will contain an error message. In the current implementation checkUsage is ignored and consistency checks are always performed. KEYWORDS channel, file handle, permissions, pipeline, read, write ═══ 2.34. Tcl_GetStdChannel ═══ NAME Tcl_GetStdChannel, Tcl_SetStdChannel - procedures for retrieving and replacing the standard channels SYNOPSIS #include Tcl_Channel Tcl_GetStdChannel(type) Tcl_SetStdChannel(channel, type) ARGUMENTS int type (in) The identifier for the standard channel to retrieve or modify. Must be one of TCL_STDIN, TCL_STDOUT, or TCL_STDERR. Tcl_Channel channel (in) The channel to use as the new value for the specified standard channel. DESCRIPTION Tcl defines three special channels that are used by various I/O related commands if no other channels are specified. The standard input channel has a channel name of stdin and is used by read and gets. The standard output channel is named stdout and is used by puts. The standard error channel is named stderr and is used for reporting errors. In addition, the standard channels are inherited by any child processes created using exec or open in the absence of any other redirections. The standard channels are actually aliases for other normal channels. The current channel associated with a standard channel can be retrieved by calling Tcl_GetStdChannel with one of TCL_STDIN, TCL_STDOUT, or TCL_STDERR as the type. The return value will be a valid channel, or NULL. A new channel can be set for the standard channel specified by type by calling Tcl_SetStdChannel with a new channel or NULL in the channel argument. If the specified channel is closed by a later call to Tcl_Close, then the corresponding standard channel will automatically be set to NULL. If Tcl_GetStdChannel is called before Tcl_SetStdChannel, Tcl will construct a new channel to wrap the appropriate platform-specific standard file handle. If Tcl_SetStdChannel is called before Tcl_GetStdChannel, then the default channel will not be created. If one of the standard channels is set to NULL, either by calling Tcl_SetStdChannel with a null channel argument, or by calling Tcl_Close on the channel, then the next call to Tcl_CreateChannel will automatically set the standard channel with the newly created channel. If more than one standard channel is NULL, then the standard channels will be assigned starting with standard input, followed by standard output, with standard error being last. SEE ALSO Tcl_Close(3), Tcl_CreateChannel(3) KEYWORDS standard channel, standard input, standard output, standard error ═══ 2.35. Tcl_Hash ═══ NAME Tcl_InitHashTable, Tcl_DeleteHashTable, Tcl_CreateHashEntry, Tcl_DeleteHashEntry, Tcl_FindHashEntry, Tcl_GetHashValue, Tcl_SetHashValue, Tcl_GetHashKey, Tcl_FirstHashEntry, Tcl_NextHashEntry, Tcl_HashStats - procedures to manage hash tables SYNOPSIS #include Tcl_InitHashTable(tablePtr, keyType) Tcl_DeleteHashTable(tablePtr) Tcl_HashEntry * Tcl_CreateHashEntry(tablePtr, key, newPtr) Tcl_DeleteHashEntry(entryPtr) Tcl_HashEntry * Tcl_FindHashEntry(tablePtr, key) ClientData Tcl_GetHashValue(entryPtr) Tcl_SetHashValue(entryPtr, value) char * Tcl_GetHashKey(tablePtr, entryPtr) Tcl_HashEntry * Tcl_FirstHashEntry(tablePtr, searchPtr) Tcl_HashEntry * Tcl_NextHashEntry(searchPtr) char * Tcl_HashStats(tablePtr) ARGUMENTS Tcl_HashTable *tablePtr (in) Address of hash table structure (for all procedures but Tcl_InitHashTable, this must have been initialized by previous call to Tcl_InitHashTable). int keyType (in) Kind of keys to use for new hash table. Must be either TCL_STRING_KEYS, TCL_ONE_WORD_KEYS, or an integer value greater than 1. char *key (in) Key to use for probe into table. Exact form depends on keyType used to create table. int *newPtr (out) The word at *newPtr is set to 1 if a new entry was created and 0 if there was already an entry for key. Tcl_HashEntry *entryPtr (in) Pointer to hash table entry. ClientData value (in) New value to assign to hash table entry. Need not have type ClientData, but must fit in same space as ClientData. Tcl_HashSearch *searchPtr (in) Pointer to record to use to keep track of progress in enumerating all the entries in a hash table. DESCRIPTION A hash table consists of zero or more entries, each consisting of a key and a value. Given the key for an entry, the hashing routines can very quickly locate the entry, and hence its value. There may be at most one entry in a hash table with a particular key, but many entries may have the same value. Keys can take one of three forms: strings, one-word values, or integer arrays. All of the keys in a given table have the same form, which is specified when the table is initialized. The value of a hash table entry can be anything that fits in the same space as a "char *" pointer. Values for hash table entries are managed entirely by clients, not by the hash module itself. Typically each entry's value is a pointer to a data structure managed by client code. Hash tables grow gracefully as the number of entries increases, so that there are always less than three entries per hash bucket, on average. This allows for fast lookups regardless of the number of entries in a table. Tcl_InitHashTable initializes a structure that describes a new hash table. The space for the structure is provided by the caller, not by the hash module. The value of keyType indicates what kinds of keys will be used for all entries in the table. KeyType must have one of the following values: TCL_STRING_KEYS Keys are null-terminated ASCII strings. They are passed to hashing routines using the address of the first character of the string. TCL_ONE_WORD_KEYS Keys are single-word values; they are passed to hashing routines and stored in hash table entries as "char *" values. The pointer value is the key; it need not (and usually doesn't) actually point to a string. other If keyType is not TCL_STRING_KEYS or TCL_ONE_WORD_KEYS, then it must be an integer value greater than 1. In this case the keys will be arrays of "int" values, where keyType gives the number of ints in each key. This allows structures to be used as keys. All keys must have the same size. Array keys are passed into hashing functions using the address of the first int in the array. Tcl_DeleteHashTable deletes all of the entries in a hash table and frees up the memory associated with the table's bucket array and entries. It does not free the actual table structure (pointed to by tablePtr), since that memory is assumed to be managed by the client. Tcl_DeleteHashTable also does not free or otherwise manipulate the values of the hash table entries. If the entry values point to dynamically-allocated memory, then it is the client's responsibility to free these structures before deleting the table. Tcl_CreateHashEntry locates the entry corresponding to a particular key, creating a new entry in the table if there wasn't already one with the given key. If an entry already existed with the given key then *newPtr is set to zero. If a new entry was created, then *newPtr is set to a non-zero value and the value of the new entry will be set to zero. The return value from Tcl_CreateHashEntry is a pointer to the entry, which may be used to retrieve and modify the entry's value or to delete the entry from the table. Tcl_DeleteHashEntry will remove an existing entry from a table. The memory associated with the entry itself will be freed, but the client is responsible for any cleanup associated with the entry's value, such as freeing a structure that it points to. Tcl_FindHashEntry is similar to Tcl_CreateHashEntry except that it doesn't create a new entry if the key doesn't exist; instead, it returns NULL as result. Tcl_GetHashValue and Tcl_SetHashValue are used to read and write an entry's value, respectively. Values are stored and retrieved as type "ClientData", which is large enough to hold a pointer value. On almost all machines this is large enough to hold an integer value too. Tcl_GetHashKey returns the key for a given hash table entry, either as a pointer to a string, a one-word ("char *") key, or as a pointer to the first word of an array of integers, depending on the keyType used to create a hash table. In all cases Tcl_GetHashKey returns a result with type "char *". When the key is a string or array, the result of Tcl_GetHashKey points to information in the table entry; this information will remain valid until the entry is deleted or its table is deleted. Tcl_FirstHashEntry and Tcl_NextHashEntry may be used to scan all of the entries in a hash table. A structure of type "Tcl_HashSearch", provided by the client, is used to keep track of progress through the table. Tcl_FirstHashEntry initializes the search record and returns the first entry in the table (or NULL if the table is empty). Each subsequent call to Tcl_NextHashEntry returns the next entry in the table or NULL if the end of the table has been reached. A call to Tcl_FirstHashEntry followed by calls to Tcl_NextHashEntry will return each of the entries in the table exactly once, in an arbitrary order. It is unadvisable to modify the structure of the table, e.g. by creating or deleting entries, while the search is in progress. Tcl_HashStats returns a dynamically-allocated string with overall information about a hash table, such as the number of entries it contains, the number of buckets in its hash array, and the utilization of the buckets. It is the caller's responsibility to free the result string by passing it to free. The header file tcl.h defines the actual data structures used to implement hash tables. This is necessary so that clients can allocate Tcl_HashTable structures and so that macros can be used to read and write the values of entries. However, users of the hashing routines should never refer directly to any of the fields of any of the hash-related data structures; use the procedures and macros defined here. KEYWORDS hash table, key, lookup, search, value ═══ 2.36. Tcl_Interp ═══ NAME Tcl_Interp - client-visible fields of interpreter structures SYNOPSIS #include typedef struct { char *result; Tcl_FreeProc *freeProc; int errorLine; } Tcl_Interp; typedef void Tcl_FreeProc(char *blockPtr); DESCRIPTION The Tcl_CreateInterp procedure returns a pointer to a Tcl_Interp structure. This pointer is then passed into other Tcl procedures to process commands in the interpreter and perform other operations on the interpreter. Interpreter structures contain many many fields that are used by Tcl, but only three that may be accessed by clients: result, freeProc, and errorLine. The result and freeProc fields are used to return results or error messages from commands. This information is returned by command procedures back to Tcl_Eval, and by Tcl_Eval back to its callers. The result field points to the string that represents the result or error message, and the freeProc field tells how to dispose of the storage for the string when it isn't needed anymore. The easiest way for command procedures to manipulate these fields is to call procedures like Tcl_SetResult or Tcl_AppendResult; they will hide all the details of managing the fields. The description below is for those procedures that manipulate the fields directly. Whenever a command procedure returns, it must ensure that the result field of its interpreter points to the string being returned by the command. The result field must always point to a valid string. If a command wishes to return no result then interp->result should point to an empty string. Normally, results are assumed to be statically allocated, which means that the contents will not change before the next time Tcl_Eval is called or some other command procedure is invoked. In this case, the freeProc field must be zero. Alternatively, a command procedure may dynamically allocate its return value (e.g. using Tcl_Alloc) and store a pointer to it in interp->result. In this case, the command procedure must also set interp->freeProc to the address of a procedure that can free the value, or TCL_DYNAMIC if the storage was allocated directly by Tcl or by a call to Tcl_Alloc. If interp->freeProc is non-zero, then Tcl will call freeProc to free the space pointed to by interp->result before it invokes the next command. If a client procedure overwrites interp->result when interp->freeProc is non-zero, then it is responsible for calling freeProc to free the old interp->result (the Tcl_FreeResult macro should be used for this purpose). FreeProc should have arguments and result that match the Tcl_FreeProc declaration above: it receives a single argument which is a pointer to the result value to free. In most applications TCL_DYNAMIC is the only non-zero value ever used for freeProc. However, an application may store a different procedure address in freeProc in order to use an alternate memory allocator or in order to do other cleanup when the result memory is freed. As part of processing each command, Tcl_Eval initializes interp->result and interp->freeProc just before calling the command procedure for the command. The freeProc field will be initialized to zero, and interp->result will point to an empty string. Commands that do not return any value can simply leave the fields alone. Furthermore, the empty string pointed to by result is actually part of an array of TCL_RESULT_SIZE characters (approximately 200). If a command wishes to return a short string, it can simply copy it to the area pointed to by interp->result. Or, it can use the sprintf procedure to generate a short result string at the location pointed to by interp->result. It is a general convention in Tcl-based applications that the result of an interpreter is normally in the initialized state described in the previous paragraph. Procedures that manipulate an interpreter's result (e.g. by returning an error) will generally assume that the result has been initialized when the procedure is called. If such a procedure is to be called after the result has been changed, then Tcl_ResetResult should be called first to reset the result to its initialized state. The errorLine field is valid only after Tcl_Eval returns a TCL_ERROR return code. In this situation the errorLine field identifies the line number of the command being executed when the error occurred. The line numbers are relative to the command being executed: 1 means the first line of the command passed to Tcl_Eval, 2 means the second line, and so on. The errorLine field is typically used in conjunction with Tcl_AddErrorInfo to report information about where an error occurred. ErrorLine should not normally be modified except by Tcl_Eval. KEYWORDS free, initialized, interpreter, malloc, result ═══ 2.37. Tcl_LinkVar ═══ NAME Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar - link Tcl variable to C variable SYNOPSIS #include int Tcl_LinkVar(interp, varName, addr, type) Tcl_UnlinkVar(interp, varName) Tcl_UpdateLinkedVar(interp, varName) ARGUMENTS Tcl_Interp *interp (in) Interpreter that contains varName. Also used by Tcl_LinkVar to return error messages. char *varName (in) Name of global variable. Must be in writable memory: Tcl may make temporary modifications to it while parsing the variable name. char *addr (in) Address of C variable that is to be linked to varName. int type (in) Type of C variable. Must be one of TCL_LINK_INT, TCL_LINK_DOUBLE, TCL_LINK_BOOLEAN, or TCL_LINK_STRING, optionally OR'ed with TCL_LINK_READ_ONLY to make Tcl variable read-only. DESCRIPTION Tcl_LinkVar uses variable traces to keep the Tcl variable named by varName in sync with the C variable at the address given by addr. Whenever the Tcl variable is read the value of the C variable will be returned, and whenever the Tcl variable is written the C variable will be updated to have the same value. Tcl_LinkVar normally returns TCL_OK; if an error occurs while setting up the link (e.g. because varName is the name of array) then TCL_ERROR is returned and interp->result contains an error message. The type argument specifies the type of the C variable, and must have one of the following values, optionally OR'ed with TCL_LINK_READ_ONLY: TCL_LINK_INT The C variable is of type int. Any value written into the Tcl variable must have a proper integer form acceptable to Tcl_GetInt; attempts to write non-integer values into varName will be rejected with Tcl errors. TCL_LINK_DOUBLE The C variable is of type double. Any value written into the Tcl variable must have a proper real form acceptable to Tcl_GetDouble; attempts to write non-real values into varName will be rejected with Tcl errors. TCL_LINK_BOOLEAN The C variable is of type int. If its value is zero then it will read from Tcl as "0"; otherwise it will read from Tcl as "1". Whenever varName is modified, the C variable will be set to a 0 or 1 value. Any value written into the Tcl variable must have a proper boolean form acceptable to Tcl_GetBoolean; attempts to write non-boolean values into varName will be rejected with Tcl errors. TCL_LINK_STRING The C variable is of type char *. If its value is not null then it must be a pointer to a string allocated with Tcl_Alloc. Whenever the Tcl variable is modified the current C string will be freed and new memory will be allocated to hold a copy of the variable's new value. If the C variable contains a null pointer then the Tcl variable will read as "NULL". If the TCL_LINK_READ_ONLY flag is present in type then the variable will be read-only from Tcl, so that its value can only be changed by modifying the C variable. Attempts to write the variable from Tcl will be rejected with errors. Tcl_UnlinkVar removes the link previously set up for the variable given by varName. If there does not exist a link for varName then the procedure has no effect. Tcl_UpdateLinkedVar may be invoked after the C variable has changed to force the Tcl variable to be updated immediately. In many cases this procedure is not needed, since any attempt to read the Tcl variable will return the latest value of the C variable. However, if a trace has been set on the Tcl variable (such as a Tk widget that wishes to display the value of the variable), the trace will not trigger when the C variable has changed. Tcl_UpdateLinkedVar ensures that any traces on the Tcl variable are invoked. KEYWORDS boolean, integer, link, read-only, real, string, traces, variable ═══ 2.38. Tcl_CreateEventSource ═══ NAME Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_WatchFile, Tcl_FileReady, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_WaitForEvent - Event sources, the event notifier, and the event queue SYNOPSIS #include Tcl_CreateEventSource(setupProc, checkProc, clientData) Tcl_DeleteEventSource(setupProc, checkProc, clientData) Tcl_WatchFile(file, mask) Tcl_SetMaxBlockTime(timePtr) int Tcl_FileReady(file, mask) Tcl_QueueEvent(evPtr, position) int Tcl_WaitForEvent(timePtr) ARGUMENTS Tcl_EventSetupProc *setupProc (in) Procedure to invoke to prepare for event wait in Tcl_DoWhenIdle. Tcl_EventCheckProc *checkProc (in) Procedure for Tcl_DoWhenIdle to invoke after waiting for events. Checks to see if any events have occurred and, if so, queues them. ClientData clientData (in) Arbitrary one-word value to pass to setupProc and checkProc. Tcl_File file (in) Generic file handle as returned by Tcl_GetFile. int mask (in) Indicates the events of interest on file: an OR'ed combination of TCL_READABLE, TCL_WRITABLE, and TCL_EXCEPTION. Tcl_Time *timePtr (in) Indicates the maximum amount of time to wait for an event. This is specified as an interval (how long to wait), not an absolute time (when to wakeup). If the pointer passed to Tcl_WaitForEvent is NULL, it means there is no maximum wait time: wait forever if necessary. Tcl_Event *evPtr (in) An event to add to the event queue. The storage for the event must have been allocated by the caller using Tcl_Alloc or ckalloc. Tcl_QueuePosition position (in) Where to add the new event in the queue: TCL_QUEUE_TAIL, TCL_QUEUE_HEAD, or TCL_QUEUE_MARK. int flags (in) A copy of the flags argument passed to Tcl_DoOneEvent. INTRODUCTION The procedures described here are the building blocks out of which the Tcl event notifier is constructed. The event notifier is the lowest layer in the Tcl event mechanism. It consists of three things: 1. Event sources: these represent the ways in which events can be generated. For example, there is a timer event source that implements the Tcl_CreateTimerHandler procedure and the after command, and there is a file event source that implements the Tcl_CreateFileHandler procedure. An event source must work with the notifier to detect events at the right times, record them on the event queue, and eventually notify higher-level software that they have occurred. 2. The event queue: there is a single queue for the whole application, containing events that have been detected but not yet serviced. The event queue guarantees a fair discipline of event handling, so that no event source can starve the others. It also allows events to be saved for servicing at a future time. 3. The procedure Tcl_DoOneEvent: this is procedure that is invoked by the application to service events. It works with the event sources and the event queue to detect and handle events, and calls Tcl_WaitForEvent to actually wait for an event to occur. The easiest way to understand how the notifier works is to consider what happens when Tcl_DoOneEvent is called. Tcl_DoOneEvent is passed a flags argument that indicates what sort of events it is OK to process and also whether or not to block if no events are ready. Tcl_DoOneEvent does the following things: 1. Check the event queue to see if it contains any events that can be serviced. If so, service the first possible event, remove it from the queue, and return. 2. Prepare to block for an event. To do this, Tcl_DoOneEvent invokes a setup procedure in each event source. The event source will call procedures like Tcl_WatchFile and Tcl_SetMaxBlockTime to indicate what low-level events to look for in Tcl_WaitForEvent. 3. Call Tcl_WaitForEvent. This procedure is implemented differently on different platforms; it waits for an event to occur, based on the information provided by the event sources. It may cause the application to block if timePtr specifies an interval other than 0. Tcl_WaitForEvent returns when something has happened, such as a file becoming readable or the interval given by timePtr expiring. If there are no events for Tcl_WaitForEvent to wait for, so that it would block forever, then it returns immediately and Tcl_DoOneEvent returns 0. 4. Call a check procedure in each event source. The check procedure determines whether any events of interest to this source occurred (e.g. by calling Tcl_FileReady). If so, the events are added to the event queue. 5. Check the event queue to see if it contains any events that can be serviced. If so, service the first possible event, remove it from the queue, and return. 6. See if there are idle callbacks pending. If so, invoke all of them and return. 7. Either return 0 to indicate that no events were ready, or go back to step [2] if blocking was requested by the caller. The procedures in this file allow you to do two things. First, they allow you to create new event sources, such as one for UNIX signals or one to notify when subprocesses have exited. Second, the procedures can be used to build a new version of Tcl_DoOneEvent. This might be necessary to support a new operating system with different low-level event reporting mechanisms, or it might be necessary to merge Tcl's event loop with that of some other toolkit like Xt. CREATING A NEW EVENT SOURCE An event source consists of three procedures invoked by the notifier, plus additional C procedures that are invoked by higher-level code to arrange for event-driven callbacks. The three procedures called by the notifier consist of the setup and check procedures described above, plus an additional procedure that is invoked when an event is removed from the event queue for servicing. The procedure Tcl_CreateEventSource creates a new event source. Its arguments specify the setup procedure and check procedure for the event source. SetupProc should match the following prototype: typedef void Tcl_EventSetupProc( ClientData clientData, int flags); The clientData argument will be the same as the clientData argument to Tcl_CreateEventSource; it is typically used to point to private information managed by the event source. The flags argument will be the same as the flags argument passed to Tcl_DoOneEvent except that it will never by 0 (Tcl_DoOneEvent replaces 0 with TCL_ALL_EVENTS). Flags indicates what kinds of events should be considered; if the bit corresponding to this event source isn't set, the event source should return immediately without doing anything. For example, the file event source checks for the TCL_FILE_EVENTS bit. SetupProc's job is to provide information to Tcl_WaitForEvent about how to wait for events. It usually does this by calling Tcl_WatchFile or Tcl_SetMaxBlockTime. For example, setupProc can call Tcl_WatchFile to indicate that Tcl_WaitForEvent should return when the conditions given by the mask argument become true for the file given by file. The UNIX version of Tcl_WaitForEvent uses the information passed to Tcl_WatchFile to set the file masks for select, which it uses to wait for events. If Tcl_WatchFile isn't called by any event sources then Tcl_WaitForEvent will ignore files while waiting. SetupProc can also invoke Tcl_SetMaxBlockTime to set an upper bound on how long Tcl_WaitForEvent will block. If no event source calls Tcl_SetMaxBlockTime then Tcl_WaitForEvent will wait as long as necessary for an event to occur; otherwise, it will only wait as long as the shortest interval passed to Tcl_SetMaxBlockTime by one of the event sources. For example, the timer event source uses this procedure to limit the wait time to the interval before the next timer event is ready. If an event source knows that it already has events ready to report, it can request a zero maximum block time. The timePtr argument to Tcl_WaitForEvent points to a structure that describes a time interval in seconds and microseconds: typedef struct Tcl_Time { long sec; long usec; } Tcl_Time; The usec field should be less than 1000000. Information provided to Tcl_WatchFile and Tcl_SetMaxBlockTime is only used for the next call to Tcl_WaitForEvent; it is discarded after Tcl_WaitForEvent returns. The next time an event wait is done each of the event sources' setup procedures will be called again, and they can specify new information for that event wait. In addition to the generic procedures Tcl_WatchFile and Tcl_SetMaxBlockTime, other platform-specific procedures may also be available for setupProc, if there is additional information needed by Tcl_WaitForEvent on that platform. The second procedure provided by each event source is its check procedure, indicated by the checkProc argument to Tcl_CreateEventSource. CheckProc must match the following prototype: typedef void Tcl_EventCheckProc( ClientData clientData, int flags); The arguments to this procedure are the same as those for setupProc. CheckProc is invoked by Tcl_DoOneEvent after it has waited for events. Presumably at least one event source is now prepared to queue an event. Tcl_DoOneEvent calls each of the event sources in turn, so they all have a chance to queue any events that are ready. The check procedure does two things. First, it must see if any events have triggered. Different event sources do this in different ways, but the procedure Tcl_FileReady may be useful for some event sources. It takes as arguments a file identifier file and a mask of interesting conditions; it returns another mask indicating which of those conditions were found to be present on the file during the most recent call to Tcl_WaitForEvent. Tcl_WaitForEvent only checks a file if Tcl_WatchFile was called by at least one event source, so it is possible for Tcl_FileReady to return 0 even if the file is ready. If an event source's check procedure detects that an interesting event has occurred, then it must add the event to Tcl's event queue. To do this, the event source calls Tcl_QueueEvent. The evPtr argument is a pointer to a dynamically allocated structure containing the event (see below for more information on memory management issues). Each event source can define its own event structure with whatever information is relevant to that event source. However, the first element of the structure must be a structure of type Tcl_Event, and the address of this structure is used when communicating between the event source and the rest of the notifier. A Tcl_Event has the following definition: typedef struct Tcl_Event { Tcl_EventProc *proc; struct Tcl_Event *nextPtr; }; The event source must fill in the proc field of the event before calling Tcl_QueueEvent. The nextPtr is used to link together the events in the queue and should not be modified by the event source. An event may be added to the queue at any of three positions, depending on the position argument to Tcl_QueueEvent: TCL_QUEUE_TAIL Add the event at the back of the queue, so that all other pending events will be serviced first. This is almost always the right place for new events. TCL_QUEUE_HEAD Add the event at the front of the queue, so that it will be serviced before all other queued events. TCL_QUEUE_MARK Add the event at the front of the queue, unless there are other events at the front whose position is TCL_QUEUE_MARK; if so, add the new event just after all other TCL_QUEUE_MARK events. This value of position is used to insert an ordered sequence of events at the front of the queue, such as a series of Enter and Leave events synthesized during a grab or ungrab operation in Tk. When it is time to handle an event from the queue (steps 1 and 5 above) Tcl_DoOneEvent will invoke the proc specified in the first queued Tcl_Event structure. Proc must match the following prototype: typedef int Tcl_EventProc( Tcl_Event *evPtr, int flags); The first argument to proc is a pointer to the event, which will be the same as the first argument to the Tcl_QueueEvent call that added the event to the queue. The second argument to proc is the flags argument for the current call to Tcl_DoOneEvent; this is used by the event source to return immediately if its events are not relevant. It is up to proc to handle the event, typically by invoking one or more Tcl commands or C-level callbacks. Once the event source has finished handling the event it returns 1 to indicate that the event can be removed from the queue. If for some reason the event source decides that the event cannot be handled at this time, it may return 0 to indicate that the event should be deferred for processing later; in this case Tcl_DoOneEvent will go on to the next event in the queue and attempt to service it. There are several reasons why an event source might defer an event. One possibility is that events of this type are excluded by the flags argument. For example, the file event source will always return 0 if the TCL_FILE_EVENTS bit isn't set in flags. Another example of deferring events happens in Tk if Tk_RestrictEvents has been invoked to defer certain kinds of window events. When proc returns 1, Tcl_DoOneEvent will remove the event from the event queue and free its storage. Note that the storage for an event must be allocated by the event source (using Tcl_Alloc or the Tcl macro ckalloc) before calling Tcl_QueueEvent, but it will be freed by Tcl_DoOneEvent, not by the event source. CREATING A NEW NOTIFIER The notifier consists of all the procedures described in this manual entry, plus Tcl_DoOneEvent and Tcl_Sleep. Most of these procedures are generic, in that they are the same for all platforms. However, four of the procedures are platform-dependent: Tcl_WatchFile, Tcl_FileReady, Tcl_WaitForEvent, and Tcl_Sleep. To support a new platform, you must write new versions of these procedures. Tcl_WatchFile and Tcl_FileReady have already been described previously in this document, and Tcl_Sleep is described in its own manual entry. Tcl_WaitForEvent is the lowest-level procedure in the notifier; it is responsible for waiting for an "interesting" event to occur or for a given time to elapse. Before Tcl_WaitForEvent is invoked, each of the event sources' setup procedure will have been invoked; the setup procedures will have provided information about what to wait for by invoking procedures like Tcl_WatchFile. The timePtr argument to Tcl_WaitForEvent gives the maximum time to block for an event, based on calls to Tcl_SetMaxBlockTime made by setup procedures and on other information (such as the TCL_DONT_WAIT bit in flags). Tcl_WaitForEvent uses information saved by Tcl_WatchFile, plus the timePtr argument to decide what to wait for and how long to block. It returns TCL_OK as soon as one of the specified events has occurred or the given amount of time has elapsed. However, if there are no event handlers (neither Tcl_WatchFile nor Tcl_SetMaxBlockTime has been called since the last call to Tcl_WaitForEvent), so that the procedure would block forever, then it returns immediately with a result of TCL_ERROR. The easiest way to create a new notifier is to look at the code for an existing notifier, such as the files generic/tclNotify.c and unix/tclUnixNotfy.c. KEYWORDS block time, event notifier, event queue, event sources, file events ═══ 2.39. Tcl_OpenFileChannel ═══ NAME Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_Close, Tcl_Read, Tcl_Gets, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_Eof, Tcl_InputBlocked, Tcl_GetChannelOption, Tcl_SetChannelOption - buffered I/O facilities using channels SYNOPSIS #include typedef ... Tcl_Channel; Tcl_Channel Tcl_OpenFileChannel(interp, fileName, mode, permissions) Tcl_Channel Tcl_OpenCommandChannel(interp, argc, argv, flags) Tcl_Channel Tcl_MakeFileChannel(inOsFile, outOsFile, readOrWrite) Tcl_Channel Tcl_GetChannel(interp, channelName, modePtr) void Tcl_RegisterChannel(interp, channel) int Tcl_UnregisterChannel(interp, channel) int Tcl_Close(interp, channel) int Tcl_Read(channel, buf, toRead) int Tcl_Gets(channel, lineRead) int Tcl_Write(channel, buf, toWrite) int Tcl_Flush(channel) int Tcl_Seek(channel, offset, seekMode) int Tcl_Tell(channel) int Tcl_GetChannelOption(channel, optionName, optionValue) int Tcl_SetChannelOption(interp, channel, optionName, newValue) int Tcl_Eof(channel) int Tcl_InputBlocked(channel) int Tcl_InputBuffered(channel) ARGUMENTS Tcl_Interp *interp (in) Used for error reporting and to look up a channel registered in it. char *fileName (in) The name of a local or network file. char *mode (in) Specifies how the file is to be accessed. May have any of the values allowed for the mode argument to the Tcl open command. For Tcl_OpenCommandChannel, may be NULL. int permissions (in) POSIX-style permission flags such as 0644. If a new file is created, these permissions will be set on the created file. int argc (in) The number of elements in argv. char **argv (in) Arguments for constructing a command pipeline. These values have the same meaning as the non-switch arguments to the Tcl exec command. int flags (in) Specifies the disposition of the stdio handles in pipeline: OR-ed combination of TCL_STDIN, TCL_STDOUT, TCL_STDERR, and TCL_ENFORCE_MODE. If TCL_STDIN is set, stdin for the first child in the pipe is the pipe channel, otherwise it is the same as the standard input of the invoking process; likewise for TCL_STDOUT and TCL_STDERR. If TCL_ENFORCE_MODE is not set, then the pipe can redirect stdio handles to override the stdio handles for which TCL_STDIN, TCL_STDOUT and TCL_STDERR have been set. If it is set, then such redirections cause an error. ClientData inOsFile (in) Operating system specific handle for input from a file. For Unix this is a file descriptor, for Windows it is a HANDLE, etc. ClientData outOsFile (in) Operating system specific handle for output to a file. int readOrWrite (in) OR-ed combination of TCL_READABLE and TCL_WRITABLE to indicate which of inOsFile and outOsFile contains a valid value. int *modePtr (out) Points at an integer variable that will receive an OR-ed combination of TCL_READABLE and TCL_WRITABLE denoting whether the channel is open for reading and writing. Tcl_Channel channel (in) A Tcl channel for input or output. Must have been the return value from a procedure such as Tcl_OpenFileChannel. char *buf (in) An array of bytes in which to store channel input, or from which to read channel output. int len (in) The length of the input or output. int atEnd (in) If nonzero, store the input at the end of the input queue, otherwise store it at the head of the input queue. int toRead (in) The number of bytes to read from the channel. Tcl_DString *lineRead (in) A pointer to a Tcl dynamic string in which to store the line read from the channel. Must have been initialized by the caller. int toWrite (in) The number of bytes to read from buf and output to the channel. int offset (in) How far to move the access point in the channel at which the next input or output operation will be applied, measured in bytes from the position given by seekMode. May be either positive or negative. int seekMode (in) Relative to which point to seek; used with offset to calculate the new access point for the channel. Legal values are SEEK_SET, SEEK_CUR, and SEEK_END. char *optionName (in) The name of an option applicable to this channel, such as -blocking. May have any of the values accepted by the fconfigure command. Tcl_DString *optionValue (in) Where to store the value of an option or a list of all options and their values. Must have been initialized by the caller. char *newValue (in) New value for the option given by optionName. DESCRIPTION The Tcl channel mechanism provides a device-independent and platform-independent mechanism for performing buffered input and output operations on a variety of file, socket, and device types. The channel mechanism is extensible to new channel types, by providing a low level channel driver for the new type; the channel driver interface is described in the manual entry for Tcl_CreateChannel. The channel mechanism provides a buffering scheme modelled after Unix's standard I/O, and it also allows for nonblocking I/O on channels. The procedures described in this manual entry comprise the C APIs of the generic layer of the channel architecture. For a description of the channel driver architecture and how to implement channel drivers for new types of channels, see the manual entry for Tcl_CreateChannel. TCL_OPENFILECHANNEL Tcl_OpenFileChannel opens a file specified by fileName and returns a channel handle that can be used to perform input and output on the file. This API is modelled after the fopen procedure of the Unix standard I/O library. The syntax and meaning of all arguments is similar to those given in the Tcl open command when opening a file. If an error occurs while opening the channel, Tcl_OpenFileChannel returns NULL and records a POSIX error code that can be retrieved with Tcl_GetErrno. In addition, if interp is non-NULL, Tcl_OpenFileChannel leaves an error message in interp->result after any error. The newly created channel is not registered in the supplied interpreter; to register it, use Tcl_RegisterChannel, described below. If one of the standard channels, stdin, stdout or stderr was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. TCL_OPENCOMMANDCHANNEL Tcl_OpenCommandChannel provides a C-level interface to the functions of the exec and open commands. It creates a sequence of subprocesses specified by the argv and argc arguments and returns a channel that can be used to communicate with these subprocesses. The flags argument indicates what sort of communication will exist with the command pipeline. If the TCL_STDIN flag is set then the standard input for the first subprocess will be tied to the channel: writing to the channel will provide input to the subprocess. If TCL_STDIN is not set, then standard input for the first subprocess will be the same as this application's standard input. If TCL_STDOUT is set then standard output from the last subprocess can be read from the channel; otherwise it goes to this application's standard output. If TCL_STDERR is set, standard error output for all subprocesses is returned to the channel and results in an error when the channel is closed; otherwise it goes to this application's standard error. If TCL_ENFORCE_MODE is not set, then argc and argv can redirect the stdio handles to override TCL_STDIN, TCL_STDOUT, and TCL_STDERR; if it is set, then it is an error for argc and argv to override stdio channels for which TCL_STDIN, TCL_STDOUT, and TCL_STDERR have been set. If an error occurs while opening the channel, Tcl_OpenCommandChannel returns NULL and records a POSIX error code that can be retrieved with Tcl_GetErrno. In addition, Tcl_OpenCommandChannel leaves an error message in interp->result if interp is not NULL. The newly created channel is not registered in the supplied interpreter; to register it, use Tcl_RegisterChannel, described below. If one of the standard channels, stdin, stdout or stderr was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. TCL_MAKEFILECHANNEL Tcl_MakeFileChannel makes a Tcl_Channel from an existing, platform-specific, file handle. The newly created channel is not registered in the supplied interpreter; to register it, use Tcl_RegisterChannel, described below. If one of the standard channels, stdin, stdout or stderr was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. TCL_GETCHANNEL Tcl_GetChannel returns a channel given the channelName used to create it with Tcl_CreateChannel and a pointer to a Tcl interpreter in interp. If a channel by that name is not registered in that interpreter, the procedure returns NULL. If the mode argument is not NULL, it points at an integer variable that will receive an OR-ed combination of TCL_READABLE and TCL_WRITABLE describing whether the channel is open for reading and writing. TCL_REGISTERCHANNEL Tcl_RegisterChannel adds a channel to the set of channels accessible in interp. After this call, Tcl programs executing in that interpreter can refer to the channel in input or output operations using the name given in the call to Tcl_CreateChannel. After this call, the channel becomes the property of the interpreter, and the caller should not call Tcl_Close for the channel; the channel will be closed automatically when it is unregistered from the interpreter. Code executing outside of any Tcl interpreter can call Tcl_RegisterChannel with interp as NULL, to indicate that it wishes to hold a reference to this channel. Subsequently, the channel can be registered in a Tcl interpreter and it will only be closed when the matching number of calls to Tcl_UnregisterChannel have been made. This allows code executing outside of any interpreter to safely hold a reference to a channel that is also registered in a Tcl interpreter. TCL_UNREGISTERCHANNEL Tcl_UnregisterChannel removes a channel from the set of channels accessible in interp. After this call, Tcl programs will no longer be able to use the channel's name to refer to the channel in that interpreter. If this operation removed the last registration of the channel in any interpreter, the channel is also closed and destroyed. Code not associated with a Tcl interpreter can call Tcl_UnregisterChannel with interp as NULL, to indicate to Tcl that it no longer holds a reference to that channel. If this is the last reference to the channel, it will now be closed. TCL_CLOSE Tcl_Close destroys the channel channel, which must denote a currently open channel. The channel should not be registered in any interpreter when Tcl_Close is called. Buffered output is flushed to the channel's output device prior to destroying the channel, and any buffered input is discarded. If this is a blocking channel, the call does not return until all buffered data is successfully sent to the channel's output device. If this is a nonblocking channel and there is buffered output that cannot be written without blocking, the call returns immediately; output is flushed in the background and the channel will be closed once all of the buffered data has been output. In this case errors during flushing are not reported. If the channel was closed successfully, Tcl_Close returns TCL_OK. If an error occurs, Tcl_Close returns TCL_ERROR and records a POSIX error code that can be retrieved with Tcl_GetErrno. If the channel is being closed synchronously and an error occurs during closing of the channel and interp is not NULL, an error message is left in interp->result. Note: it is not safe to call Tcl_Close on a channel that has been registered using Tcl_RegisterChannel; see the documentation for Tcl_RegisterChannel, above, for details. If the channel has ever been given as the chan argument in a call to Tcl_RegisterChannel, you should instead use Tcl_UnregisterChannel, which will internally call Tcl_Close when all calls to Tcl_RegisterChannel have been matched by corresponding calls to Tcl_UnregisterChannel. TCL_READ Tcl_Read consumes up to toRead bytes of data from channel and stores it at buf. The return value of Tcl_Read is the number of characters written at buf. The buffer produced by Tcl_Read is not NULL terminated. Its contents are valid from the zeroth position up to and excluding the position indicated by the return value. If an error occurs, the return value is -1 and Tcl_Read records a POSIX error code that can be retrieved with Tcl_GetErrno. The return value may be smaller than the value of toRead, indicating that less data than requested was available, also called a short read. In blocking mode, this can only happen on an end-of-file. In nonblocking mode, a short read can also occur if there is not enough input currently available: Tcl_Read returns a short count rather than waiting for more data. If the channel is in blocking mode, a return value of zero indicates an end of file condition. If the channel is in nonblocking mode, a return value of zero indicates either that no input is currently available or an end of file condition. Use Tcl_Eof and Tcl_InputBlocked to tell which of these conditions actually occurred. Tcl_Read translates platform-specific end-of-line representations into the canonical \n internal representation according to the current end-of-line recognition mode. End-of-line recognition and the various platform-specific modes are described in the manual entry for the Tcl fconfigure command. TCL_GETS Tcl_Gets reads a line of input from a channel and appends all of the characters of the line except for the terminating end-of-line character(s) to the dynamic string given by dsPtr. The end-of-line character(s) are read and discarded. If a line was successfully read, the return value is greater than or equal to zero, and it indicates the number of characters stored in the dynamic string. If an error occurs, Tcl_Gets returns -1 and records a POSIX error code that can be retrieved with Tcl_GetErrno. Tcl_Gets also returns -1 if the end of the file is reached; the Tcl_Eof procedure can be used to distinguish an error from an end-of-file condition. If the channel is in nonblocking mode, the return value can also be -1 if no data was available or the data that was available did not contain an end-of-line character. When -1 is returned, the Tcl_InputBlocked procedure may be invoked to determine if the channel is blocked because of input unavailability. TCL_WRITE Tcl_Write accepts toWrite bytes of data at buf for output on channel. This data may not appear on the output device immediately. If the data should appear immediately, call Tcl_Flush after the call to Tcl_Write, or set the -buffering option on the channel to none. If you wish the data to appear as soon as an end of line is accepted for output, set the -buffering option on the channel to line mode. The toWrite argument specifies how many bytes of data are provided in the buf argument. If it is negative, Tcl_Write expects the data to be NULL terminated and it outputs everything up to the NULL. The return value of Tcl_Write is a count of how many characters were accepted for output to the channel. This is either equal to toWrite or -1 to indicate that an error occurred. If an error occurs, Tcl_Write also records a POSIX error code that may be retrieved with Tcl_GetErrno. Newline characters in the output data are translated to platform-specific end-of-line sequences according to the -translation option for the channel. TCL_FLUSH Tcl_Flush causes all of the buffered output data for channel to be written to its underlying file or device as soon as possible. If the channel is in blocking mode, the call does not return until all the buffered data has been sent to the channel or some error occurred. The call returns immediately if the channel is nonblocking; it starts a background flush that will write the buffered data to the channel eventually, as fast as the channel is able to absorb it. The return value is normally TCL_OK. If an error occurs, Tcl_Flush returns TCL_ERROR and records a POSIX error code that can be retrieved with Tcl_GetErrno. TCL_SEEK Tcl_Seek moves the access point in channel where subsequent data will be read or written. Buffered output is flushed to the channel and buffered input is discarded, prior to the seek operation. Tcl_Seek normally returns the new access point. If an error occurs, Tcl_Seek returns -1 and records a POSIX error code that can be retrieved with Tcl_GetErrno. After an error, the access point may or may not have been moved. TCL_TELL Tcl_Tell returns the current access point for a channel. The returned value is -1 if the channel does not support seeking. TCL_GETCHANNELOPTION Tcl_GetChannelOption retrieves, in dsPtr, the value of one of the options currently in effect for a channel, or a list of all options and their values. The channel argument identifies the channel for which to query an option or retrieve all options and their values. If optionName is not NULL, it is the name of the option to query; the option's value is copied to the Tcl dynamic string denoted by optionValue. If optionName is NULL, the function stores an alternating list of option names and their values in optionValue, using a series of calls to Tcl_DStringAppendElement. The various preexisting options and their possible values are described in the manual entry for the Tcl fconfigure command. Other options can be added by each channel type. These channel type specific options are described in the manual entry for the Tcl command that creates a channel of that type; for example, the additional options for TCP based channels are described in the manual entry for the Tcl socket command. The procedure normally returns TCL_OK. If an error occurs, it returns TCL_ERROR and calls Tcl_SetErrno to store an appropriate POSIX error code. TCL_SETCHANNELOPTION Tcl_SetChannelOption sets a new value for an option on channel. OptionName is the option to set and newValue is the value to set. The procedure normally returns TCL_OK. If an error occurs, it returns TCL_ERROR; in addition, if interp is non-NULL, Tcl_SetChannelOption leaves an error message in interp->result. TCL_EOF Tcl_Eof returns a nonzero value if channel encountered an end of file during the last input operation. TCL_INPUTBLOCKED Tcl_InputBlocked returns a nonzero value if channel is in nonblocking mode and the last input operation returned less data than requested because there was insufficient data available. The call always returns zero if the channel is in blocking mode. TCL_INPUTBUFFERED Tcl_InputBuffered returns the number of bytes of input currently buffered in the internal buffers for a channel. If the channel is not open for reading, this function always returns zero. SEE ALSO DString(3), fconfigure(n), filename(n), fopen(2), Tcl_CreateChannel(3) KEYWORDS access point, blocking, buffered I/O, channel, channel driver, end of file, flush, input, nonblocking, output, read, seek, write ═══ 2.40. Tcl_OpenTcpClient ═══ NAME Tcl_OpenTcpClient, Tcl_OpenTcpServer - procedures to open channels using TCP sockets SYNOPSIS #include Tcl_Channel Tcl_OpenTcpClient(interp, port, host, myaddr, myport, async) Tcl_Channel Tcl_MakeTcpClientChannel(sock) Tcl_Channel Tcl_OpenTcpServer(interp, port, myaddr, proc, clientData) ARGUMENTS Tcl_Interp *interp (in) Tcl interpreter to use for error reporting. If non-NULL and an error occurs, an error message is left in interp->result. int port (in) A port number to connect to as a client or to listen on as a server. char *host (in) A string specifying a host name or address for the remote end of the connection. int myport (in) A port number for the client's end of the socket. If 0, a port number is allocated at random. char *myaddr (in) A string specifying the host name or address for network interface to use for the local end of the connection. If NULL, a default interface is chosen. int async (in) If nonzero, the client socket is connected asynchronously to the server. ClientData sock (in) Platform-specific handle for client TCP socket. Tcl_TcpAcceptProc *proc (in) Pointer to a procedure to invoke each time a new connection is accepted via the socket. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION These functions are convenience procedures for creating channels that communicate over TCP sockets. The operations on a channel are described in the manual entry for Tcl_OpenFileChannel. TCL_OPENTCPCLIENT Tcl_OpenTcpClient opens a client TCP socket connected to a port on a specific host, and returns a channel that can be used to communicate with the server. The host to connect to can be specified either as a domain name style name (e.g. www.sunlabs.com), or as a string containing the alphanumeric representation of its four-byte address (e.g. 127.0.0.1). Use the string localhost to connect to a TCP socket on the host on which the function is invoked. The myaddr and myport arguments allow a client to specify an address for the local end of the connection. If myaddr is NULL, then an interface is chosen automatically by the operating system. If myport is 0, then a port number is chosen at random by the operating system. If async is zero, the call to Tcl_OpenTcpClient returns only after the client socket has either successfully connected to the server, or the attempted connection has failed. If async is nonzero the socket is connected asynchronously and the returned channel may not yet be connected to the server when the call to Tcl_OpenTcpClient returns. If the channel is in blocking mode and an input or output operation is done on the channel before the connection is completed or fails, that operation will wait until the connection either completes successfully or fails. If the channel is in nonblocking mode, the input or output operation will return immediately and a subsequent call to Tcl_InputBlocked on the channel will return nonzero. The returned channel is opened for reading and writing. If an error occurs in opening the socket, Tcl_OpenTcpClient returns NULL and records a POSIX error code that can be retrieved with Tcl_GetErrno. In addition, if interp is non-NULL, an error message is left in interp->result. The newly created channel is not registered in the supplied interpreter; to register it, use Tcl_RegisterChannel. If one of the standard channels, stdin, stdout or stderr was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. TCL_MAKETCPCLIENTCHANNEL Tcl_MakeTcpClientChannel creates a Tcl_Channel around an existing, platform specific, handle for a client TCP socket. The newly created channel is not registered in the supplied interpreter; to register it, use Tcl_RegisterChannel. If one of the standard channels, stdin, stdout or stderr was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. TCL_OPENTCPSERVER Tcl_OpenTcpServer opens a TCP socket on the local host on a specified port and uses the Tcl event mechanism to accept requests from clients to connect to it. The myaddr argument specifies the network interface. If myaddr is NULL the special address INADDR_ANY should be used to allow connections from any network interface. Each time a client connects to this socket, Tcl creates a channel for the new connection and invokes proc with information about the channel. Proc must match the following prototype: typedef void Tcl_TcpAcceptProc( ClientData clientData, Tcl_Channel channel, char *hostName, int port); The clientData argument will be the same as the clientData argument to Tcl_OpenTcpServer, channel will be the handle for the new channel, hostName points to a string containing the name of the client host making the connection, and port will contain the client's port number. The new channel is opened for both input and output. If proc raises an error, the connection is closed automatically. Proc has no return value, but if it wishes to reject the connection it can close channel. Tcl_OpenTcpServer normally returns a pointer to a channel representing the server socket. If an error occurs, Tcl_OpenTcpServer returns NULL and records a POSIX error code that can be retrieved with Tcl_GetErrno. In addition, if interp->result is non-NULL, an error message is left in interp->result. The channel returned by Tcl_OpenTcpServer cannot be used for either input or output. It is simply a handle for the socket used to accept connections. The caller can close the channel to shut down the server and disallow further connections from new clients. TCP server channels operate correctly only in applications that dispatch events through Tcl_DoOneEvent or through Tcl commands such as vwait; otherwise Tcl will never notice that a connection request from a remote client is pending. The newly created channel is not registered in the supplied interpreter; to register it, use Tcl_RegisterChannel. If one of the standard channels, stdin, stdout or stderr was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. SEE ALSO Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n) KEYWORDS client, server, TCP ═══ 2.41. Tcl_PkgRequire ═══ NAME Tcl_PkgRequire, Tcl_PkgProvide - package version control SYNOPSIS #include char * Tcl_PkgRequire(interp, name, version, exact) int Tcl_PkgProvide(interp, name, version) ARGUMENTS Tcl_Interp *interp (in) Interpreter where package is needed or available. char *name (in) Name of package. char *version (in) A version string consisting of one or more decimal numbers separated by dots. int exact (in) Non-zero means that only the particular version specified by version is acceptable. Zero means that newer versions than version are also acceptable as long as they have the same major version number as version. DESCRIPTION These procedures provide C-level interfaces to Tcl's package and version management facilities. Tcl_PkgRequire is equivalent to the package require command, and Tcl_PkgProvide is equivalent to the package provide command. See the documentation for the Tcl commands for details on what these procedures do. If Tcl_PkgRequire completes successfully it returns a pointer to the version string for the version of the package that is provided in the interpreter (which may be different than version); if an error occurs it returns NULL and leaves an error message in interp->result. Tcl_PkgProvide returns TCL_OK if it completes successfully; if an error occurs it returns TCL_ERROR and leaves an error message in interp->result. KEYWORDS package, provide, require, version ═══ 2.42. Tcl_Preserve ═══ NAME Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree - avoid freeing storage while it's being used SYNOPSIS #include Tcl_Preserve(clientData) Tcl_Release(clientData) Tcl_EventuallyFree(clientData, freeProc) ARGUMENTS ClientData clientData (in) Token describing structure to be freed or reallocated. Usually a pointer to memory for structure. Tcl_FreeProc *freeProc (in) Procedure to invoke to free clientData. DESCRIPTION These three procedures help implement a simple reference count mechanism for managing storage. They are designed to solve a problem having to do with widget deletion, but are also useful in many other situations. When a widget is deleted, its widget record (the structure holding information specific to the widget) must be returned to the storage allocator. However, it's possible that the widget record is in active use by one of the procedures on the stack at the time of the deletion. This can happen, for example, if the command associated with a button widget causes the button to be destroyed: an X event causes an event-handling C procedure in the button to be invoked, which in turn causes the button's associated Tcl command to be executed, which in turn causes the button to be deleted, which in turn causes the button's widget record to be de-allocated. Unfortunately, when the Tcl command returns, the button's event-handling procedure will need to reference the button's widget record. Because of this, the widget record must not be freed as part of the deletion, but must be retained until the event-handling procedure has finished with it. In other situations where the widget is deleted, it may be possible to free the widget record immediately. Tcl_Preserve and Tcl_Release implement short-term reference counts for their clientData argument. The clientData argument identifies an object and usually consists of the address of a structure. The reference counts guarantee that an object will not be freed until each call to Tcl_Preserve for the object has been matched by calls to Tcl_Release. There may be any number of unmatched Tcl_Preserve calls in effect at once. Tcl_EventuallyFree is invoked to free up its clientData argument. It checks to see if there are unmatched Tcl_Preserve calls for the object. If not, then Tcl_EventuallyFree calls freeProc immediately. Otherwise Tcl_EventuallyFree records the fact that clientData needs eventually to be freed. When all calls to Tcl_Preserve have been matched with calls to Tcl_Release then freeProc will be called by Tcl_Release to do the cleanup. All the work of freeing the object is carried out by freeProc. FreeProc must have arguments and result that match the type Tcl_FreeProc: typedef void Tcl_FreeProc(char *blockPtr); The blockPtr argument to freeProc will be the same as the clientData argument to Tcl_EventuallyFree. The type of blockPtr (char *) is different than the type of the clientData argument to Tcl_EventuallyFree for historical reasons, but the value is the same. This mechanism can be used to solve the problem described above by placing Tcl_Preserve and Tcl_Release calls around actions that may cause undesired storage re-allocation. The mechanism is intended only for short-term use (i.e. while procedures are pending on the stack); it will not work efficiently as a mechanism for long-term reference counts. The implementation does not depend in any way on the internal structure of the objects being freed; it keeps the reference counts in a separate structure. KEYWORDS free, reference count, storage ═══ 2.43. Tcl_PrintDouble ═══ NAME Tcl_PrintDouble - Convert floating value to string SYNOPSIS #include Tcl_PrintDouble(interp, value, dst) ARGUMENTS Tcl_Interp *interp (in) Interpreter that controls the conversion. double value (in) Floating-point value to be converted. char *dst (out) Where to store string representing value. Must have at least TCL_DOUBLE_SPACE characters of storage. DESCRIPTION Tcl_PrintDouble generates a string that represents the value of value and stores it in memory at the location given by dst. It uses %g format to generate the string, with two special twists. First, the string is guaranteed to contain either a "." or an "e" so that it doesn't look like an integer (where %g would generate an integer with no decimal point, Tcl_PrintDouble adds ".0"). Second, the number of significant digits printed at dst is controlled by the tcl_precision variable in interp; if tcl_precision is undefined then 6 significant digits are printed. KEYWORDS conversion, double-precision, floating-point, string ═══ 2.44. Tcl_RecordAndEval ═══ NAME Tcl_RecordAndEval - save command on history list before evaluating SYNOPSIS #include int Tcl_RecordAndEval(interp, cmd, eval) ARGUMENTS Tcl_Interp *interp (in) Tcl interpreter in which to evaluate command. char *cmd (in) Command (or sequence of commands) to execute. int flags (in) An OR'ed combination of flag bits. TCL_NO_EVAL means record the command but don't evaluate it. TCL_EVAL_GLOBAL means evaluate the command at global level instead of the current stack level. DESCRIPTION Tcl_RecordAndEval is invoked to record a command as an event on the history list and then execute it using Tcl_Eval (or Tcl_GlobalEval if the TCL_EVAL_GLOBAL bit is set in flags). It returns a completion code such as TCL_OK just like Tcl_Eval and it leaves information in interp->result. If you don't want the command recorded on the history list then you should invoke Tcl_Eval instead of Tcl_RecordAndEval. Normally Tcl_RecordAndEval is only called with top-level commands typed by the user, since the purpose of history is to allow the user to re-issue recently-invoked commands. If the flags argument contains the TCL_NO_EVAL bit then the command is recorded without being evaluated. KEYWORDS command, event, execute, history, interpreter, record ═══ 2.45. Tcl_RegExpMatch ═══ NAME Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange - Pattern matching with regular expressions SYNOPSIS #include int Tcl_RegExpMatch(interp, string, pattern) Tcl_RegExp Tcl_RegExpCompile(interp, pattern) int Tcl_RegExpExec(interp, regexp, string, start) Tcl_RegExpRange(regexp, index, startPtr, endPtr) ARGUMENTS Tcl_Interp *interp (in) Tcl interpreter to use for error reporting. char *string (in) String to check for a match with a regular expression. char *pattern (in) String in the form of a regular expression pattern. Tcl_RegExp regexp (in) Compiled regular expression. Must have been returned previously by Tcl_RegExpCompile. char *start (in) If string is just a portion of some other string, this argument identifies the beginning of the larger string. If it isn't the same as string, then no ^ matches will be allowed. int index (in) Specifies which range is desired: 0 means the range of the entire match, 1 or greater means the range that matched a parenthesized sub-expression. char **startPtr (out) The address of the first character in the range is stored here, or NULL if there is no such range. char **endPtr (out) The address of the character just after the last one in the range is stored here, or NULL if there is no such range. DESCRIPTION Tcl_RegExpMatch determines whether its pattern argument matches regexp, where regexp is interpreted as a regular expression using the same rules as for the regexp Tcl command. If there is a match then Tcl_RegExpMatch returns 1. If there is no match then Tcl_RegExpMatch returns 0. If an error occurs in the matching process (e.g. pattern is not a valid regular expression) then Tcl_RegExpMatch returns -1 and leaves an error message in interp->result. Tcl_RegExpCompile, Tcl_RegExpExec, and Tcl_RegExpRange provide lower-level access to the regular expression pattern matcher. Tcl_RegExpCompile compiles a regular expression string into the internal form used for efficient pattern matching. The return value is a token for this compiled form, which can be used in subsequent calls to Tcl_RegExpExec or Tcl_RegExpRange. If an error occurs while compiling the regular expression then Tcl_RegExpCompile returns NULL and leaves an error message in interp->result. Note: the return value from Tcl_RegExpCompile is only valid up to the next call to Tcl_RegExpCompile; it is not safe to retain these values for long periods of time. Tcl_RegExpExec executes the regular expression pattern matcher. It returns 1 if string contains a range of characters that match regexp, 0 if no match is found, and -1 if an error occurs. In the case of an error, Tcl_RegExpExec leaves an error message in interp->result. When searching a string for multiple matches of a pattern, it is important to distinguish between the start of the original string and the start of the current search. For example, when searching for the second occurrence of a match, the string argument might point to the character just after the first match; however, it is important for the pattern matcher to know that this is not the start of the entire string, so that it doesn't allow ^ atoms in the pattern to match. The start argument provides this information by pointing to the start of the overall string containing string. Start will be less than or equal to string; if it is less than string then no ^ matches will be allowed. Tcl_RegExpRange may be invoked after Tcl_RegExpExec returns; it provides detailed information about what ranges of the string matched what parts of the pattern. Tcl_RegExpRange returns a pair of pointers in *startPtr and *endPtr that identify a range of characters in the source string for the most recent call to Tcl_RegExpExec. Index indicates which of several ranges is desired: if index is 0, information is returned about the overall range of characters that matched the entire pattern; otherwise, information is returned about the range of characters that matched the index'th parenthesized subexpression within the pattern. If there is no range corresponding to index then NULL is stored in *firstPtr and *lastPtr. KEYWORDS match, pattern, regular expression, string, subexpression ═══ 2.46. Tcl_SetErrno ═══ NAME Tcl_SetErrno, Tcl_GetErrno - manipulate errno to store and retrieve error codes SYNOPSIS #include void Tcl_SetErrno(errorCode) int Tcl_GetErrno() ARGUMENTS int errorCode (in) A POSIX error code such as ENOENT. DESCRIPTION Tcl_SetErrno and Tcl_GetErrno provide portable access to the errno variable, which is used to record a POSIX error code after system calls and other operations such as Tcl_Gets. These procedures are necessary because global variable accesses cannot be made across module boundaries on some platforms. Tcl_SetErrno sets the errno variable to the value of the errorCode argument C procedures that wish to return error information to their callers via errno should call Tcl_SetErrno rather than setting errno directly. Tcl_GetErrno returns the current value of errno. Procedures wishing to access errno should call this procedure instead of accessing errno directly. KEYWORDS errno, error code, global variables ═══ 2.47. Tcl_SetRecursionLimit ═══ NAME Tcl_SetRecursionLimit - set maximum allowable nesting depth in interpreter SYNOPSIS #include int Tcl_SetRecursionLimit(interp, depth) ARGUMENTS Tcl_Interp *interp (in) Interpreter whose recursion limit is to be set. Must be greater than zero. int depth (in) New limit for nested calls to Tcl_Eval for interp. DESCRIPTION At any given time Tcl enforces a limit on the number of recursive calls that may be active for Tcl_Eval and related procedures such as Tcl_GlobalEval. Any call to Tcl_Eval that exceeds this depth is aborted with an error. By default the recursion limit is 1000. Tcl_SetRecursionLimit may be used to change the maximum allowable nesting depth for an interpreter. The depth argument specifies a new limit for interp, and Tcl_SetRecursionLimit returns the old limit. To read out the old limit without modifying it, invoke Tcl_SetRecursionDepth with depth equal to 0. The Tcl_SetRecursionLimit only sets the size of the Tcl call stack: 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 Tcl_SetRecursionLimit. If this happens, see if there is a mechanism in your system for increasing the maximum size of the C stack. KEYWORDS nesting depth, recursion ═══ 2.48. Tcl_SetResult ═══ NAME Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult - manipulate Tcl result string SYNOPSIS #include Tcl_SetResult(interp, string, freeProc) Tcl_AppendResult(interp, string, string, ... , (char *) NULL) Tcl_AppendElement(interp, string) Tcl_ResetResult(interp) Tcl_FreeResult(interp) ARGUMENTS Tcl_Interp *interp (out) Interpreter whose result is to be modified. char *string (in) String value to become result for interp or to be appended to existing result. Tcl_FreeProc *freeProc (in) Address of procedure to call to release storage at string, or TCL_STATIC, TCL_DYNAMIC, or TCL_VOLATILE. DESCRIPTION The procedures described here are utilities for setting the result/error string in a Tcl interpreter. Tcl_SetResult arranges for string to be the return string for the current Tcl command in interp, replacing any existing result. If freeProc is TCL_STATIC it means that string refers to an area of static storage that is guaranteed not to be modified until at least the next call to Tcl_Eval. If freeProc is TCL_DYNAMIC it means that string was allocated with a call to Tcl_Alloc and is now the property of the Tcl system. Tcl_SetResult will arrange for the string's storage to be released by calling Tcl_Free when it is no longer needed. If freeProc is TCL_VOLATILE it means that string points to an area of memory that is likely to be overwritten when Tcl_SetResult returns (e.g. it points to something in a stack frame). In this case Tcl_SetResult will make a copy of the string in dynamically allocated storage and arrange for the copy to be the return string for the current Tcl command. If freeProc isn't one of the values TCL_STATIC, TCL_DYNAMIC, and TCL_VOLATILE, then it is the address of a procedure that Tcl should call to free the string. This allows applications to use non-standard storage allocators. When Tcl no longer needs the storage for the string, it will call freeProc. FreeProc should have arguments and result that match the type Tcl_FreeProc: typedef void Tcl_FreeProc(char *blockPtr); When freeProc is called, its blockPtr will be set to the value of string passed to Tcl_SetResult. If string is NULL, then freeProc is ignored and Tcl_SetResult re-initializes interp's result to point to the pre-allocated result area, with an empty string in the result area. If Tcl_SetResult is called at a time when interp holds a result, Tcl_SetResult does whatever is necessary to dispose of the old result (see the Tcl_Interp manual entry for details on this). Tcl_AppendResult makes it easy to build up Tcl results in pieces. It takes each of its string arguments and appends them in order to the current result associated with interp. If the result is in its initialized empty state (e.g. a command procedure was just invoked or Tcl_ResetResult was just called), then Tcl_AppendResult sets the result to the concatenation of its string arguments. Tcl_AppendResult may be called repeatedly as additional pieces of the result are produced. Tcl_AppendResult takes care of all the storage management issues associated with managing interp's result, such as allocating a larger result area if necessary. Any number of string arguments may be passed in a single call; the last argument in the list must be a NULL pointer. Tcl_AppendElement is similar to Tcl_AppendResult in that it allows results to be built up in pieces. However, Tcl_AppendElement takes only a single string argument and it appends that argument to the current result as a proper Tcl list element. Tcl_AppendElement adds backslashes or braces if necessary to ensure that interp's result can be parsed as a list and that string will be extracted as a single element. Under normal conditions, Tcl_AppendElement will add a space character to interp's result just before adding the new list element, so that the list elements in the result are properly separated. However if the new list element is the first in a list or sub-list (i.e. interp's current result is empty, or consists of the single character "{", or ends in the characters " {") then no space is added. Tcl_ResetResult clears the result for interp, freeing the memory associated with it if the current result was dynamically allocated. It leaves the result in its normal initialized state with interp->result pointing to a static buffer containing TCL_RESULT_SIZE characters, of which the first character is zero. Tcl_ResetResult also clears the error state managed by Tcl_AddErrorInfo and Tcl_SetErrorCode. Tcl_FreeResult is a macro that performs part of the work of Tcl_ResetResult. It frees up the memory associated with interp's result and sets interp->freeProc to zero, but it doesn't change interp->result or clear error state. Tcl_FreeResult is most commonly used when a procedure is about to replace one result value with another. SEE ALSO Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp KEYWORDS append, command, element, list, result, return value, interpreter ═══ 2.49. Tcl_SetVar ═══ NAME Tcl_SetVar, Tcl_SetVar2, Tcl_GetVar, Tcl_GetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 - manipulate Tcl variables SYNOPSIS #include char * Tcl_SetVar(interp, varName, newValue, flags) char * Tcl_SetVar2(interp, name1, name2, newValue, flags) char * Tcl_GetVar(interp, varName, flags) char * Tcl_GetVar2(interp, name1, name2, flags) int Tcl_UnsetVar(interp, varName, flags) int Tcl_UnsetVar2(interp, name1, name2, flags) ARGUMENTS Tcl_Interp *interp (in) Interpreter containing variable. char *varName (in) Name of variable. May refer to a scalar variable or an element of an array variable. If the name references an element of an array, then it must be in writable memory: Tcl will make temporary modifications to it while looking up the name. char *newValue (in) New value for variable. int flags (in) OR-ed combination of bits providing additional information for operation. See below for valid values. char *name1 (in) Name of scalar variable, or name of array variable if name2 is non-NULL. char *name2 (in) If non-NULL, gives name of element within array and name1 must refer to an array variable. DESCRIPTION These procedures may be used to create, modify, read, and delete Tcl variables from C code. Tcl_SetVar and Tcl_SetVar2 will create a new variable or modify an existing one. Both of these procedures set the given variable to the value given by newValue, and they return a pointer to a copy of the variable's new value, which is stored in Tcl's variable structure. Tcl keeps a private copy of the variable's value, so the caller may change newValue after these procedures return without affecting the value of the variable. If an error occurs in setting the variable (e.g. an array variable is referenced without giving an index into the array), then NULL is returned. The name of the variable may be specified in either of two ways. If Tcl_SetVar is called, the variable name is given as a single string, varName. If varName contains an open parenthesis and ends with a close parenthesis, then the value between the parentheses is treated as an index (which can have any string value) and the characters before the first open parenthesis are treated as the name of an array variable. If varName doesn't have parentheses as described above, then the entire string is treated as the name of a scalar variable. If Tcl_SetVar2 is called, then the array name and index have been separated by the caller into two separate strings, name1 and name2 respectively; if name2 is zero it means that a scalar variable is being referenced. The flags argument may be used to specify any of several options to the procedures. It consists of an OR-ed combination of any of the following bits: TCL_GLOBAL_ONLY Under normal circumstances the procedures look up variables at the current level of procedure call for interp, or at global level if there is no call active. However, if this bit is set in flags then the variable is looked up at global level even if there is a procedure call active. TCL_LEAVE_ERR_MSG If an error is returned and this bit is set in flags, then an error message will be left in interp->result. If this flag bit isn't set then no error message is left (interp->result will not be modified). TCL_APPEND_VALUE If this bit is set then newValue is appended to the current value, instead of replacing it. If the variable is currently undefined, then this bit is ignored. TCL_LIST_ELEMENT If this bit is set, then newValue is converted to a valid Tcl list element before setting (or appending to) the variable. A separator space is appended before the new list element unless the list element is going to be the first element in a list or sublist (i.e. the variable's current value is empty, or contains the single character "{", or ends in " }"). Tcl_GetVar and Tcl_GetVar2 return the current value of a variable. The arguments to these procedures are treated in the same way as the arguments to Tcl_SetVar and Tcl_SetVar2. Under normal circumstances, the return value is a pointer to the variable's value (which is stored in Tcl's variable structure and will not change before the next call to Tcl_SetVar or Tcl_SetVar2). The only bits of flags that are used are TCL_GLOBAL_ONLY and TCL_LEAVE_ERR_MSG, both of which have the same meaning as for Tcl_SetVar. If an error occurs in reading the variable (e.g. the variable doesn't exist or an array element is specified for a scalar variable), then NULL is returned. Tcl_UnsetVar and Tcl_UnsetVar2 may be used to remove a variable, so that future calls to Tcl_GetVar or Tcl_GetVar2 for the variable will return an error. The arguments to these procedures are treated in the same way as the arguments to Tcl_GetVar and Tcl_GetVar2. If the variable is successfully removed then TCL_OK is returned. If the variable cannot be removed because it doesn't exist then TCL_ERROR is returned. If an array element is specified, the given element is removed but the array remains. If an array name is specified without an index, then the entire array is removed. SEE ALSO Tcl_TraceVar KEYWORDS array, interpreter, scalar, set, unset, variable ═══ 2.50. Tcl_Sleep ═══ NAME Tcl_Sleep - delay execution for a given number of milliseconds SYNOPSIS #include Tcl_Sleep(ms) ARGUMENTS int ms (in) Number of milliseconds to sleep. DESCRIPTION This procedure delays the calling process by the number of milliseconds given by the ms parameter and returns after that time has elapsed. It is typically used for things like flashing a button, where the delay is short and the application needn't do anything while it waits. For longer delays where the application needs to respond to other events during the delay, the procedure Tcl_CreateTimerHandler should be used instead of Tcl_Sleep. KEYWORDS sleep, time, wait ═══ 2.51. Tcl_SplitList ═══ NAME Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement - manipulate Tcl lists SYNOPSIS #include int Tcl_SplitList(interp, list, argcPtr, argvPtr) char * Tcl_Merge(argc, argv) int Tcl_ScanElement(src, flagsPtr) int Tcl_ConvertElement(src, dst, flags) ARGUMENTS Tcl_Interp *interp (out) Interpreter to use for error reporting. If NULL, then no error message is left. char *list (in) Pointer to a string with proper list structure. int *argcPtr (out) Filled in with number of elements in list. char ***argvPtr (out) *argvPtr will be filled in with the address of an array of pointers to the strings that are the extracted elements of list. There will be *argcPtr valid entries in the array, followed by a NULL entry. int argc (in) Number of elements in argv. char **argv (in) Array of strings to merge together into a single list. Each string will become a separate element of the list. char *src (in) String that is to become an element of a list. int *flagsPtr (in) Pointer to word to fill in with information about src. The value of *flagsPtr must be passed to Tcl_ConvertElement. char *dst (in) Place to copy converted list element. Must contain enough characters to hold converted string. int flags (in) Information about src. Must be value returned by previous call to Tcl_ScanElement, possibly OR-ed with TCL_DONT_USE_BRACES. DESCRIPTION These procedures may be used to disassemble and reassemble Tcl lists. Tcl_SplitList breaks a list up into its constituent elements, returning an array of pointers to the elements using argcPtr and argvPtr. While extracting the arguments, Tcl_SplitList obeys the usual rules for backslash substitutions and braces. The area of memory pointed to by *argvPtr is dynamically allocated; in addition to the array of pointers, it also holds copies of all the list elements. It is the caller's responsibility to free up all of this storage. For example, suppose that you have called Tcl_SplitList with the following code: int argc, code; char *string; char **argv; ... code = Tcl_SplitList(interp, string, &argc, &argv); Then you should eventually free the storage with a call like the following: Tcl_Free((char *) argv); Tcl_SplitList normally returns TCL_OK, which means the list was successfully parsed. If there was a syntax error in list, then TCL_ERROR is returned and interp->result will point to an error message describing the problem (if interp was not NULL). If TCL_ERROR is returned then no memory is allocated and *argvPtr is not modified. Tcl_Merge is the inverse of Tcl_SplitList: it takes a collection of strings given by argc and argv and generates a result string that has proper list structure. This means that commands like index may be used to extract the original elements again. In addition, if the result of Tcl_Merge is passed to Tcl_Eval, it will be parsed into argc words whose values will be the same as the argv strings passed to Tcl_Merge. Tcl_Merge will modify the list elements with braces and/or backslashes in order to produce proper Tcl list structure. The result string is dynamically allocated using Tcl_Alloc; the caller must eventually release the space using Tcl_Free. If the result of Tcl_Merge is passed to Tcl_SplitList, the elements returned by Tcl_SplitList will be identical to those passed into Tcl_Merge. However, the converse is not true: if Tcl_SplitList is passed a given string, and the resulting argc and argv are passed to Tcl_Merge, the resulting string may not be the same as the original string passed to Tcl_SplitList. This is because Tcl_Merge may use backslashes and braces differently than the original string. Tcl_ScanElement and Tcl_ConvertElement are the procedures that do all of the real work of Tcl_Merge. Tcl_ScanElement scans its src argument and determines how to use backslashes and braces when converting it to a list element. It returns an overestimate of the number of characters required to represent src as a list element, and it stores information in *flagsPtr that is needed by Tcl_ConvertElement. Tcl_ConvertElement is a companion procedure to Tcl_ScanElement. It does the actual work of converting a string to a list element. Its flags argument must be the same as the value returned by Tcl_ScanElement. Tcl_ConvertElement writes a proper list element to memory starting at *dst and returns a count of the total number of characters written, which will be no more than the result returned by Tcl_ScanElement. Tcl_ConvertElement writes out only the actual list element without any leading or trailing spaces: it is up to the caller to include spaces between adjacent list elements. Tcl_ConvertElement uses one of two different approaches to handle the special characters in src. Wherever possible, it handles special characters by surrounding the string with braces. This produces clean-looking output, but can't be used in some situations, such as when src contains unmatched braces. In these situations, Tcl_ConvertElement handles special characters by generating backslash sequences for them. The caller may insist on the second approach by OR-ing the flag value returned by Tcl_ScanElement with TCL_DONT_USE_BRACES. Although this will produce an uglier result, it is useful in some special situations, such as when Tcl_ConvertElement is being used to generate a portion of an argument for a Tcl command. In this case, surrounding src with curly braces would cause the command not to be parsed correctly. KEYWORDS backslash, convert, element, list, merge, split, strings ═══ 2.52. Tcl_SplitPath ═══ NAME Tcl_SplitPath, Tcl_JoinPath, Tcl_GetPathType - manipulate platform-dependent file paths SYNOPSIS #include Tcl_SplitPath(path, argcPtr, argvPtr) char * Tcl_JoinPath(argc, argv, resultPtr) Tcl_PathType Tcl_GetPathType(path) ARGUMENTS char *path (in) File path in a form appropriate for the current platform (see the filename manual entry for acceptable forms for path names). int *argcPtr (out) Filled in with number of path elements in path. char ***argvPtr (out) *argvPtr will be filled in with the address of an array of pointers to the strings that are the extracted elements of path. There will be *argcPtr valid entries in the array, followed by a NULL entry. int argc (in) Number of elements in argv. char **argv (in) Array of path elements to merge together into a single path. Tcl_DString *resultPtr (in/out) A pointer to an initialized Tcl_DString to which the result of Tcl_JoinPath will be appended. DESCRIPTION These procedures may be used to disassemble and reassemble file paths in a platform independent manner: they provide C-level access to the same functionality as the file split, file join, and file pathtype commands. Tcl_SplitPath breaks a path into its constituent elements, returning an array of pointers to the elements using argcPtr and argvPtr. The area of memory pointed to by *argvPtr is dynamically allocated; in addition to the array of pointers, it also holds copies of all the path elements. It is the caller's responsibility to free all of this storage. For example, suppose that you have called Tcl_SplitPath with the following code: int argc; char *path; char **argv; ... Tcl_SplitPath(string, &argc, &argv); Then you should eventually free the storage with a call like the following: Tcl_Free((char *) argv); Tcl_JoinPath is the inverse of Tcl_SplitPath: it takes a collection of path elements given by argc and argv and generates a result string that is a properly constructed path. The result string is appended to resultPtr. ResultPtr must refer to an initialized Tcl_DString. If the result of Tcl_SplitPath is passed to Tcl_JoinPath, the result will refer to the same location, but may not be in the same form. This is because Tcl_SplitPath and Tcl_JoinPath eliminate duplicate path separators and return a normalized form for each platform. Tcl_GetPathType returns the type of the specified path, where Tcl_PathType is one of TCL_PATH_ABSOLUTE, TCL_PATH_RELATIVE, or TCL_PATH_VOLUME_RELATIVE. See the filename manual entry for a description of the path types for each platform. KEYWORDS file, filename, join, path, split, type ═══ 2.53. Tcl_StaticPackage ═══ NAME Tcl_StaticPackage - make a statically linked package available via the load command SYNOPSIS #include Tcl_StaticPackage(interp, pkgName, initProc, safeInitProc) ARGUMENTS Tcl_Interp *interp (in) If not NULL, points to an interpreter into which the package has already been loaded (i.e., the caller has already invoked the appropriate initialization procedure). NULL means the package hasn't yet been incorporated into any interpreter. char *pkgName (in) Name of the package; should be properly capitalized (first letter upper-case, all others lower-case). Tcl_PackageInitProc *initProc (in) Procedure to invoke to incorporate this package into a trusted interpreter. Tcl_PackageInitProc *safeInitProc (in) Procedure to call to incorporate this package into a safe interpreter (one that will execute untrusted scripts). NULL means the package can't be used in safe interpreters. DESCRIPTION This procedure may be invoked to announce that a package has been linked statically with a Tcl application and, optionally, that it has already been loaded into an interpreter. Once Tcl_StaticPackage has been invoked for a package, it may be loaded into interpreters using the load command. Tcl_StaticPackage is normally invoked only by the Tcl_AppInit procedure for the application, not by packages for themselves (Tcl_StaticPackage should only be invoked for statically loaded packages, and code in the package itself should not need to know whether the package is dynamically or statically loaded). When the load command is used later to load the package into an interpreter, one of initProc and safeInitProc will be invoked, depending on whether the target interpreter is safe or not. initProc and safeInitProc must both match the following prototype: typedef int Tcl_PackageInitProc(Tcl_Interp *interp); The interp argument identifies the interpreter in which the package is to be loaded. The initialization procedure must return TCL_OK or TCL_ERROR to indicate whether or not it completed successfully; in the event of an error it should set interp->result to point to an error message. The result or error from the initialization procedure will be returned as the result of the load command that caused the initialization procedure to be invoked. KEYWORDS initialization procedure, package, static linking ═══ 2.54. Tcl_StringMatch ═══ NAME Tcl_StringMatch - test whether a string matches a pattern SYNOPSIS #include int Tcl_StringMatch(string, pattern) ARGUMENTS char *string (in) String to test. char *pattern (in) Pattern to match against string. May contain special characters from the set *?\[]. DESCRIPTION This utility procedure determines whether a string matches a given pattern. If it does, then Tcl_StringMatch returns 1. Otherwise Tcl_StringMatch returns 0. The algorithm used for matching is the same algorithm used in the "string match" Tcl command and is similar to the algorithm used by the C-shell for file name matching; see the Tcl manual entry for details. KEYWORDS match, pattern, string ═══ 2.55. Tcl_Main ═══ NAME Tcl_Main - main program for Tcl-based applications SYNOPSIS #include Tcl_Main(argc, argv, appInitProc) ARGUMENTS int argc (in) Number of elements in argv. char *argv[] (in) Array of strings containing command-line arguments. Tcl_AppInitProc *appInitProc (in) Address of an application-specific initialization procedure. The value for this argument is usually Tcl_AppInit. DESCRIPTION Tcl_Main acts as the main program for most Tcl-based applications. Starting with Tcl 7.4 it is not called main anymore because it is part of the Tcl library and having a function main in a library (particularly a shared library) causes problems on many systems. Having main in the Tcl library would also make it hard to use Tcl in C++ programs, since C++ programs must have special C++ main functions. Normally each application contains a small main function that does nothing but invoke Tcl_Main. Tcl_Main then does all the work of creating and running a tclsh-like application. When it is has finished its own initialization, but before it processes commands, Tcl_Main calls the procedure given by the appInitProc argument. This procedure provides a "hook" for the application to perform its own initialization, such as defining application-specific commands. The procedure must have an interface that matches the type Tcl_AppInitProc: typedef int Tcl_AppInitProc(Tcl_Interp *interp); AppInitProc is almost always a pointer to Tcl_AppInit; for more details on this procedure, see the documentation for Tcl_AppInit. KEYWORDS application-specific initialization, command-line arguments, main program ═══ 2.56. Tcl_TraceVar ═══ NAME Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 - monitor accesses to a variable SYNOPSIS #include int Tcl_TraceVar(interp, varName, flags, proc, clientData) int Tcl_TraceVar2(interp, name1, name2, flags, proc, clientData) Tcl_UntraceVar(interp, varName, flags, proc, clientData) Tcl_UntraceVar2(interp, name1, name2, flags, proc, clientData) ClientData Tcl_VarTraceInfo(interp, varName, flags, proc, prevClientData) ClientData Tcl_VarTraceInfo2(interp, name1, name2, flags, proc, prevClientData) ARGUMENTS Tcl_Interp *interp (in) Interpreter containing variable. char *varName (in) Name of variable. May refer to a scalar variable, to an array variable with no index, or to an array variable with a parenthesized index. If the name references an element of an array, then it must be in writable memory: Tcl will make temporary modifications to it while looking up the name. int flags (in) OR-ed combination of the values TCL_TRACE_READS, TCL_TRACE_WRITES, and TCL_TRACE_UNSETS, and TCL_GLOBAL_ONLY. Not all flags are used by all procedures. See below for more information. Tcl_VarTraceProc *proc (in) Procedure to invoke whenever one of the traced operations occurs. ClientData clientData (in) Arbitrary one-word value to pass to proc. char *name1 (in) Name of scalar or array variable (without array index). char *name2 (in) For a trace on an element of an array, gives the index of the element. For traces on scalar variables or on whole arrays, is NULL. ClientData prevClientData (in) If non-NULL, gives last value returned by Tcl_VarTraceInfo or Tcl_VarTraceInfo2, so this call will return information about next trace. If NULL, this call will return information about first trace. DESCRIPTION Tcl_TraceVar allows a C procedure to monitor and control access to a Tcl variable, so that the C procedure is invoked whenever the variable is read or written or unset. If the trace is created successfully then Tcl_TraceVar returns TCL_OK. If an error occurred (e.g. varName specifies an element of an array, but the actual variable isn't an array) then TCL_ERROR is returned and an error message is left in interp->result. The flags argument to Tcl_TraceVar indicates when the trace procedure is to be invoked and provides information for setting up the trace. It consists of an OR-ed combination of any of the following values: TCL_GLOBAL_ONLY Normally, the variable will be looked up at the current level of procedure call; if this bit is set then the variable will be looked up at global level, ignoring any active procedures. TCL_TRACE_READS Invoke proc whenever an attempt is made to read the variable. TCL_TRACE_WRITES Invoke proc whenever an attempt is made to modify the variable. TCL_TRACE_UNSETS Invoke proc whenever the variable is unset. A variable may be unset either explicitly by an unset command, or implicitly when a procedure returns (its local variables are automatically unset) or when the interpreter is deleted (all variables are automatically unset). Whenever one of the specified operations occurs on the variable, proc will be invoked. It should have arguments and result that match the type Tcl_VarTraceProc: typedef char *Tcl_VarTraceProc( ClientData clientData, Tcl_Interp *interp, char *name1, char *name2, int flags); The clientData and interp parameters will have the same values as those passed to Tcl_TraceVar when the trace was created. ClientData typically points to an application-specific data structure that describes what to do when proc is invoked. Name1 and name2 give the name of the traced variable in the normal two-part form (see the description of Tcl_TraceVar2 below for details). Flags is an OR-ed combination of bits providing several pieces of information. One of the bits TCL_TRACE_READS, TCL_TRACE_WRITES, or TCL_TRACE_UNSETS will be set in flags to indicate which operation is being performed on the variable. The bit TCL_GLOBAL_ONLY will be set whenever the variable being accessed is a global one not accessible from the current level of procedure call: the trace procedure will need to pass this flag back to variable-related procedures like Tcl_GetVar if it attempts to access the variable. The bit TCL_TRACE_DESTROYED will be set in flags if the trace is about to be destroyed; this information may be useful to proc so that it can clean up its own internal data structures (see the section TCL_TRACE_DESTROYED below for more details). Lastly, the bit TCL_INTERP_DESTROYED will be set if the entire interpreter is being destroyed. When this bit is set, proc must be especially careful in the things it does (see the section TCL_INTERP_DESTROYED below). The trace procedure's return value should normally be NULL; see ERROR RETURNS below for information on other possibilities. Tcl_UntraceVar may be used to remove a trace. If the variable specified by interp, varName, and flags has a trace set with flags, proc, and clientData, then the corresponding trace is removed. If no such trace exists, then the call to Tcl_UntraceVar has no effect. The same bits are valid for flags as for calls to Tcl_TraceVar. Tcl_VarTraceInfo may be used to retrieve information about traces set on a given variable. The return value from Tcl_VarTraceInfo is the clientData associated with a particular trace. The trace must be on the variable specified by the interp, varName, and flags arguments (only the TCL_GLOBAL_ONLY bit from flags is used; other bits are ignored) and its trace procedure must the same as the proc argument. If the prevClientData argument is NULL then the return value corresponds to the first (most recently created) matching trace, or NULL if there are no matching traces. If the prevClientData argument isn't NULL, then it should be the return value from a previous call to Tcl_VarTraceInfo. In this case, the new return value will correspond to the next matching trace after the one whose clientData matches prevClientData, or NULL if no trace matches prevClientData or if there are no more matching traces after it. This mechanism makes it possible to step through all of the traces for a given variable that have the same proc. TWO-PART NAMES The procedures Tcl_TraceVar2, Tcl_UntraceVar2, and Tcl_VarTraceInfo2 are identical to Tcl_TraceVar, Tcl_UntraceVar, and Tcl_VarTraceInfo, respectively, except that the name of the variable has already been separated by the caller into two parts. Name1 gives the name of a scalar variable or array, and name2 gives the name of an element within an array. If name2 is NULL it means that either the variable is a scalar or the trace is to be set on the entire array rather than an individual element (see WHOLE-ARRAY TRACES below for more information). ACCESSING VARIABLES DURING TRACES During read and write traces, the trace procedure can read, write, or unset the traced variable using Tcl_GetVar2, Tcl_SetVar2, and other procedures. While proc is executing, traces are temporarily disabled for the variable, so that calls to Tcl_GetVar2 and Tcl_SetVar2 will not cause proc or other trace procedures to be invoked again. Disabling only occurs for the variable whose trace procedure is active; accesses to other variables will still be traced. However, if a variable is unset during a read or write trace then unset traces will be invoked. During unset traces the variable has already been completely expunged. It is possible for the trace procedure to read or write the variable, but this will be a new version of the variable. Traces are not disabled during unset traces as they are for read and write traces, but existing traces have been removed from the variable before any trace procedures are invoked. If new traces are set by unset trace procedures, these traces will be invoked on accesses to the variable by the trace procedures. CALLBACK TIMING When read tracing has been specified for a variable, the trace procedure will be invoked whenever the variable's value is read. This includes set Tcl commands, $-notation in Tcl commands, and invocations of the Tcl_GetVar and Tcl_GetVar2 procedures. Proc is invoked just before the variable's value is returned. It may modify the value of the variable to affect what is returned by the traced access. If it unsets the variable then the access will return an error just as if the variable never existed. When write tracing has been specified for a variable, the trace procedure will be invoked whenever the variable's value is modified. This includes set commands, commands that modify variables as side effects (such as catch and scan), and calls to the Tcl_SetVar and Tcl_SetVar2 procedures). Proc will be invoked after the variable's value has been modified, but before the new value of the variable has been returned. It may modify the value of the variable to override the change and to determine the value actually returned by the traced access. If it deletes the variable then the traced access will return an empty string. When unset tracing has been specified, the trace procedure will be invoked whenever the variable is destroyed. The traces will be called after the variable has been completely unset. WHOLE-ARRAY TRACES If a call to Tcl_TraceVar or Tcl_TraceVar2 specifies the name of an array variable without an index into the array, then the trace will be set on the array as a whole. This means that proc will be invoked whenever any element of the array is accessed in the ways specified by flags. When an array is unset, a whole-array trace will be invoked just once, with name1 equal to the name of the array and name2 NULL; it will not be invoked once for each element. MULTIPLE TRACES It is possible for multiple traces to exist on the same variable. When this happens, all of the trace procedures will be invoked on each access, in order from most-recently-created to least-recently-created. When there exist whole-array traces for an array as well as traces on individual elements, the whole-array traces are invoked before the individual-element traces. If a read or write trace unsets the variable then all of the unset traces will be invoked but the remainder of the read and write traces will be skipped. ERROR RETURNS Under normal conditions trace procedures should return NULL, indicating successful completion. If proc returns a non-NULL value it signifies that an error occurred. The return value must be a pointer to a static character string containing an error message. If a trace procedure returns an error, no further traces are invoked for the access and the traced access aborts with the given message. Trace procedures can use this facility to make variables read-only, for example (but note that the value of the variable will already have been modified before the trace procedure is called, so the trace procedure will have to restore the correct value). The return value from proc is only used during read and write tracing. During unset traces, the return value is ignored and all relevant trace procedures will always be invoked. RESTRICTIONS A trace procedure can be called at any time, even when there is a partially-formed result in the interpreter's result area. If the trace procedure does anything that could damage this result (such as calling Tcl_Eval) then it must save the original values of the interpreter's result and freeProc fields and restore them before it returns. UNDEFINED VARIABLES It is legal to set a trace on an undefined variable. The variable will still appear to be undefined until the first time its value is set. If an undefined variable is traced and then unset, the unset will fail with an error ("no such variable"), but the trace procedure will still be invoked. TCL_TRACE_DESTROYED FLAG In an unset callback to proc, the TCL_TRACE_DESTROYED bit is set in flags if the trace is being removed as part of the deletion. Traces on a variable are always removed whenever the variable is deleted; the only time TCL_TRACE_DESTROYED isn't set is for a whole-array trace invoked when only a single element of an array is unset. TCL_INTERP_DESTROYED When an interpreter is destroyed, unset traces are called for all of its variables. The TCL_INTERP_DESTROYED bit will be set in the flags argument passed to the trace procedures. Trace procedures must be extremely careful in what they do if the TCL_INTERP_DESTROYED bit is set. It is not safe for the procedures to invoke any Tcl procedures on the interpreter, since its state is partially deleted. All that trace procedures should do under these circumstances is to clean up and free their own internal data structures. BUGS Tcl doesn't do any error checking to prevent trace procedures from misusing the interpreter during traces with TCL_INTERP_DESTROYED set. KEYWORDS clientData, trace, variable ═══ 2.57. Tcl_TranslateFileName ═══ NAME Tcl_TranslateFileName - convert file name to native form and replace tilde with home directory SYNOPSIS #include char * Tcl_TranslateFileName(interp, name, bufferPtr) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to report an error, if any. char *name (in) File name, which may start with a "~". Tcl_DString *bufferPtr (in/out) If needed, this dynamic string is used to store the new file name. At the time of the call it should be uninitialized or empty. The caller must eventually call Tcl_DStringFree to free up anything stored here. DESCRIPTION This utility procedure translates a file name to a form suitable for passing to the local operating system. It converts network names into native form and does tilde substitution. If Tcl_TranslateFileName has to do tilde substitution or translate the name then it uses the dynamic string at *bufferPtr to hold the new string it generates. After Tcl_TranslateFileName returns a non-NULL result, the caller must eventually invoke Tcl_DStringFree to free any information placed in *bufferPtr. The caller need not know whether or not Tcl_TranslateFileName actually used the string; Tcl_TranslateFileName initializes *bufferPtr even if it doesn't use it, so the call to Tcl_DStringFree will be safe in either case. If an error occurs (e.g. because there was no user by the given name) then NULL is returned and an error message will be left at interp->result. When an error occurs, Tcl_TranslateFileName frees the dynamic string itself so that the caller need not call Tcl_DStringFree. The caller is responsible for making sure that interp->result has its default empty value when Tcl_TranslateFileName is invoked. SEE ALSO filename KEYWORDS file name, home directory, tilde, translate, user ═══ 2.58. Tcl_UpVar ═══ NAME Tcl_UpVar, Tcl_UpVar2 - link one variable to another SYNOPSIS #include int Tcl_UpVar(interp, frameName, sourceName, destName, flags) int Tcl_UpVar2(interp, frameName, name1, name2, destName, flags) ARGUMENTS Tcl_Interp *interp (in) Interpreter containing variables; also used for error reporting. char *frameName (in) Identifies the stack frame containing source variable. May have any of the forms accepted by the upvar command, such as #0 or 1. char *sourceName (in) Name of source variable, in the frame given by frameName. May refer to a scalar variable or to an array variable with a parenthesized index. char *destName (in) Name of destination variable, which is to be linked to source variable so that references to destName refer to the other variable. Must not currently exist except as an upvar-ed variable. int flags (in) Either TCL_GLOBAL_ONLY or 0; if non-zero, then destName is a global variable; otherwise it is a local to the current procedure (or global if no procedure is active). char *name1 (in) First part of source variable's name (scalar name, or name of array without array index). char *name2 (in) If source variable is an element of an array, gives the index of the element. For scalar source variables, is NULL. DESCRIPTION Tcl_UpVar and Tcl_UpVar2 provide the same functionality as the upvar command: they make a link from a source variable to a destination variable, so that references to the destination are passed transparently through to the source. The name of the source variable may be specified either as a single string such as xyx or a(24) (by calling Tcl_UpVar) or in two parts where the array name has been separated from the element name (by calling Tcl_UpVar2). The destination variable name is specified in a single string; it may not be an array element. Both procedures return either TCL_OK or TCL_ERROR, and they leave an error message in interp->result if an error occurs. As with the upvar command, the source variable need not exist; if it does exist, unsetting it later does not destroy the link. The destination variable may exist at the time of the call, but if so it must exist as a linked variable. KEYWORDS linked variable, upvar, variable ═══ 3. Tcl Built-In Commands ═══ ═══ 3.1. Tcl ═══ NAME Tcl - Summary of Tcl language syntax. DESCRIPTION The following rules define the syntax and semantics of the Tcl language: 1. 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. 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. 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 of a command are separated by white space (except for newlines, which are command separators). 4. 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. If the first character of a word is an open brace ("{") 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. 6. 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. 7. If a word contains a dollar-sign ("$") 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 terminated by any character that isn't a letter, digit, or underscore. $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, and underscores. Command substitutions, variable substitutions, and backslash substitutions are performed on the characters of index. ${name} Name is the name of a scalar variable. It may contain any characters whatsoever except for close braces. There may be any number of variable substitutions in a single word. Variable substitution is not performed on words enclosed in braces. 8. 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) (0x7). \b Backspace (0x8). \f Form feed (0xc). \n Newline (0xa). \ r Carriage-return (0xd). \t Tab (0x9). \v Vertical tab (0xb). \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 isn't in braces or quotes. \\ Backslash ("\"). \ooo The digits ooo (one, two, or three of them) give the octal value of the character. \xhh The hexadecimal digits hh give the hexadecimal value of the character. Any number of digits may be present. Backslash substitution is not performed on words enclosed in braces, except for backslash-newline as described above. 9. 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. 10. 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. 11. Substitutions do not affect the word boundaries of a command. 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. ═══ 3.2. after ═══ 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 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 bgerror mechanism is used to report the error. 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 command). If there is a pending command that matches the string, it is cancelled 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 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 bgerror mechanism is used to report the error. 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 cancelled. 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, the event loop can be entered with the vwait and update commands. SEE ALSO bgerror KEYWORDS cancel, delay, idle callback, sleep, time ═══ 3.3. 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 doesn't exist, it is given a value equal to the concatenation of all the value arguments. 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. KEYWORDS append, variable ═══ 3.4. array ═══ 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 won't 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 glob-style matching rules of string match) are included. If arrayName isn't the name of an array variable, or if the array contains no elements, then an empty list is returned. array names arrayName ?pattern? Returns a list containing the names of all of the elements in the array that match pattern (using the glob-style matching rules of string match). 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 isn't 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. array size arrayName Returns a decimal string giving the number of elements in the array. If arrayName isn't 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. KEYWORDS array, element names, search ═══ 3.5. bgerror ═══ NAME bgerror - Command invoked to process background errors SYNOPSIS bgerror message DESCRIPTION The bgerror command doesn't 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 didn't originate with the application. For example, if an error occurs while executing a command specified with the after 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 the bgerror command later as an idle event handler. Before invoking bgerror, Tcl restores the errorInfo and errorCode 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. Tcl has no default implementation for bgerror. However, in applications using Tk there will be a default bgerror procedure that posts a dialog box containing the error message and offers the user a chance to see a stack trace showing where the error occurred. KEYWORDS background error, reporting ═══ 3.6. break ═══ NAME break - Abort looping command SYNOPSIS break DESCRIPTION This command is typically invoked inside the body of a looping command such as for or foreach or while. It returns a TCL_BREAK 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 command, Tk event bindings, and the outermost scripts of procedure bodies. KEYWORDS abort, break, loop ═══ 3.7. case ═══ NAME case - Evaluate one of several scripts, depending on a given value SYNOPSIS case string ?in? patList body ?patList body ...? case string ?in? {patList body ?patList body ...?} DESCRIPTION Note: the case command is obsolete and is supported only for backward compatibility. At some point in the future it may be removed entirely. You should use the switch command instead. The case command matches string against each of the patList arguments in order. Each patList argument is a list of one or more patterns. If any of these patterns matches string then case evaluates the following body argument by passing it recursively to the Tcl interpreter and returns the result of that evaluation. Each patList argument consists of a single pattern or list of patterns. Each pattern may contain any of the wild-cards described under string match. If a patList argument is default, the corresponding body will be evaluated if no patList matches string. If no patList argument matches string and no default is given, then the case command returns an empty string. Two syntaxes are provided for the patList 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 case commands, since the braces around the whole list make it unnecessary to include a backslash at the end of each line. Since the patList 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. KEYWORDS case, match, regular expression ═══ 3.8. catch ═══ NAME catch - Evaluate script and trap exceptional returns SYNOPSIS catch script ?varName? DESCRIPTION The catch command may be used to prevent errors from aborting command interpretation. Catch calls the Tcl interpreter recursively to execute script, and always returns a TCL_OK code, regardless of any errors that might occur while executing script. The return value from catch is a decimal string giving the code returned by the Tcl interpreter after executing script. This will be 0 (TCL_OK) if there were no errors in script; otherwise it will have a non-zero value corresponding to one of the exceptional return codes (see tcl.h for the definitions of code values). If the varName argument is given, then it gives the name of a variable; catch will set the variable to the string returned from script (either a result or an error message). Note that catch catches all exceptions, including those generated by break and continue as well as errors. KEYWORDS catch, error ═══ 3.9. 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. KEYWORDS working directory ═══ 3.10. clock ═══ NAME clock - Obtain and manipulate time SYNOPSIS clock option ?arg arg ...? DESCRIPTION This command performs one of several operations that may obtain or manipulate strings or values that represent some notion of time. The option argument determines what action is carried out by the command. The legal options (which may be abbreviated) are: clock clicks Return 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. This value should only be used for the relative measurement of elapsed time. clock format clockValue ?-format string? ?-gmt boolean? Converts an integer time value, typically returned by clock seconds, clock scan, or the atime, mtime, or ctime options of the file command, to human-readable form. If the -format argument is present the next argument is a string that describes how the date and time are to be formatted. Field descriptors consist of a % followed by a field descriptor character. All other characters are copied into the result. Valid field descriptors are: 1. Insert a %. 2. Abbreviated weekday name (Mon, Tue, etc.). 3. Full weekday name (Monday, Tuesday, etc.). 4. Abbreviated month name (Jan, Feb, etc.). 5. Full month name. 6. Locale specific date and time. 7. Day of month (01 - 31). 8. Hour in 24-hour format (00 - 23). 9. Hour in 12-hour format (00 - 12). 10. Day of year (001 - 366). 11. Month number (01 - 12). 12. Minute (00 - 59). 13. AM/PM indicator. 14. Seconds (00 - 59). 15. Week of year (01 - 52), Sunday is the first day of the week. 16. Weekday number (Sunday = 0). 17. Week of year (01 - 52), Monday is the first day of the week. 18. Locale specific date format. 19. Locale specific time format. 20. Year without century (00 - 99). 21. Year with century (e.g. 1990) 22. Time zone name. In addition, the following field descriptors may be supported on some systems (e.g. Unix but not Windows): 1. Date as %m/%d/%y. 2. Day of month (1 - 31), no leading zeros. 3. Abbreviated month name. 4. Insert a newline. 5. Time as %I:%M:%S %p. 6. Time as %H:%M. 7. Insert a tab. 8. Time as %H:%M:%S. If the -format argument is not specified, the format string "%a %b %d %H:%M:%S %Z %Y" is used. If the -gmt argument is present the next argument must be a boolean which if true specifies that the time will be formatted as Greenwich Mean Time. If false then the local timezone will be used as defined by the operating environment. clock scan dateString ?-base clockVal? ?-gmt boolean? Convert dateString to an integer clock value (see clock seconds). This command can parse and convert virtually any standard date and/or time string, which can include standard time zone mnemonics. If only a time is specified, the current date is assumed. If the string 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. 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 dateString 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?, dd monthname ?yy? and day, dd monthname yy. The default year is the current year. If the year is less then 100, then 1900 is added to it. 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. clock seconds Return the current date and time as a system-dependent integer value. The unit of the value is seconds, allowing it to be used for relative time calculations. The value is usually defined as total elapsed time from an "epoch". You shouldn't assume the value of the epoch. KEYWORDS clock, date, time ═══ 3.11. close ═══ NAME close - Close an open channel. SYNOPSIS close channelId DESCRIPTION Closes the channel given by channelId. ChannelId must be a channel identifier such as the return value from a previous open or socket command. 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 command for a description of channel sharing. Channels are automatically 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. KEYWORDS blocking, channel, close, nonblocking ═══ 3.12. concat ═══ NAME concat - Join lists together SYNOPSIS concat ?arg arg ...? DESCRIPTION This command treats each argument as a list and concatenates them into a single list. It also eliminates leading and trailing spaces in the arg's and adds a single separator space between arg's. It permits any number of arguments. For example, the command concat a b {c d e} {f {g h}} will return a b c d e f {g h} as its result. If no args are supplied, the result is an empty string. KEYWORDS concatenate, join, lists ═══ 3.13. 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 or foreach or while. It returns a TCL_CONTINUE 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 command and the outermost scripts of procedure bodies. KEYWORDS continue, iteration, loop ═══ 3.14. 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), 0 otherwise. KEYWORDS channel, end of file ═══ 3.15. error ═══ NAME error - Generate an error SYNOPSIS error message ?info? ?code? DESCRIPTION Returns a TCL_ERROR code, which causes command interpretation to be unwound. Message is a string that is returned to the application to indicate what went wrong. If the info argument is provided and is non-empty, it is used to initialize the global variable errorInfo. errorInfo 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 errorInfo. If the info argument is present, it is used to initialize errorInfo 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 errorInfo; in its place will be info. This feature is most useful in conjunction with the catch 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 If the code argument is present, then its value is stored in the errorCode global variable. This variable is intended to hold a machine-readable description of the error in cases where such information is available; see the tclvars manual page for information on the proper format for the variable. If the code argument is not present, then errorCode is automatically reset to "NONE" by the Tcl interpreter as part of processing the error generated by the command. KEYWORDS error, errorCode, errorInfo ═══ 3.16. 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 command, passes the concatenated string to the Tcl interpreter recursively, and returns the result of that evaluation (or any error generated by it). KEYWORDS concatenate, evaluate, script ═══ 3.17. exec ═══ NAME exec - Invoke subprocess(es) 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: -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. " 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. 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. 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. Standard error from all commands in the pipeline is redirected to fileId's file. The file must have been opened for writing. >&@ fileId FileId must be the identifier for an open file, such as the return value from a previous call to open. 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. 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 variable 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 isn't redirected, 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 don't normally end with newlines. However, if -keepnewline is specified then the trailing newline is retained. If standard input isn't redirected with "<" or "<<" 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 hasn't 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"). 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 directory /system on the machine windows (and the c:/ is ignored), and is not equivalent to c:/windows/system, which describes a directory on the current computer. Windows NT When attempting to execute an application, exec first searches for the name as it was specified. Then, in order, .com, .exe, and .bat 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 the shell builtin commands like dir and copy, the caller must prepend "cmd.exe /c " to the desired command. Windows 95 When attempting to execute an application, exec first searches for the name as it was specified. Then, in order, .com, .exe, and .bat 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 95 system directory. The Windows 95 home directory. The directories listed in the path. In order to execute the shell builtin commands like dir and copy, the caller must prepend "command.com /c " to the desired command. Once a 16-bit DOS application has read standard input from a console and then quit, all subsequently run 16-bit DOS applications will see the standard input as already closed. 32-bit applications do not have this problem and will run correctly even after a 16-bit DOS application thinks that standard input is closed. There is no known workaround for this bug at this time. Redirection between the NUL: device and a 16-bit application does not always work. When redirecting from NUL:, some applications may hang, others will get an infinite stream of "0x01" bytes, and some will actually correctly get an immediate end-of-file; the behavior seems to depend upon something compiled into the application itself. When redirecting greater than 4K or so to NUL:, some applications will hang. The above problems do not happen with 32-bit applications. All DOS 16-bit applications are run synchronously. All standard input from a pipe to a 16-bit DOS application is collected into a temporary file; the other end of the pipe must be closed before the 16-bit DOS application begins executing. All standard output or error from a 16-bit DOS application to a pipe is collected into temporary files; the application must terminate before the temporary files are redirected to the next stage of the pipeline. This is due to a workaround for a Windows 95 bug in the implementation of pipes, and is how the Windows 95 command line interpreter handles pipes itself. Certain applications, such as command.com, should not be executed interactively. Applications which directly access the console window, rather than reading from their standard input and writing to their standard output may fail, hang Tcl, or even hang the system if their own private console window is not available to them. Windows 3.X When attempting to execute an application, exec first searches for the name as it was specified. Then, in order, .com, .exe, and .bat 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 3.X system directory. The Windows 3.X home directory. The directories listed in the path. In order to execute the shell builtin commands like dir and copy, the caller must prepend "command.com /c " to the desired command. 16-bit and 32-bit DOS and Windows applications may be executed. However, redirection and piping of standard IO only works with 16-bit DOS applications. 32-bit applications always see standard input as already closed, and any standard output or error is discarded, no matter where in the pipeline the application occurs or what redirection symbols are used by the caller. Additionally, for 16-bit applications, standard error is always sent to the same place as standard output; it cannot be redirected to a separate location. In order to achieve pseudo-redirection for 32-bit applications, the 32-bit application must instead be written to take command line arguments that specify the files that it should read from and write to and open those files itself. All applications, both 16-bit and 32-bit, run synchronously; each application runs to completion before the next one in the pipeline starts. Temporary files are used to simulate piping between applications. The exec command cannot be used to start an application in the background. When standard input is redirected from an open file using the "@ fileId" notation, the open file is completely read up to its end. This is slightly different than under Windows 95 or NT, where the child application consumes from the open file only as much as it wants. Redirecting to an open file is supported as normal. Macintosh The exec command is not implemented and does not exist under Macintosh. Unix The exec command is fully functional and works as described. SEE ALSO open(n) KEYWORDS execute, pipeline, redirection, subprocess ═══ 3.18. exit ═══ NAME exit - End the application SYNOPSIS exit ?returnCode? DESCRIPTION Terminate the process, returning returnCode to the system as the exit status. If returnCode isn't specified then it defaults to 0. KEYWORDS exit, process ═══ 3.19. expr ═══ 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 are a subset of the operators permitted in C expressions, and they have 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. OPERANDS A Tcl expression consists of a combination of operands, operators, and parentheses. White space may be used between the operands and operators and parentheses; it is ignored by the expression processor. Where possible, operands are interpreted as integer values. Integer values may be specified in decimal (the normal case), in octal (if the first character of the operand is 0), or in hexadecimal (if the first two characters of the operand are 0x). 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 the ways accepted by an ANSI-compliant C compiler (except that the "f", "F", "l", and "L" suffixes will not be permitted in most installations). For example, all of the following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. If no numeric interpretation is possible, 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 an numeric value, either integer or floating-point. 2. As a Tcl variable, using standard $ notation. The variable's value will be used as the operand. 3. 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 4. 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. 5. As a Tcl command enclosed in brackets. The command will be executed and its result will be used as the operand. 6. As a mathematical function whose arguments have any of the above forms for operands, such as "sin($x)". See below for a list of defined functions. Where substitutions occur above (e.g. inside quoted strings), they are performed by the expression processor. However, an additional layer of substitution may already have been performed by the command parser 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 are listed below, grouped in decreasing order of precedence: - + ~ ! Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands may be applied to string operands, and bit-wise NOT may be applied only to integers. * / % Multiply, divide, remainder. None of these operands 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 divisor. + - 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. & 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 numeric operands only (integers or floating-point). || Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. Valid for numeric operands only (integers or floating-point). 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 numeric value. See the C manual for more details on the results produced by each operator. All of the binary operators group left-to-right within the same precedence level. For example, the command expr 4*2 < 7 returns 0. 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 Tcl supports the following mathematical functions in expressions: acos cos hypot sinh asin cosh log sqrt atan exp log10 tan atan2 floor pow tanh ceil fmod sin Each of these functions invokes the math library function of the same name; see the manual entries for the library functions for details on what they do. Tcl also implements the following functions for conversion between integers and floating-point numbers: 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. double(arg) If arg is a floating value, returns arg, otherwise converts arg to floating and returns the converted value. int(arg) If arg is an integer value, returns arg, otherwise converts arg to integer by truncation and returns the converted value. round(arg) If arg is an integer value, returns arg, otherwise converts arg to integer by rounding and returns the converted value. In addition to these predefined functions, applications may define additional functions using Tcl_CreateMathFunc(). TYPES, OVERFLOW, AND PRECISION All internal computations involving integers are done with the C type long, and 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 a Tcl error. For conversion to integer from string, detection of overflow depends on the behavior of some routines in the local C library, so it should be regarded as unreliable. In any case, integer overflow and underflow are generally not detected reliably for intermediate results. 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". The global variable tcl_precision determines the number of significant digits that are retained when floating values are converted to strings (except that trailing zeroes are omitted). If tcl_precision is unset then 6 digits of precision are used. To retain all of the significant bits of an IEEE floating-point number set tcl_precision to 17; if a value is converted to string with 17 digits of precision and then converted back to binary for some later calculation, the resulting binary value is guaranteed to be identical to the original one. 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. If one of the operands of a comparison is a string and the other has a numeric value, the numeric operand is converted back to a string using the C sprintf format specifier %d for integers and %g for floating-point values. 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 after the second operand is converted to the string "18". Because of Tcl's tendency to treat values as numbers whenever possible, it isn't generally a good idea to use operators like == when you really want string comparison and the values of the operands could be arbitrary; it's better in these cases to use the string compare command instead. KEYWORDS arithmetic, boolean, compare, expression ═══ 3.20. 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 is invoked when there are only three characters available for input and no end-of-line sequence, gets returns an empty string and a subsequent call to fblocked will return 1. SEE ALSO gets(n), read(n) KEYWORDS blocking, nonblocking ═══ 3.21. fconfigure ═══ 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. 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 command for its additional options. -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, read, puts, flush, and close commands; 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 or invoking the vwait 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 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. -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 ten and one million, allowing buffers of ten to one million bytes in size. -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. -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 and read) the Tcl I/O system automatically translates the external end-of-line representation into newline characters. Upon output (i.e., with 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, for the Macintosh platform it chooses cr 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 mode also sets the end of file character to the empty string, which disables it. See the description of -eofchar 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. This mode is typically used on Macintosh platforms. 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. SEE ALSO close(n), flush(n), gets(n), puts(n), read(n), socket(n) KEYWORDS blocking, buffering, carriage return, end of line, flushing, linemode, newline, nonblocking, platform, translation ═══ 3.22. file ═══ 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 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 Returns a decimal string giving the time at which file name was last accessed. The time is measured in the standard POSIX fashion as seconds from a fixed starting time (often January 1, 1970). If the file doesn't exist or its access time cannot be queried then an error is generated. 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. Trying to overwrite a non-empty directory, overwrite a directory with a file, or 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 ?pathname ... ? Removes the file or directory specified by each pathname argument. Non-empty directories will be removed only if the -force option is specified. Trying to delete a non-existant 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. 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 "." (or ":" on the Macintosh). 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. 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, and : for Macintosh. 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 don't support symbolic links this option behaves exactly the same as the stat option. file mkdir dir ?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 Returns a decimal string giving the time at which file name was last modified. The time is measured in the standard POSIX fashion as seconds from a fixed starting time (often January 1, 1970). If the file doesn't exist or its modified time cannot be queried then an error is generated. 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 file 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 isn't a symbolic link or its value cannot be read, then an error is returned. On systems that don't 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. 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 doesn't contain a dot, then returns name. file size name Returns a decimal string giving the size of file name in bytes. If the file doesn't 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 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 tail name Returns all of the characters in name after the last directory separator. If name contains no separators then returns name. 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. 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. SEE ALSO filename KEYWORDS attributes, copy files, delete files, directory, file, move files, name, rename files, stat ═══ 3.23. 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 or 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 fileevent, the process can tell when data is present and only invoke gets or read when they won't block. The channelId argument to fileevent refers to an open channel, such as the return value from a previous open or socket command. 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 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 command. In blocking mode, a puts command may block if you give it more data than the underlying file or device can accept, and a gets or read command will block if you attempt to read more data than is ready; no events will be processed while the commands block. In nonblocking mode puts, read, and gets never block. See the documentation for the individual commands for information on how they handle blocking and nonblocking channels. 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 bgerror mechanism 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. CREDITS fileevent is based on the addinput command created by Mark Diekhans. SEE ALSO bgerror, fconfigure, gets, puts, read KEYWORDS asynchronous I/O, blocking, channel, event handler, nonblocking, readable, script, writable. ═══ 3.24. filename ═══ 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 and file join commands to manipulate file names (see the file 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 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 array element tcl_platform(platform): mac On Apple Macintosh systems, Tcl supports two forms of path names. The normal Mac style names use colons as path separators. Paths may be relative or absolute, and file names may contain any character other than colon. A leading colon causes the rest of the path to be interpreted relative to the current directory. If a path contains a colon that is not at the beginning, then the path is interpreted as an absolute path. Sequences of two or more colons anywhere in the path are used to construct relative paths where :: refers to the parent of the current directory, ::: refers to the parent of the parent, and so forth. In addition to Macintosh style names, Tcl also supports a subset of Unix-like names. If a path contains no colons, then it is interpreted like a Unix path. Slash is used as the path separator. The file name . refers to the current directory, and .. refers to the parent of the current directory. However, some names like / or /.. have no mapping, and are interpreted as Macintosh names. In general, commands that generate file names will return Macintosh style names, but commands that accept file names will take both Macintosh and Unix-style names. The following examples illustrate various forms of path names: : Relative path to the current folder. MyFile Relative path to a file named MyFile in the current folder. MyDisk:MyFile Absolute path to a file named MyFile on the device named MyDisk. :MyDir:MyFile Relative path to a file name MyFile in a folder named MyDir in the current folder. ::MyFile Relative path to a file named MyFile in the folder above the current folder. :::MyFile Relative path to a file named MyFile in the folder two levels above the current folder. /MyDisk/MyFile Absolute path to a file named MyFile on the device named MyDisk. ../MyFile Relative path to a file named MyFile in the folder above the current folder. unix On Unix 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. 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. 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 in the root directory of the export point share on the host 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. 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. The Macintosh and 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. File names that have a tilde without a user name will be 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. 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. KEYWORDS current directory, absolute file name, relative file name, volume-relative file name, portability ═══ 3.25. 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 a channel identifier such as returned by a previous open or socket command, and it 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. SEE ALSO open(n), socket(n) KEYWORDS blocking, buffer, channel, flush, nonblocking, output ═══ 3.26. 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 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 command is invoked within body or next, then the for command will return immediately. The operation of break and continue are similar to the corresponding statements in C. For returns an empty string. KEYWORDS for, iteration, looping ═══ 3.27. 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 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 and continue statements may be invoked inside body, with the same effect as in the for command. Foreach returns an empty string. EXAMPLES 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. KEYWORDS foreach, iteration, list, looping ═══ 3.28. format ═══ NAME format - Format a string in the style of sprintf SYNOPSIS format formatString ?arg arg ...? INTRODUCTION This command generates a formatted string in the same way as the ANSI C sprintf procedure (it uses sprintf in its implementation). 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 args 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 length 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. 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. 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 isn't 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 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. The third portion of a conversion specifier is a 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 a numeric string. 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. The fifth part of a conversion specifier is a length modifier, which must be h or l. If it is h it specifies that the numeric value should be truncated to a 16-bit value before converting. This option is rarely useful. The l modifier is ignored. 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; the integer may either be in decimal, in octal (with a leading 0) or in hexadecimal (with a leading 0x). 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). c Convert integer to the 8-bit character it represents. s No conversion; just insert string. f Convert floating-point 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 floating-point number to scientific notation in the form x.yyyeё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 floating-point number as for %e or %E. Otherwise convert as for %f. Trailing zeroes and a trailing decimal point are omitted. % No conversion: just insert %. For the numerical conversions the argument being converted must be an integer or floating-point string; format converts the argument to binary and then converts it back to a string according to the conversion specifier. 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. %p and %n specifiers are not currently supported. 2. For %c conversions the argument must be a decimal string, which will then be converted to the corresponding character value. 3. The l modifier is ignored; integer values are always converted as if there were no modifier present and real values are always converted as if the l modifier were present (i.e. type double is used for the internal representation). If the h modifier is specified then integer values are truncated to short before conversion. KEYWORDS conversion specifier, format, sprintf, string, substitution ═══ 3.29. 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). 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 nonblocking 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 nonblocking 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 and fblocked commands can be used to distinguish these three cases. SEE ALSO eof(n), fblocked(n) KEYWORDS blocking, channel, end of file, end of line, line, nonblocking, read ═══ 3.30. glob ═══ NAME glob - Return names of files that match patterns SYNOPSIS glob ?switches? pattern ?pattern ...? DESCRIPTION This command performs file name "globbing" in a fashion similar to the csh shell. It returns a list of the files whose names match any of the pattern arguments. If the initial arguments to glob start with - then they are treated as switches. The following switches are currently supported: -nocomplain Allows an empty list to be returned without error; without this switch an error is returned if the result list would be empty. -- Marks the end of switches. The argument following this one will be treated as a pattern even if it starts with a -. The pattern arguments may contain any of the following special characters: ? 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 strings a, b, etc. As with csh, a "." at the beginning of a file's name or just after a "/" must be matched explicitly or with a {} construct. 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 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. PORTABILITY ISSUES Unlike other Tcl commands that will accept both network and native style names (see the filename manual entry for details on how native and network names are specified), the glob command only accepts native names. Also, for Windows UNC names, the servername and sharename components of the path may not contain ?, *, or [] constructs. KEYWORDS exist, file, glob, pattern ═══ 3.31. global ═══ NAME global - Access global variables SYNOPSIS global varname ?varname ...? DESCRIPTION This command is ignored unless a Tcl procedure is being interpreted. If so then it declares the given varname's to be global variables rather than local ones. For the duration of the current procedure (and only while executing in the current procedure), any reference to any of the varnames will refer to the global variable by the same name. KEYWORDS global, procedure, variable ═══ 3.32. history ═══ 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). 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 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 isn't 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 event ?event? Returns the value of the event given by event. Event defaults to -1. This command causes history revision to occur: see below for details. 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. This command returns an empty string. 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 return its result. Event defaults to -1. This command results in history revision: see below for details. history substitute old new ?event? Retrieves the command given by event (-1 by default), replace any occurrences of old by new in the command (only simple character equality is supported; no wild cards), execute the resulting command, and return the result of that execution. This command results in history revision: see below for details. history words selector ?event? Retrieves from the command given by event (-1 by default) the words given by selector, and return those words in a string separated by spaces. The selector argument has three forms. If it is a single number then it selects the word given by that number (0 for the command name, 1 for its first argument, and so on). If it consists of two numbers separated by a dash, then it selects all the arguments between those two. Otherwise selector is treated as a pattern; all words matching that pattern (in the sense of string match) are returned. In the numeric forms $ may be used to select the last word of a command. For example, suppose the most recent command in the history list is format {%s is %d years old} Alice [expr $ageInMonths/12] Below are some history commands and the results they would produce: Command Result history words $ [expr $ageInMonths/12] history words 1-2 {%s is %d years old} Alice history words *a*o* {%s is %d years old} [expr $ageInMonths/12] History words results in history revision: see below for details. HISTORY REVISION The history options event, redo, substitute, and words result in "history revision". When one of these options is invoked then the current event is modified to eliminate the history command and replace it with the result of the history command. For example, suppose that the most recent command in the history list is set a [expr $b+2] and suppose that the next command invoked is one of the ones on the left side of the table below. The command actually recorded in the history event will be the corresponding one on the right side of the table. Command Typed Command Recorded history redo set a [expr $b+2] history s a b set b [expr $b+2] set c [history w 2] set c [expr $b+2] History revision is needed because event specifiers like -1 are only valid at a particular time: once more events have been added to the history list a different event specifier would be needed. History revision occurs even when history is invoked indirectly from the current event (e.g. a user types a command that invokes a Tcl procedure that invokes history): the top-level command whose execution eventually resulted in a history command is replaced. If you wish to invoke commands like history words without history revision, you can use history event to save the current history event and then use history change to restore it later. KEYWORDS event, history, record, revision ═══ 3.33. 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 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. KEYWORDS boolean, conditional, else, false, if, true ═══ 3.34. 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. KEYWORDS add, increment, variable, value ═══ 3.35. info ═══ 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 cmdcount Returns a count of the total number of commands that have been invoked in this interpreter. info commands ?pattern? If pattern isn't specified, returns a list of names of all the Tcl commands, including both the built-in commands written in C and the command procedures defined using the proc command. If pattern is specified, only those names matching pattern are returned. Matching is determined using the same rules as for string match. 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 doesn't 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 isn't complete, the script can delay evaluating it until additional lines have been typed to complete the command. 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 doesn't have a default value then the command returns 0. Otherwise it returns 1 and places the default value of arg into variable varname. info exists varName Returns 1 if the variable named varName exists in the current context (either as a global or local variable), returns 0 otherwise. info globals ?pattern? If pattern isn't specified, returns a list of all the names of currently-defined global variables. If pattern is specified, only those names matching pattern are returned. Matching is determined using the same rules as for string match. info hostname Returns the name of the computer on which this invocation is being executed. 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 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 variable and may be changed by setting tcl_library. See the tclvars manual entry for more information. info loaded ?interp? Returns a list describing all of the packages that have been loaded into interp with the load 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 isn't 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 and upvar 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. 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 patchlevel Returns the value of the global variable tcl_patchLevel; see the tclvars manual entry for more information. info procs ?pattern? If pattern isn't specified, returns a list of all the names of Tcl command procedures. If pattern is specified, only those names matching pattern are returned. Matching is determined using the same rules as for string match. info script If a Tcl script file is currently being evaluated (i.e. there is a call to Tcl_EvalFile active or there is an active invocation of the source command), then this command returns the name of the innermost file being processed. 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 aren't supported on this platform then an empty string is returned. info tclversion Returns the value of the global variable tcl_version; see the tclvars manual entry for more information. info vars ?pattern? If pattern isn't specified, returns a list of all the names of currently-visible variables, including both 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. KEYWORDS command, information, interpreter, level, procedure, variable ═══ 3.36. interp ═══ NAME interp - Create and manipulate Tcl interpreters SYNOPSIS interp option ?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 variable), which are normally shared among all interpreters in the application. Note that the name space for files (such as the names returned by the open 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 removed from safe interpreters. See SAFE INTERPRETERS below for more information on what features are present in a safe interpreter. The alias mechanism can be used for protected communication (analogous to a kernel call) between a slave interpreter and its master. 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 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 option argument: interp alias srcPath srcCmd Returns a Tcl list whose elements are the targetCmd and args associated with the alias named srcCmd (all of these are the values specified when the alias was created; it is possible that the actual source command in the slave is different from srcCmd if it was renamed). interp alias srcPath srcCmd {} Deletes the alias for srcCmd in the slave interpreter identified by srcPath. srcCmd refers to the name under which 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 below for more details. interp aliases ?path? This command returns a Tcl list of the names of all the source commands for aliases defined in the interpreter identified by path. 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 interpx, 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. 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 command, then evaluates the resulting string as a Tcl script in the slave interpreter identified by path. The result of this evaluation (including error information such as the errorInfo and errorCode variables, if an error occurs) is returned to the invoking interpreter. 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 issafe ?path? Returns 1 if the interpreter identified by the specified path is safe, 0 otherwise. 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 args determine the exact behavior of the command. The valid forms of this command are: slave aliases Returns a Tcl list whose elements are the names of all the aliases in slave. The names returned are the srcCmd values used when the aliases were created (which may not be the same as the current names of the commands, if they have been renamed). slave alias srcCmd Returns a Tcl list whose elements are the targetCmd and args associated with the alias named srcCmd (all of these are the values specified when the alias was created; it is possible that the actual source command in the slave is different from srcCmd if it was renamed). slave alias srcCmd {} Deletes the alias for srcCmd in the slave interpreter. srcCmd refers to the name under which 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 below for details. slave eval arg ?arg ..? This command concatenates all of the arg arguments in the same fashion as the concat command, then evaluates the resulting string as a Tcl script in slave. The result of this evaluation (including error information such as the errorInfo and errorCode variables, if an error occurs) is returned to the invoking interpreter. slave issafe Returns 1 if the slave interpreter is safe, 0 otherwise. 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 args 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 args 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 targetCmds 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. 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 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 append array break case catch clock close concat continue eof error eval expr fblocked fileevent flush for foreach format gets global history if incr info interp join lappend lindex linsert list llength lower lrange lreplace lsearch lsort package pid proc puts read rename return scan seek set split string subst switch tell trace unset update uplevel upvar vwait while All commands not on this list are removed by interp create when it creates a safe interpreter. These commands can be recreated later as Tcl procedures or aliases. In addition, the env variable is not present in a safe interpreter, so it cannot share environment variables with other interpreters. The env 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 the package and load Tcl commands. CREDITS This mechanism is based on the Safe-Tcl prototype implemented by Nathaniel Borenstein and Marshall Rose. SEE ALSO load(n), package(n) Tcl_CreateSlave(3) KEYWORDS alias, master interpreter, safe interpreter, slave interpreter ═══ 3.37. 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. KEYWORDS element, join, list, separator ═══ 3.38. 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 doesn't exist, it is created as a list with elements given by the value arguments. Lappend is similar to append except that the values 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. KEYWORDS append, element, list, variable ═══ 3.39. library ═══ NAME library - standard library of Tcl procedures SYNOPSIS auto_execok cmd auto_load cmd auto_mkindex dir pattern pattern ... auto_reset parray arrayName 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 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. 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 is invoked from an application's Tcl_AppInit procedure, this happens automatically. The code in init.tcl will define the unknown 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 by the name cmd. This command examines the directories in the current search path (given by the PATH environment variable) to see if there is an executable file named cmd in any of those directories. If so, it returns 1; if not it returns 0. Auto_exec 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_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 if it exists. If there is no $auto_path 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 didn't 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 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 in a relatively unsophisticated way: if any line contains the word proc 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 don't appear in this way (e.g. they have spaces before the proc) will not be indexed. 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're used. parray arrayName Prints on standard output the names and values of all the elements in the array arrayName. ArrayName must be an array accessible to the caller of parray. It may be either local or global. VARIABLES The following global variables are defined or used by the procedures in the Tcl library: 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 will not attempt to auto-exec any commands. auto_noload If set to any value, then unknown 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. env(TCL_LIBRARY) If set, then it specifies the location of the directory containing library scripts (the value of this variable will be returned by the command info library). If this variable isn't 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. This variable is only used if auto_path is not defined. unknown_active This variable is set by unknown to indicate that it is active. It is used to detect errors where unknown recurses on itself infinitely. The variable is unset before unknown returns. KEYWORDS auto-exec, auto-load, library, unknown ═══ 3.40. lindex ═══ NAME lindex - Retrieve an element from a list SYNOPSIS lindex list index DESCRIPTION This 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. If index has the value end, it refers to the last element in the list. KEYWORDS element, index, list ═══ 3.41. linsert ═══ NAME linsert - Insert elements into a list SYNOPSIS linsert list index element ?element element ...? DESCRIPTION This command produces a new list from list by inserting all of the element arguments just before the indexth 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. If index has the value end, or if it is greater than or equal to the number of elements in the list, then the new elements are appended to the list. KEYWORDS element, insert, list ═══ 3.42. list ═══ NAME list - Create a list SYNOPSIS list ?arg arg ...? DESCRIPTION This command returns a list comprised of all the args, or an empty string if no args are specified. Braces and backslashes get added as necessary, so that the index command may be used on the result to re-extract the original arguments, and also so that eval may be used to execute the resulting list, with arg1 comprising the command's name and the other args comprising its arguments. List produces slightly different results than concat: concat removes one level of grouping before forming the list, while list works directly from the original arguments. For example, the command list a b {c d e} {f {g h}} will return a b {c d e} {f {g h}} while concat with the same arguments will return a b c d e f {g h} KEYWORDS element, list ═══ 3.43. 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. KEYWORDS element, list, length ═══ 3.44. load ═══ NAME load - Load machine code and initialize new commands. SYNOPSIS load fileName load fileName packageName load 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 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 initialization procedure must match the following prototype: typedef int Tcl_PackageInitProc(Tcl_Interp *interp); The interp argument identifies the interpreter in which the package is to be loaded. The initialization procedure must return TCL_OK or TCL_ERROR to indicate whether or not it completed successfully; in the event of an error it should set interp->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 loads will call the initialization procedure without loading the code again. It is not possible to unload or reload a package. The load command also supports packages that are statically linked with the application, if those packages have been registered by calling the Tcl_StaticPackage 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 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 loaded with different versions of the package, Tcl picks the file that was loaded first. BUGS If the same file is loaded by different fileNames, 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). SEE ALSO info sharedlibextension, Tcl_StaticPackage KEYWORDS binary code, loading, shared library ═══ 3.45. 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. First or last may be end (or any abbreviation of it) to refer to the last element 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 aren't enclosed in braces); it does, however, produce exactly the same results as "list [lindex list first]" KEYWORDS element, list, range, sublist ═══ 3.46. 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 gives the index in list of the first element to be replaced (0 refers to the first element). If first is less than zero then it refers to the first element of list; the element indicated by first must exist in the list. Last gives the index in list of the last element to be replaced. If last is less than first then no elements are deleted; the new elements are simply inserted before first. First or last may be end (or any abbreviation of it) to refer to the last element of the list. 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. KEYWORDS element, list, replace ═══ 3.47. lsearch ═══ NAME lsearch - See if a list contains a particular element SYNOPSIS lsearch ?mode? 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. If not, the command returns -1. The mode argument indicates how the elements of the list are to be matched against pattern and it must have one of the following values: -exact The list element must contain exactly the same string as pattern. -glob Pattern is a glob-style pattern which is matched against each list element using the same rules as the string match command. -regexp Pattern is treated as a regular expression and matched against each list element using the same rules as the regexp command. If mode is omitted then it defaults to -glob. KEYWORDS list, match, pattern, regular expression, search, string ═══ 3.48. lsort ═══ NAME lsort - Sort the elements of a list SYNOPSIS lsort ?switches? list DESCRIPTION This command sorts the elements of list, returning a new list in sorted order. By default ASCII sorting is used with the result returned in increasing order. However, any of the following switches may be specified before list to control the sorting process (unique abbreviations are accepted): -ascii Use string comparison with ASCII collation order. This is the default. -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). KEYWORDS element, list, order, sort ═══ 3.49. open ═══ 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 or command pipeline and returns a channel identifier that may be used in future invocations of commands like read, puts, and close. 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 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 doesn't exist, create a new file. w+ Open the file for reading and writing. Truncate it if it exists. If it doesn't exist, create a new file. a Open the file for writing only. The file must already exist, and the file is positioned so that new data is appended to the file. a+ Open the file for reading and writing. If the file doesn't exist, create a new empty file. Set the initial access position to the end of the file. 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. CREAT Create the file if it doesn't 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 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. 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. PORTABILITY ISSUES Windows NT 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 the pipe is closed. This behavior occurs whether the command pipeline is executing 16-bit or 32-bit applications. 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. Windows 95 A command pipeline that executes a 16-bit DOS application cannot be opened for both reading and writing, since 16-bit DOS applications that receive standard input from a pipe and send standard output to a pipe run synchronously. Command pipelines that do not execute 16-bit DOS applications run asynchronously and can be opened for both reading and writing. 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 from a 32-bit application, some of the keystrokes 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 to a 32-bit application, no output is visible on the console until the 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. Whether or not Tcl is running interactively, if a command pipeline is opened for reading from a 16-bit DOS application, the call to open will not return until end-of-file has been received from the command pipeline's standard output. If a command pipeline is opened for writing to a 16-bit DOS application, no data will be sent to the command pipeline's standard output until the pipe is actually closed. This problem occurs because 16-bit DOS applications are run synchronously, as described above. Windows 3.X A command pipeline can execute 16-bit or 32-bit DOS or Windows applications, but the call to open will not return until the last program in the pipeline has finished executing; command pipelines run synchronously. If the pipeline is opened with write access (either just writing or both reading and writing) the first application in the pipeline will instead see an immediate end-of-file; any data the caller writes to the open pipe will instead be discarded. Since Tcl cannot be run with a real console under Windows 3.X, there are no interactions between command pipelines and the console. Macintosh Opening a command pipeline is not supported under Macintosh, since applications do not support the concept of standard input or output. Unix 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 section of the exec command for additional information not specific to command pipelines about executing applications on the various platforms SEE ALSO close(n), filename(n), gets(n), read(n), puts(n), exec(n) KEYWORDS access mode, append, create, file, non-blocking, open, permissions, pipeline, process ═══ 3.50. package ═══ NAME package - Facilities for package loading and version control SYNOPSIS package forget package package ifneeded package version ?script? package names package provide package ?version? package require ?-exact? package ?version? package unknown ?command? package vcompare version1 version2 package versions package package vsatisfies version1 version2 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 Removes all information about 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 and/or source 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 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 ?-exact? package ?version? 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. If both the -exact switch and the version argument are specified then only the given version is acceptable. If -exact is omitted but version is specified, then versions later than version are also acceptable as long as they have the same major version number as version. If both -exact and version are omitted then any version whatsoever is acceptable. If a version of package has already been provided (by invoking the package provide command), then its version number must satisfy the criteria given by -exact and version 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 invoked; 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 invoked; 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 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 two additional arguments giving the desired package name and version. 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 version number is supplied to the package require command, then the version argument for the invoked command will be an empty string. 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 version1 version2 Returns 1 if scripts written for version2 will work unchanged with version1 (i.e. version1 is equal to or greater than version2 and they both have the same major version number), 0 otherwise. 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. 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've done this, packages will be loaded automatically in response to package require commands. See the documentation for pkg_mkIndex for details. KEYWORDS package, version ═══ 3.51. pid ═══ NAME pid - Retrieve process id(s) SYNOPSIS pid ?fileId? DESCRIPTION If the fileId argument is given then it should normally refer to a process pipeline created with the open 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 isn't 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. KEYWORDS file, pipeline, process identifier ═══ 3.52. pkg_mkIndex ═══ NAME pkg_mkIndex - Build an index for automatic loading of packages SYNOPSIS pkg_mkIndex dir pattern ?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 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 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 command to declare the package and version number, and each binary file must contain a call to Tcl_PkgProvide. 2. Create the index by invoking pkg_mkIndex. The dir argument gives the name of a directory and each pattern argument is a glob-style pattern that selects script or binary files in dir. 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 and seeing what packages and new commands appear (this is why it is essential to have package provide commands or Tcl_PkgProvide calls in the files, as described above). 3. Install the package as a subdirectory of one of the directories given by the tcl_pkgPath 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 commands. If you install the package anywhere else, then you must ensure that the directory contaiingn the package is in the auto_path global variable or an immediate subdirectory of one of the directories in auto_path. Auto_path 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. You can add a directory to auto_path 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 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. 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, but only one will actually be loaded in a given interpreter, based on the first call to package require. Different versions of a package may be loaded in different interpreters. 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 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 commands. In contrast, auto_mkindex 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. If you use pkg_mkIndex to index a package, its commands cannot be invoked until package require has been used to select a version; in contrast, packages indexed with auto_mkindex can be used immediately since there is no version control. HOW IT WORKS Pkg_mkIndex depends on the package unknown command, the package ifneeded command, and the auto-loader. The first time a package require command is invoked, the package unknown script is invoked. This is set by Tcl initialization to a script that evaluates all of the pkgIndex.tcl files in the auto_path. The pkgIndex.tcl files contain package ifneeded commands for each version of each available package; these commands invoke package provide commands to announce the availability of the package, and they setup auto-loader information to load the files of the package. A given file of a given version of a given package isn't actually loaded until the first time one of its commands is invoked. Thus, after invoking package require you won't see the package's commands in the interpreter, but you will be able to invoke the commands and they will be auto-loaded. KEYWORDS auto-load, index, package, version ═══ 3.53. 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. 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. 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. 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 don't have defaults, and there must not be any extra actual 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 formals. 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 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. Global variables can only be accessed by invoking the global command or the upvar command. The proc command returns an empty string. When a procedure is invoked, the procedure's return value is the value specified in a return command. If the procedure doesn't execute an explicit return, 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. KEYWORDS argument, procedure ═══ 3.54. 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 a channel identifier such as returned from a previous invocation of open or socket. It must have been opened for output. If no channelId is specified then it defaults to stdout. 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; on Macintoshes newlines are normally replaced with carriage-returns). See the fconfigure manual entry for a discussion of end-of-line translations. 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 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 command (don't invoke puts unless you have recently been notified via a file event that the channel is ready for more output data). SEE ALSO fileevent(n) KEYWORDS channel, newline, output, write ═══ 3.55. pwd ═══ NAME pwd - Return the current working directory SYNOPSIS pwd DESCRIPTION Returns the path name of the current working directory. KEYWORDS working directory ═══ 3.56. read ═══ NAME read - Read from a channel SYNOPSIS read ?-nonewline? channelId read channelId numBytes 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 bytes to read. Exactly that many bytes will be read and returned, unless there are fewer than numBytes left in the file; in this case all the remaining bytes are returned. If channelId is in nonblocking mode, the command may not read as many bytes as requested: once all available input has been read, the command will return the data that is available rather than blocking for more input. 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 manual entry for fconfigure for details on the -translation option. SEE ALSO eof(n), fblocked(n), fconfigure(n) KEYWORDS blocking, channel, end of line, end of file, nonblocking, read, translation ═══ 3.57. regexp ═══ 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 doesn't. 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: -nocase Causes upper-case characters in string to be treated as lower case during the matching process. -indices Changes what is stored in the subMatchVars. 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. -- 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 doesn't match the string (e.g. because it was in a portion of the expression that wasn't matched), then the corresponding subMatchVar will be set to "-1 -1" if -indices has been specified or to an empty string otherwise. REGULAR EXPRESSIONS Regular expressions are implemented using Henry Spencer's package (thanks, Henry!), and much of the description of regular expressions below is copied verbatim from his manual entry. A regular expression is zero or more branches, separated by "|". It matches anything that matches one of the branches. A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc. A piece is an atom possibly followed by "*", "+", or "?". An atom followed by "*" matches a sequence of 0 or more matches of the atom. An atom followed by "+" matches a sequence of 1 or more matches of the atom. An atom followed by "?" matches a match of the atom, or the null string. An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), "." (matching any single character), "^" (matching the null string at the beginning of the input string), "$" (matching the null string at the end of the input string), a "\" followed by a single character (matching that character), or a single character with no other significance (matching that character). A range is a sequence of characters enclosed in "[]". It normally matches any single character from the sequence. If the sequence begins with "^", it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by "-", this is shorthand for the full list of ASCII characters between them (e.g. "[0-9]" matches any decimal digit). To include a literal "]" in the sequence, make it the first character (following a possible "^"). To include a literal "-", make it the first or last character. CHOOSING AMONG ALTERNATIVE MATCHES In general there may be more than one way to match a regular expression to an input string. For example, consider the command regexp (a*)b* aabaaabb x y Considering only the rules given so far, x and y could end up with the values aabb and aa, aaab and aaa, ab and a, or any of several other combinations. To resolve this potential ambiguity regexp chooses among alternatives using the rule "first then longest". In other words, it considers the possible matches in order working from left to right across the input string and the pattern, and it attempts to match longer pieces of the input string before shorter ones. More specifically, the following rules apply in decreasing order of priority: 1. If a regular expression could match two different parts of an input string then it will match the one that begins earliest. 2. If a regular expression contains | operators then the leftmost matching sub-expression is chosen. 3. In *, +, and ? constructs, longer matches are chosen in preference to shorter ones. 4. In sequences of expression components the components are considered from left to right. In the example from above, (a*)b* matches aab: the (a*) portion of the pattern is matched first and it consumes the leading aa; then the b* portion of the pattern consumes the next b. Or, consider the following example: regexp (ab|a)(b*)c abc x y z After this command x will be abc, y will be ab, and z will be an empty string. Rule 4 specifies that (ab|a) gets first shot at the input string and Rule 2 specifies that the ab sub-expression is checked before the a sub-expression. Thus the b has already been claimed before the (b*) component is checked and (b*) must match an empty string. KEYWORDS match, regular expression, string ═══ 3.58. regsub ═══ 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 it copies string to the variable whose name is given by varName. If there is a match, then while copying string to varName 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 "&" or "\0" or "\n" or backslash. The use of backslashes in subSpec tends to interact badly with the Tcl parser's use of backslashes, so it's generally safest to enclose subSpec in braces if it includes backslashes. If the initial arguments to regexp 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. -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. -- Marks the end of switches. The argument following this one will be treated as exp even if it starts with a -. The command returns a count of the number of matching ranges that were found and replaced. See the manual entry for regexp for details on the interpretation of regular expressions. KEYWORDS match, pattern, regular expression, substitute ═══ 3.59. 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. The rename command returns an empty string as result. KEYWORDS command, delete, rename ═══ 3.60. return ═══ NAME return - Return from a procedure SYNOPSIS return ?-code code? ?-errorinfo info? ?-errorcode code? ?string? DESCRIPTION Return immediately from the current procedure (or top-level command or source command), with string as the return value. If string is not specified then an empty string will be returned as result. EXCEPTIONAL RETURNS In the usual case where the -code option isn't specified the procedure will return normally (its completion code will be TCL_OK). However, the -code option may be used to generate an exceptional return from the procedure. Code may have any of the following values: ok Normal return: same as if the option is omitted. error Error return: same as if the error command were used to terminate the procedure, except for handling of errorInfo and errorCode variables (see below). return The current procedure will return with a completion code of TCL_RETURN, so that the procedure that invoked it will return also. break The current procedure will return with a completion code of TCL_BREAK, which will terminate the innermost nested loop in the code that invoked the current procedure. continue The current procedure will return with a completion code of TCL_CONTINUE, which will terminate the current iteration of the innermost nested loop in the code that invoked the current procedure. value Value must be an integer; it will be returned as the completion code for the current procedure. The -code option is rarely used. It is provided so that procedures that implement new control structures can reflect exceptional conditions back to their callers. Two additional options, -errorinfo and -errorcode, may be used to provide additional information during error returns. These options are ignored unless code is error. The -errorinfo option specifies an initial stack trace for the errorInfo variable; if it is not specified then the stack trace left in errorInfo will include the call to the procedure and higher levels on the stack but it will not include any information about the context of the error within the procedure. Typically the info value is supplied from the value left in errorInfo after a catch command trapped an error within the procedure. If the -errorcode option is specified then code provides a value for the errorCode variable. If the option is not specified then errorCode will default to NONE. KEYWORDS break, continue, error, procedure, return ═══ 3.61. scan ═══ NAME scan - Parse string using conversion specifiers in the style of sscanf SYNOPSIS scan string format varName ?varName ...? INTRODUCTION This command parses fields from an input string in the same fashion as 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 field is scanned from string the result is converted back into a string and assigned to the corresponding variable. DETAILS ON SCANNING Scan operates by scanning string and formatString together. If the next character in formatString is a blank or tab then it matches any number of white space characters in string (including zero). Otherwise, if it isn't a % character then it must match the next character of string. When a % is encountered in formatString, it indicates the start of a conversion specifier. A conversion specifier contains three fields after the %: a *, which indicates that the converted value is to be discarded instead of assigned to a variable; a number indicating a maximum field width; and a conversion character. All of these fields are optional except for the conversion character. When scan finds a conversion specifier in formatString, it first skips any white-space characters in string. 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. The following conversion characters are supported: d The input field must be a decimal integer. It is read in and the value is stored in the variable as a decimal string. o The input field must be an octal integer. It is read in and the value is stored in the variable as a decimal string. x The input field must be a hexadecimal integer. It is read in and the value is stored in the variable as a decimal string. c A single character is read in and its binary value is stored in the variable as a decimal string. Initial white space is not skipped in this case, so the input field may be a white-space character. This conversion is different from the ANSI standard in that the input field always consists of a single character and no field width may be specified. s The input field consists of all the characters up to the next white-space character; the characters are copied to the variable. e or f or g The input field 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 string. [chars] The input field consists of any number of 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. [^chars] The input field consists of any number of 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. 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 field for a given conversion terminates either when a white-space character is encountered or when the maximum field 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 and %n conversion specifiers are not currently supported. 2. For %c conversions a single character value is converted to a decimal string, which is then assigned to the corresponding varName; no field width may be specified for this conversion. 3. The l, h, and L modifiers are ignored; integer values are always converted as if there were no modifier present and real values are always converted as if the l modifier were present (i.e. type double is used for the internal representation). KEYWORDS conversion specifier, parse, scan ═══ 3.62. 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 a channel identifier such as returned from a previous invocation of open or socket. 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 nonblocking 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. KEYWORDS access position, file, seek ═══ 3.63. 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 doesn't 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 no procedure is active, then varName refers to a global variable. If a procedure is active, then varName refers to a parameter or local variable of the procedure unless the global command has been invoked to declare varName to be global. KEYWORDS read, write, variable ═══ 3.64. socket ═══ 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, puts and flush. At present only the TCP network protocol is supported; 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. 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 and host is either a domain-style name such as www.sunlabs.com or a numerical IP address such as 127.0.0.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 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 The -async 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 or flush 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 or flush is done on the socket before the connection attempt succeeds or fails, the operation returns immediately and fblocked on the socket returns 1. SERVER SOCKETS If the -server option is specified then the new socket will be a server for the port given by port. 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 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 host: -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 special address INADDR_ANY so that it can accept connections from any interface. 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 doesn't enter the event loop, for example by invoking the vwait command or calling the C procedure Tcl_DoOneEvent, then no connections will be accepted. CONFIGURATION OPTIONS The fconfigure command can be used to query several readonly configuration options for socket channels: -sockname 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. -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. SEE ALSO flush(n), open(n), read(n) KEYWORDS bind, channel, connection, domain name, host, network address, socket, tcp ═══ 3.65. source ═══ NAME source - Evaluate a file or resource as a Tcl script SYNOPSIS source fileName source -rsrc resourceName ?fileName? source -rsrcid resourceId ?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 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 command. The -rsrc and -rsrcid forms of this command are only available on Macintosh computers. These versions of the command allow you to source a script from a TEXT resource. You may specify what TEXT resource to source by either name or id. By default Tcl searches all open resource files, which include the current application and any loaded C extensions. Alternatively, you may specify the fileName where the TEXT resource can be found. KEYWORDS file, script ═══ 3.66. 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. For example, split "comp.unix.misc" . returns "comp unix misc" and split "Hello world" {} returns "H e l l o { } w o r l d". KEYWORDS list, split, string ═══ 3.67. string ═══ NAME string - Manipulate strings SYNOPSIS string option arg ?arg ...? DESCRIPTION Performs one of several string operations, depending on option. The legal options (which may be abbreviated) are: string compare string1 string2 Perform a character-by-character comparison of strings string1 and string2 in the same way as the C strcmp procedure. Return -1, 0, or 1, depending on whether string1 is lexicographically less than, equal to, or greater than string2. string first string1 string2 Search string2 for a sequence of characters that exactly match the characters in string1. If found, return the index of the first character in the first such match within string2. If not found, 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. If charIndex is less than 0 or greater than or equal to the length of the string then an empty string is returned. string last string1 string2 Search string2 for a sequence of characters that exactly match the characters in string1. If found, return the index of the first character in the last such match within string2. If there is no match, then return -1. string length string Returns a decimal string giving the number of characters in string. string match pattern string See if pattern matches string; return 1 if it does, 0 if it doesn't. Matching is done in a fashion similar to that used by the C-shell. 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. \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. An index of end (or any abbreviation of it) refers to the last character of the string. 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 tolower string Returns a value equal to string except that all upper case letters have been converted to lower case. string toupper string Returns a value equal to string except that all lower case letters have been converted to upper case. string trim string ?chars? Returns a value equal to string except that any leading or trailing characters from the set given by chars are removed. If chars is not specified then white space is removed (spaces, tabs, newlines, and carriage returns). string trimleft string ?chars? Returns a value equal to string except that any leading characters from the set given by chars are removed. If chars is not specified then white space is removed (spaces, tabs, newlines, and carriage returns). string trimright string ?chars? Returns a value equal to string except that any trailing characters from the set given by chars are removed. If chars is not specified then white space is removed (spaces, tabs, newlines, and carriage returns). string wordend string index Returns the index of the character just after the last one in the word containing character index of string. A word is considered to be any contiguous range of alphanumeric or underscore characters, or any single character other than these. string wordstart string index Returns the index of the first character in the word containing character index of string. A word is considered to be any contiguous range of alphanumeric or underscore characters, or any single character other than these. KEYWORDS case conversion, compare, index, match, pattern, string, word ═══ 3.68. 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, no command substitution is performed: open and close brackets are treated as ordinary characters with no special interpretation. Note: when it performs its substitutions, subst does not give any special treatment to double quotes or curly braces. For example, the script set a 44 subst {xyz {$a}} returns "xyz {44}", not "xyz {$a}". KEYWORDS backslash substitution, command substitution, variable substitution ═══ 3.69. switch ═══ 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. 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 command). -regexp When matching string to the patterns, use regular expression matching (i.e. the same as implemented by the regexp command). -- Marks the end of options. The argument following this one will be treated as string even if it starts with a -. 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. Below are some examples of switch commands: switch abc a - b {format 1} abc {format 2} default {format 3} will return 2, switch -regexp aaab { ^a.*b$ - b {format 1} a* {format 2} default {format 3} } will return 1, and switch xyz { a - b {format 1} a* {format 2} default {format 3} } will return 3. KEYWORDS switch, match, regular expression ═══ 3.70. tclvars ═══ NAME tclvars - 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. 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 doesn't 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. If the entire env array is unset then Tcl will stop monitoring env accesses and will not update environment variables. errorCode After an error has occurred, this variable will be set to hold additional information about the error in a form that is easy to process with programs. errorCode consists of a Tcl list with one or more elements. 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 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 by zero in the expr 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). CHILDKILLED pid sigName msg This format is used when a child process has been killed because of a signal. The second element of errorCode will be the process's identifier (in decimal). The third 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 fourth 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 second element of errorCode will be the process's identifier (in decimal) and the third 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 second element of errorCode will be the process's identifier, in decimal. The third 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 fourth 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 errorCode will consist of a list containing a single element whose contents are NONE. POSIX errName msg If the first element of errorCode is POSIX, then the error occurred during a POSIX kernel call. The second element of the list 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 third element of the list will be a human-readable message corresponding to errName, such as "no such file or directory" for the ENOENT case. To set errorCode, applications should use library procedures such as Tcl_SetErrorCode and Tcl_PosixError, or they may invoke the error command. If one of these methods hasn't been used, then the Tcl interpreter will reset the variable to NONE after the next error. errorInfo After an error has occurred, this string 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 command. See the library 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 isn't 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 7.3p2 for Tcl 7.3 with the first two official patches, or 7.4b4 for the fourth beta release of Tcl 7.4. The value of this variable is returned by the info patchlevel command. tcl_pkgPath This variable holds a list of directories indicating where packages are normally installed. 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 $tcl_pkgPath. The directories in $tcl_pkgPath are included by default in the auto_path variable, so they and their immediate subdirectories are automatically searched for packages during package require commands. Note: tcl_pkgPath it 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 couldn't retrieve any relevant information. In addition, extensions and applications may add additional values to the array. The predefined elements are: machine The instruction set executed by this machine, such as 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 Win95, MacOS, 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. platform Either windows, macintosh, or unix. This identifies the general operating environment of the machine. tcl_precision If this variable is set, it must contain a decimal number giving the number of significant digits to include when converting floating-point values to strings. If this variable is not set then 6 digits are included. 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 precision. 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 it if it exists. For example, for wish the variable is set to ~/.wishrc for Unix and ~/wishrc.tcl for Windows. tcl_rcRsrcName This variable is only used on Macintosh systems. The variable is used during initialization to indicate the name of a user-specific TEXT resource located in the application or extension resource forks. If it is set by application-specific initialization, then the Tcl startup code will check for the existence of this resource and source it if it exists. For example, the Macintosh wish application has the variable is set to tclshrc. 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 command. KEYWORDS arithmetic, error, environment, POSIX, precision, subprocess, variables ═══ 3.71. tell ═══ NAME tell - Return current access position for an open channel SYNOPSIS tell channelId DESCRIPTION Returns a decimal string giving the current access position in channelId. The value returned is -1 for channels that do not support seeking. KEYWORDS access position, channel, seeking ═══ 3.72. 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 isn't specified). It will then return a string of the form 503 microseconds per iteration which indicates the average amount of time required per iteration, in microseconds. Time is measured in elapsed time, not CPU time. KEYWORDS script, time ═══ 3.73. trace ═══ NAME trace - Monitor variable accesses SYNOPSIS trace option ?arg arg ...? DESCRIPTION This command causes Tcl commands to be executed whenever certain operations are invoked. At present, only variable tracing is implemented. The legal option's (which may be abbreviated) are: trace variable name ops command Arrange for command to be executed whenever variable name is accessed in one of the ways given by 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 command is invoked whenever any element of the array is manipulated. Ops indicates which operations are of interest, and consists of one or more of the following letters: r Invoke command whenever the variable is read. w Invoke command whenever the variable is written. u Invoke command whenever the variable is unset. Variables can be unset explicitly with the unset 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 command so that the actual command is as follows: command 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 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 r, w, or u as defined above. Command 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 command 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 command invokes a procedure (which it normally does) then the procedure will have to use upvar or uplevel 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 command. For read and write traces, command can modify the variable to affect the result of the traced operation. If command 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 command 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, command 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, command will have to restore the old value of the variable. While command is executing during a read or write trace, traces on the variable are temporarily disabled. This means that reads and writes invoked by command will occur directly, without invoking command (or any other traces) again. However, if command 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 vdelete 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 vdelete name ops command If there is a trace set on variable name with the operations and command given by ops and command, then the trace is removed, so that command will never again be invoked. Returns an empty string. trace vinfo 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 ops and command associated with the trace. If name doesn't exist or doesn't have any traces set, then the result of the command will be an empty string. KEYWORDS read, variable, write, trace, unset ═══ 3.74. 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 doesn't exist. The implementation of unknown isn't part of the Tcl core; instead, it is a library procedure defined by default when Tcl starts up. You can override the default unknown to change its functionality. If the Tcl interpreter encounters a command name for which there is not a defined command, then Tcl checks for the existence of a command named unknown. If there is no such command, then the interpreter returns an error. If the unknown command exists, 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 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 to see if there is an executable file by the name cmd. If so, it invokes the Tcl exec command with cmd and all the args as arguments. If cmd can't 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. KEYWORDS error, non-existent command ═══ 3.75. unset ═══ NAME unset - Delete variables SYNOPSIS unset 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 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. An error occurs if any of the variables doesn't exist, and any variables after the non-existent one are not deleted. KEYWORDS remove, variable ═══ 3.76. 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 repeated 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. KEYWORDS event, flush, handler, idle, update ═══ 3.77. 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; 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 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 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 command "info level" 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 construct as a Tcl procedure). KEYWORDS context, stack frame, variables ═══ 3.78. 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 command, and may be omitted if the first letter of the first otherVar isn't # or a digit (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. Even if the name looks like an array element, such as a(b), a regular variable is created. 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] } Add2 is invoked with an argument giving the name of a variable, and it adds two to the value of that variable. Although add2 could have been implemented using uplevel instead of upvar, upvar makes it simpler for add2 to access the variable in the caller's procedure frame. If an upvar variable is unset (e.g. x in add2 above), the unset 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. BUGS 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, then changes made to myVar will not be passed to subprocesses correctly. KEYWORDS context, frame, global, level, procedure, variable ═══ 3.79. 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 variable varName. Once varName has been set, the vwait command will return as soon as the event handler that modified varName completes. In some cases the vwait command may not return immediately after varName is set. This can happen 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. KEYWORDS event, variable, wait ═══ 3.80. 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 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 commands may be executed inside body to terminate the current iteration of the loop, and break commands may be executed inside body to cause immediate termination of the while command. The while command always returns an empty string. KEYWORDS boolean value, loop, test, while ═══ 4. Tk Applications ═══ ═══ 4.1. wish ═══ NAME wish - Simple windowing shell SYNOPSIS wish ?fileName arg arg ...? OPTIONS -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 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 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. -visual visual Specifies the visual to use for the window. Visual may have any of the forms supported by the Tk_GetVisual procedure. -- Pass all remaining arguments through to the script's argv 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 no arguments, or with a first argument that starts with "-", then it 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 wish is invoked with an initial fileName argument, 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 in this case, but the script file can always source it if desired. OPTIONS Wish automatically processes all of the command-line options described in the OPTIONS summary above. Any other command-line arguments besides these are passed through to the application using the argc and argv variables described later. APPLICATION NAME AND CLASS The name of the application, which is used for purposes such as send 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 don't match any of the options described in OPTIONS 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 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's installed somewhere else then you'll 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" "$@" This approach has three advantages over the approach in the previous paragraph. First, the location of the wish binary doesn't 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 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 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. 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 isn't yet complete; if tcl_prompt2 isn't set then no prompt is output for incomplete commands. KEYWORDS shell, toolkit ═══ 5. Tk Library Procedures ═══ ═══ 5.1. Tk_Get3DBorder ═══ NAME Tk_Get3DBorder, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorder - draw borders with three-dimensional appearance SYNOPSIS #include Tk_3DBorder Tk_Get3DBorder(interp, tkwin, colorName) void Tk_Draw3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief) void Tk_Fill3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief) void Tk_Draw3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief) void Tk_Fill3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief) void Tk_3DVerticalBevel(tkwin, drawable, border, x, y, width, height, leftBevel, relief) void Tk_3DHorizontalBevel(tkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief) void Tk_SetBackgroundFromBorder(tkwin, border) char * Tk_NameOf3DBorder(border) XColor * Tk_3DBorderColor(border) GC * Tk_3DBorderGC(tkwin, border, which) Tk_Free3DBorder(border) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. Tk_Window tkwin (in) Token for window (for all procedures except Tk_Get3DBorder, must be the window for which the border was allocated). Tk_Uid colorName (in) Textual description of color corresponding to background (flat areas). Illuminated edges will be brighter than this and shadowed edges will be darker than this. Drawable drawable (in) X token for window or pixmap; indicates where graphics are to be drawn. Must either be the X window for tkwin or a pixmap with the same screen and depth as tkwin. Tk_3DBorder border (in) Token for border previously allocated in call to Tk_Get3DBorder. int x (in) X-coordinate of upper-left corner of rectangle describing border or bevel, in pixels. int y (in) Y-coordinate of upper-left corner of rectangle describing border or bevel, in pixels. int width (in) Width of rectangle describing border or bevel, in pixels. int height (in) Height of rectangle describing border or bevel, in pixels. int borderWidth (in) Width of border in pixels. Positive means border is inside rectangle given by x, y, width, height, negative means border is outside rectangle. int relief (in) Indicates 3-D position of interior of object relative to exterior; should be TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, or TK_RELIEF_RIDGE (may also be TK_RELIEF_FLAT for Tk_Fill3DRectangle). XPoint *pointPtr (in) Pointer to array of points describing the set of vertices in a polygon. The polygon need not be closed (it will be closed automatically if it isn't). int numPoints (in) Number of points at *pointPtr. int polyBorderWidth (in) Width of border in pixels. If positive, border is drawn to left of trajectory given by pointPtr; if negative, border is drawn to right of trajectory. If leftRelief is TK_RELIEF_GROOVE or TK_RELIEF_RIDGE then the border is centered on the trajectory. int leftRelief (in) Height of left side of polygon's path relative to right. TK_RELIEF_RAISED means left side should appear higher and TK_RELIEF_SUNKEN means right side should appear higher; TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean the obvious things. For Tk_Fill3DPolygon, TK_RELIEF_FLAT may also be specified to indicate no difference in height. int leftBevel (in) Non-zero means this bevel forms the left side of the object; zero means it forms the right side. int leftIn (in) Non-zero means that the left edge of the horizontal bevel angles in, so that the bottom of the edge is farther to the right than the top. Zero means the edge angles out, so that the bottom is farther to the left than the top. int rightIn (in) Non-zero means that the right edge of the horizontal bevel angles in, so that the bottom of the edge is farther to the left than the top. Zero means the edge angles out, so that the bottom is farther to the right than the top. int topBevel (in) Non-zero means this bevel forms the top side of the object; zero means it forms the bottom side. int which (in) Specifies which of the border's graphics contexts is desired. Must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC. DESCRIPTION These procedures provide facilities for drawing window borders in a way that produces a three-dimensional appearance. Tk_Get3DBorder allocates colors and Pixmaps needed to draw a border in the window given by the tkwin argument. The colorName argument indicates what colors should be used in the border. ColorName may be any value acceptable to Tk_GetColor. The color indicated by colorName will not actually be used in the border; it indicates the background color for the window (i.e. a color for flat surfaces). The illuminated portions of the border will appear brighter than indicated by colorName, and the shadowed portions of the border will appear darker than colorName. Tk_Get3DBorder returns a token that may be used in later calls to Tk_Draw3DRectangle. If an error occurs in allocating information for the border (e.g. colorName isn't a legal color specifier), then NULL is returned and an error message is left in interp->result. Once a border structure has been created, Tk_Draw3DRectangle may be invoked to draw the border. The tkwin argument specifies the window for which the border was allocated, and drawable specifies a window or pixmap in which the border is to be drawn. Drawable need not refer to the same window as tkwin, but it must refer to a compatible pixmap or window: one associated with the same screen and with the same depth as tkwin. The x, y, width, and height arguments define the bounding box of the border region within drawable (usually x and y are zero and width and height are the dimensions of the window), and borderWidth specifies the number of pixels actually occupied by the border. The relief argument indicates which of several three-dimensional effects is desired: TK_RELIEF_RAISED means that the interior of the rectangle should appear raised relative to the exterior of the rectangle, and TK_RELIEF_SUNKEN means that the interior should appear depressed. TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to be a groove or ridge around the exterior of the rectangle. Tk_Fill3DRectangle is somewhat like Tk_Draw3DRectangle except that it first fills the rectangular area with the background color (one corresponding to the colorName used to create border). Then it calls Tk_Draw3DRectangle to draw a border just inside the outer edge of the rectangular area. The argument relief indicates the desired effect (TK_RELIEF_FLAT means no border should be drawn; all that happens is to fill the rectangle with the background color). The procedure Tk_Draw3DPolygon may be used to draw more complex shapes with a three-dimensional appearance. The pointPtr and numPoints arguments define a trajectory, polyBorderWidth indicates how wide the border should be (and on which side of the trajectory to draw it), and leftRelief indicates which side of the trajectory should appear raised. Tk_Draw3DPolygon draws a border around the given trajectory using the colors from border to produce a three-dimensional appearance. If the trajectory is non-self-intersecting, the appearance will be a raised or sunken polygon shape. The trajectory may be self-intersecting, although it's not clear how useful this is. Tk_Fill3DPolygon is to Tk_Draw3DPolygon what Tk_Fill3DRectangle is to Tk_Draw3DRectangle: it fills the polygonal area with the background color from border, then calls Tk_Draw3DPolygon to draw a border around the area (unless leftRelief is TK_RELIEF_FLAT; in this case no border is drawn). The procedures Tk_3DVerticalBevel and Tk_3DHorizontalBevel provide lower-level drawing primitives that are used by procedures such as Tk_Draw3DRectangle. These procedures are also useful in their own right for drawing rectilinear border shapes. Tk_3DVerticalBevel draws a vertical beveled edge, such as the left or right side of a rectangle, and Tk_3DHorizontalBevel draws a horizontal beveled edge, such as the top or bottom of a rectangle. Each procedure takes x, y, width, and height arguments that describe the rectangular area of the beveled edge (e.g., width is the border width for Tk_3DVerticalBevel). The leftBorder and topBorder arguments indicate the position of the border relative to the "inside" of the object, and relief indicates the relief of the inside of the object relative to the outside. Tk_3DVerticalBevel just draws a rectangular region. Tk_3DHorizontalBevel draws a trapezoidal region to generate mitered corners; it should be called after Tk_3DVerticalBevel (otherwise Tk_3DVerticalBevel will overwrite the mitering in the corner). The leftIn and rightIn arguments to Tk_3DHorizontalBevel describe the mitering at the corners; a value of 1 means that the bottom edge of the trapezoid will be shorter than the top, 0 means it will be longer. For example, to draw a rectangular border the top bevel should be drawn with 1 for both leftIn and rightIn, and the bottom bevel should be drawn with 0 for both arguments. The procedure Tk_SetBackgroundFromBorder will modify the background pixel and/or pixmap of tkwin to produce a result compatible with border. For color displays, the resulting background will just be the color given by the colorName argument passed to Tk_Get3DBorder when border was created; for monochrome displays, the resulting background will be a light stipple pattern, in order to distinguish the background from the illuminated portion of the border. Given a token for a border, the procedure Tk_NameOf3DBorder will return the colorName string that was passed to Tk_Get3DBorder to create the border. The procedure Tk_3DBorderColor returns the XColor structure that will be used for flat surfaces drawn for its border argument by procedures like Tk_Fill3DRectangle. The return value corresponds to the colorName passed to Tk_Get3DBorder. The XColor, and its associated pixel value, will remain allocated as long as border exists. The procedure Tk_3DBorderGC returns one of the X graphics contexts that are used to draw the border. The argument which selects which one of the three possible GC's: TK_3D_FLAT_GC returns the context used for flat surfaces, TK_3D_LIGHT_GC returns the context for light shadows, and TK_3D_DARK_GC returns the context for dark shadows. When a border is no longer needed, Tk_Free3DBorder should be called to release the resources associated with the border. There should be exactly one call to Tk_Free3DBorder for each call to Tk_Get3DBorder. KEYWORDS 3D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect ═══ 5.2. Tk_CreateBindingTable ═══ NAME Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent - invoke scripts in response to X events SYNOPSIS #include Tk_BindingTable Tk_CreateBindingTable(interp) Tk_DeleteBindingTable(bindingTable) unsigned long Tk_CreateBinding(interp, bindingTable, object, eventString, script, append) int Tk_DeleteBinding(interp, bindingTable, object, eventString) char * Tk_GetBinding(interp, bindingTable, object, eventString) Tk_GetAllBindings(interp, bindingTable, object) Tk_DeleteAllBindings(bindingTable, object) Tk_BindEvent(bindingTable, eventPtr, tkwin, numObjects, objectPtr) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use when invoking bindings in binding table. Also used for returning results and errors from binding procedures. Tk_BindingTable bindingTable (in) Token for binding table; must have been returned by some previous call to Tk_CreateBindingTable. ClientData object (in) Identifies object with which binding is associated. char *eventString (in) String describing event sequence. char *script (in) Tcl script to invoke when binding triggers. int append (in) Non-zero means append script to existing script for binding, if any; zero means replace existing script with new one. XEvent *eventPtr (in) X event to match against bindings in bindingTable. Tk_Window tkwin (in) Identifier for any window on the display where the event occurred. Used to find display-related information such as key maps. int numObjects (in) Number of object identifiers pointed to by objectPtr. ClientData *objectPtr (in) Points to an array of object identifiers: bindings will be considered for each of these objects in order from first to last. DESCRIPTION These procedures provide a general-purpose mechanism for creating and invoking bindings. Bindings are organized in terms of binding tables. A binding table consists of a collection of bindings plus a history of recent events. Within a binding table, bindings are associated with objects. The meaning of an object is defined by clients of the binding package. For example, Tk keeps uses one binding table to hold all of the bindings created by the bind command. For this table, objects are pointers to strings such as window names, class names, or other binding tags such as all. Tk also keeps a separate binding table for each canvas widget, which manages bindings created by the canvas's bind widget command; within this table, an object is either a pointer to the internal structure for a canvas item or a Tk_Uid identifying a tag. The procedure Tk_CreateBindingTable creates a new binding table and associates interp with it (when bindings in the table are invoked, the scripts will be evaluated in interp). Tk_CreateBindingTable returns a token for the table, which must be used in calls to other procedures such as Tk_CreateBinding or Tk_BindEvent. Tk_DeleteBindingTable frees all of the state associated with a binding table. Once it returns the caller should not use the bindingTable token again. Tk_CreateBinding adds a new binding to an existing table. The object argument identifies the object with which the binding is to be associated, and it may be any one-word value. Typically it is a pointer to a string or data structure. The eventString argument identifies the event or sequence of events for the binding; see the documentation for the bind command for a description of its format. script is the Tcl script to be evaluated when the binding triggers. append indicates what to do if there already exists a binding for object and eventString: if append is zero then script replaces the old script; if append is non-zero then the new script is appended to the old one. Tk_CreateBinding returns an X event mask for all the events associated with the bindings. This information may be useful to invoke XSelectInput to select relevant events, or to disallow the use of certain events in bindings. If an error occurred while creating the binding (e.g., eventString refers to a non-existent event), then 0 is returned and an error message is left in interp->result. Tk_DeleteBinding removes from bindingTable the binding given by object and eventString, if such a binding exists. Tk_DeleteBinding always returns TCL_OK. In some cases it may reset interp->result to the default empty value. Tk_GetBinding returns a pointer to the script associated with eventString and object in bindingTable. If no such binding exists then NULL is returned and an error message is left in interp->result. Tk_GetAllBindings returns in interp->result a list of all the event strings for which there are bindings in bindingTable associated with object. If there are no bindings for object then an empty string is returned in interp->result. Tk_DeleteAllBindings deletes all of the bindings in bindingTable that are associated with object. Tk_BindEvent is called to process an event. It makes a copy of the event in an internal history list associated with the binding table, then it checks for bindings that match the event. Tk_BindEvent processes each of the objects pointed to by objectPtr in turn. For each object, it finds all the bindings that match the current event history, selects the most specific binding using the priority mechanism described in the documentation for bind, and invokes the script for that binding. If there are no matching bindings for a particular object, then the object is skipped. Tk_BindEvent continues through all of the objects, handling exceptions such as errors, break, and continue as described in the documentation for bind. KEYWORDS binding, event, object, script ═══ 5.3. Tk_CanvasPsY ═══ NAME Tk_CanvasPsY, Tk_CanvasPsBitmap, Tk_CanvasPsColor, Tk_CanvasPsFont, Tk_CanvasPsPath, Tk_CanvasPsStipple - utility procedures for generating Postscript for canvases SYNOPSIS #include double Tk_CanvasPsY(canvas, canvasY) int Tk_CanvasPsBitmap(interp, canvas, bitmap, x, y, width, height) int Tk_CanvasPsColor(interp, canvas, colorPtr) int Tk_CanvasPsFont(interp, canvas, fontStructPtr) Tk_CanvasPsPath(interp, canvas, coordPtr, numPoints) int Tk_CanvasPsStipple(interp, canvas, bitmap) ARGUMENTS Tk_Canvas canvas (in) A token that identifies a canvas widget for which Postscript is being generated. double canvasY (in) Y-coordinate in the space of the canvas. Tcl_Interp *interp (in/out) A Tcl interpreter; Postscript is appended to its result, or the result may be replaced with an error message. Pixmap bitmap (in) Bitmap to use for generating Postscript. int x (in) X-coordinate within bitmap of left edge of region to output. int y (in) Y-coordinate within bitmap of top edge of region to output. int width (in) Width of region of bitmap to output, in pixels. int height (in) Height of region of bitmap to output, in pixels. XColor *colorPtr (in) Information about color value to set in Postscript. XFontStruct *fontStructPtr (in) Font for which Postscript is to be generated. double *coordPtr (in) Pointer to an array of coordinates for one or more points specified in canvas coordinates. The order of values in coordPtr is x1, y1, x2, y2, x3, y3, and so on. int numPoints (in) Number of points at coordPtr. DESCRIPTION These procedures are called by canvas type managers to carry out common functions related to generating Postscript. Most of the procedures take a canvas argument, which refers to a canvas widget for which Postscript is being generated. Tk_CanvasY takes as argument a y-coordinate in the space of a canvas and returns the value that should be used for that point in the Postscript currently being generated for canvas. Y coordinates require transformation because Postscript uses an origin at the lower-left corner whereas X uses an origin at the upper-left corner. Canvas x coordinates can be used directly in Postscript without transformation. Tk_CanvasPsBitmap generates Postscript to describe a region of a bitmap. The Postscript is generated in proper image data format for Postscript, i.e., as data between angle brackets, one bit per pixel. The Postscript is appended to interp->result and TCL_OK is returned unless an error occurs, in which case TCL_ERROR is returned and interp->result is overwritten with an error message. Tk_CanvasPsColor generates Postscript to set the current color to correspond to its colorPtr argument, taking into account any color map specified in the postscript command. It appends the Postscript to interp->result and returns TCL_OK unless an error occurs, in which case TCL_ERROR is returned and interp->result is overwritten with an error message. Tk_CanvasPsFont generates Postscript that sets the current font to match fontStructPtr as closely as possible. Tk_CanvasPsFont takes into account any font map specified in the postscript command, and it does the best it can at mapping X fonts to Postscript fonts. It appends the Postscript to interp->result and returns TCL_OK unless an error occurs, in which case TCL_ERROR is returned and interp->result is overwritten with an error message. Tk_CanvasPsPath generates Postscript to set the current path to the set of points given by coordPtr and numPoints. It appends the resulting Postscript to interp->result. Tk_CanvasPsStipple generates Postscript that will fill the current path in stippled fashion. It uses bitmap as the stipple pattern and the current Postscript color; ones in the stipple bitmap are drawn in the current color, and zeroes are not drawn at all. The Postscript is appended to interp->result and TCL_OK is returned, unless an error occurs, in which case TCL_ERROR is returned and interp->result is overwritten with an error message. KEYWORDS bitmap, canvas, color, font, path, Postscript, stipple ═══ 5.4. Tk_CanvasTkwin ═══ NAME Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption - utility procedures for canvas type managers SYNOPSIS #include Tk_Window Tk_CanvasTkwin(canvas) int Tk_CanvasGetCoord(interp, canvas, string, doublePtr) Tk_CanvasDrawableCoords(canvas, x, y, drawableXPtr, drawableYPtr) Tk_CanvasSetStippleOrigin(canvas, gc) Tk_CanvasWindowCoords(canvas, x, y, screenXPtr, screenYPtr) Tk_CanvasEventuallyRedraw(canvas, x1, y1, x2, y2) Tk_OptionParseProc *Tk_CanvasTagsParseProc; Tk_OptionPrintProc *Tk_CanvasTagsPrintProc; ARGUMENTS Tk_Canvas canvas (in) A token that identifies a canvas widget. Tcl_Interp *interp (in/out) Interpreter to use for error reporting. char *string (in) Textual description of a canvas coordinate. double *doublePtr (out) Points to place to store a converted coordinate. double x (in) An x coordinate in the space of the canvas. double y (in) A y coordinate in the space of the canvas. short *drawableXPtr (out) Pointer to a location in which to store an x coordinate in the space of the drawable currently being used to redisplay the canvas. short *drawableYPtr (out) Pointer to a location in which to store a y coordinate in the space of the drawable currently being used to redisplay the canvas. GC gc (out) Graphics context to modify. short *screenXPtr (out) Points to a location in which to store the screen coordinate in the canvas window that corresponds to x. short *screenYPtr (out) Points to a location in which to store the screen coordinate in the canvas window that corresponds to y. int x1 (in) Left edge of the region that needs redisplay. Only pixels at or to the right of this coordinate need to be redisplayed. int y1 (in) Top edge of the region that needs redisplay. Only pixels at or below this coordinate need to be redisplayed. int x2 (in) Right edge of the region that needs redisplay. Only pixels to the left of this coordinate need to be redisplayed. int y2 (in) Bottom edge of the region that needs redisplay. Only pixels above this coordinate need to be redisplayed. DESCRIPTION These procedures are called by canvas type managers to perform various utility functions. Tk_CanvasTkwin returns the Tk_Window associated with a particular canvas. Tk_CanvasGetCoord translates a string specification of a coordinate (such as 2p or 1.6c) into a double-precision canvas coordinate. If string is a valid coordinate description then Tk_CanvasGetCoord stores the corresponding canvas coordinate at *doublePtr and returns TCL_OK. Otherwise it stores an error message in interp->result and returns TCL_ERROR. Tk_CanvasDrawableCoords is called by type managers during redisplay to compute where to draw things. Given x and y coordinates in the space of the canvas, Tk_CanvasDrawableCoords computes the corresponding pixel in the drawable that is currently being used for redisplay; it returns those coordinates in *drawableXPtr and *drawableYPtr. This procedure should not be invoked except during redisplay. Tk_CanvasSetStippleOrigin is also used during redisplay. It sets the stipple origin in gc so that stipples drawn with gc in the current offscreen pixmap will line up with stipples drawn with origin (0,0) in the canvas's actual window. Tk_CanvasSetStippleOrigin is needed in order to guarantee that stipple patterns line up properly when the canvas is redisplayed in small pieces. Redisplays are carried out in double-buffered fashion where a piece of the canvas is redrawn in an offscreen pixmap and then copied back onto the screen. In this approach the stipple origins in graphics contexts need to be adjusted during each redisplay to compensate for the position of the off-screen pixmap relative to the window. If an item is being drawn with stipples, its type manager typically calls Tk_CanvasSetStippleOrigin just before using gc to draw something; after it is finished drawing, the type manager calls XSetTSOrigin to restore the origin in gc back to (0,0) (the restore is needed because graphics contexts are shared, so they cannot be modified permanently). Tk_CanvasWindowCoords is similar to Tk_CanvasDrawableCoords except that it returns coordinates in the canvas's window on the screen, instead of coordinates in an off-screen pixmap. Tk_CanvasEventuallyRedraw may be invoked by a type manager to inform Tk that a portion of a canvas needs to be redrawn. The x1, y1, x2, and y2 arguments specify the region that needs to be redrawn, in canvas coordinates. Type managers rarely need to invoke Tk_CanvasEventuallyRedraw, since Tk can normally figure out when an item has changed and make the redisplay request on its behalf (this happens, for example whenever Tk calls a configureProc or scaleProc). The only time that a type manager needs to call Tk_CanvasEventuallyRedraw is if an item has changed on its own without being invoked through one of the procedures in its Tk_ItemType; this could happen, for example, in an image item if the image is modified using image commands. Tk_CanvasTagsParseProc and Tk_CanvasTagsPrintProc are procedures that handle the -tags option for canvas items. The code of a canvas type manager won't call these procedures directly, but will use their addresses to create a Tk_CustomOption structure for the -tags option. The code typically looks like this: static Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc, Tk_CanvasTagsPrintProc, (ClientData) NULL }; static Tk_ConfigSpec configSpecs[] = { ... {TK_CONFIG_CUSTOM, "-tags", (char *) NULL, (char *) NULL, (char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOption}, ... }; KEYWORDS canvas, focus, item type, redisplay, selection, type manager ═══ 5.5. Tk_CanvasTextInfo ═══ NAME Tk_CanvasTextInfo - additional information for managing text items in canvases SYNOPSIS #include Tk_CanvasTextInfo * Tk_CanvasGetTextInfo(canvas) ARGUMENTS Tk_Canvas canvas (in) A token that identifies a particular canvas widget. DESCRIPTION Textual canvas items are somewhat more complicated to manage than other items, due to things like the selection and the input focus. Tk_CanvasGetTextInfo may be invoked by a type manager to obtain additional information needed for items that display text. The return value from Tk_CanvasGetTextInfo is a pointer to a structure that is shared between Tk and all the items that display text. The structure has the following form: typedef struct Tk_CanvasTextInfo { Tk_3DBorder selBorder; int selBorderWidth; XColor *selFgColorPtr; Tk_Item *selItemPtr; int selectFirst; int selectLast; Tk_Item *anchorItemPtr; int selectAnchor; Tk_3DBorder insertBorder; int insertWidth; int insertBorderWidth; Tk_Item *focusItemPtr; int gotFocus; int cursorOn; } Tk_CanvasTextInfo; The selBorder field identifies a Tk_3DBorder that should be used for drawing the background under selected text. selBorderWidth gives the width of the raised border around selected text, in pixels. selFgColorPtr points to an XColor that describes the foreground color to be used when drawing selected text. selItemPtr points to the item that is currently selected, or NULL if there is no item selected or if the canvas doesn't have the selection. selectFirst and selectLast give the indices of the first and last selected characters in selItemPtr, as returned by the indexProc for that item. anchorItemPtr points to the item that currently has the selection anchor; this is not necessarily the same as selItemPtr. selectAnchor is an index that identifies the anchor position within anchorItemPtr. insertBorder contains a Tk_3DBorder to use when drawing the insertion cursor; insertWidth gives the total width of the insertion cursor in pixels, and insertBorderWidth gives the width of the raised border around the insertion cursor. focusItemPtr identifies the item that currently has the input focus, or NULL if there is no such item. gotFocus is 1 if the canvas widget has the input focus and 0 otherwise. cursorOn is 1 if the insertion cursor should be drawn in focusItemPtr and 0 if it should not be drawn; this field is toggled on and off by Tk to make the cursor blink. The structure returned by Tk_CanvasGetTextInfo is shared between Tk and the type managers; typically the type manager calls Tk_CanvasGetTextInfo once when an item is created and then saves the pointer in the item's record. Tk will update information in the Tk_CanvasTextInfo; for example, a configure widget command might change the selBorder field, or a select widget command might change the selectFirst field, or Tk might change cursorOn in order to make the insertion cursor flash on and off during successive redisplays. Type managers should treat all of the fields of the Tk_CanvasTextInfo structure as read-only, except for selItemPtr, selectFirst, selectLast, and selectAnchor. Type managers may change selectFirst, selectLast, and selectAnchor to adjust for insertions and deletions in the item (but only if the item is the current owner of the selection or anchor, as determined by selItemPtr or anchorItemPtr). If all of the selected text in the item is deleted, the item should set selItemPtr to NULL to indicate that there is no longer a selection. KEYWORDS canvas, focus, insertion cursor, selection, selection anchor, text ═══ 5.6. Tk_ClipboardClear ═══ NAME Tk_ClipboardClear, Tk_ClipboardAppend - Manage the clipboard SYNOPSIS #include int Tk_ClipboardClear(interp, tkwin) int Tk_ClipboardAppend(interp, tkwin, target, format, buffer) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for reporting errors. Tk_Window tkwin (in) Window that determines which display's clipboard to manipulate. Atom target (in) Conversion type for this clipboard item; has same meaning as target argument to Tk_CreateSelHandler. Atom format (in) Representation to use when data is retrieved; has same meaning as format argument to Tk_CreateSelHandler. char *buffer (in) Null terminated string containing the data to be appended to the clipboard. DESCRIPTION These two procedures manage the clipboard for Tk. The clipboard is typically managed by calling Tk_ClipboardClear once, then calling Tk_ClipboardAppend to add data for any number of targets. Tk_ClipboardClear claims the CLIPBOARD selection and frees any data items previously stored on the clipboard in this application. It normally returns TCL_OK, but if an error occurs it returns TCL_ERROR and leaves an error message in interp->result. Tk_ClipboardClear must be called before a sequence of Tk_ClipboardAppend calls can be issued. Tk_ClipboardAppend appends a buffer of data to the clipboard. The first buffer for a given target determines the format for that target. Any successive appends for that target must have the same format or an error will be returned. Tk_ClipboardAppend returns TCL_OK if the buffer is successfully copied onto the clipboard. If the clipboard is not currently owned by the application, either because Tk_ClipboardClear has not been called or because ownership of the clipboard has changed since the last call to Tk_ClipboardClear, Tk_ClipboardAppend returns TCL_ERROR and leaves an error message in interp->result. In order to guarantee atomicity, no event handling should occur between Tk_ClipboardClear and the following Tk_ClipboardAppend calls (otherwise someone could retrieve a partially completed clipboard or claim ownership away from this application). Tk_ClipboardClear may invoke callbacks, including arbitrary Tcl scripts, as a result of losing the CLIPBOARD selection, so any calling function should take care to be reentrant at the point Tk_ClipboardClear is invoked. KEYWORDS append, clipboard, clear, format, type ═══ 5.7. Tk_ClearSelection ═══ NAME Tk_ClearSelection - Deselect a selection SYNOPSIS #include Tk_ClearSelection(tkwin, selection) ARGUMENTS Tk_Window tkwin (in) The selection will be cleared from the display containing this window. Atom selection (in) The name of selection to be cleared. DESCRIPTION Tk_ClearSelection cancels the selection specified by the atom selection for the display containing tkwin. The selection need not be in tkwin itself or even in tkwin's application. If there is a window anywhere on tkwin's display that owns selection, the window will be notified and the selection will be cleared. If there is no owner for selection on the display, then the procedure has no effect. KEYWORDS clear, selection ═══ 5.8. Tk_ConfigureWidget ═══ NAME Tk_ConfigureWidget, Tk_Offset, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions - process configuration options for widgets SYNOPSIS #include int Tk_ConfigureWidget(interp, tkwin, specs, argc, argv, widgRec, flags) int Tk_Offset(type, field) int Tk_ConfigureInfo(interp, tkwin, specs, widgRec, argvName, flags) int Tk_FreeOptions(specs, widgRec, display, flags) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for returning error messages. Tk_Window tkwin (in) Window used to represent widget (needed to set up X resources). Tk_ConfigSpec *specs (in) Pointer to table specifying legal configuration options for this widget. int argc (in) Number of arguments in argv. char **argv (in) Command-line options for configuring widget. char *widgRec (in/out) Points to widget record structure. Fields in this structure get modified by Tk_ConfigureWidget to hold configuration information. int flags (in) If non-zero, then it specifies an OR-ed combination of flags that control the processing of configuration information. TK_CONFIG_ARGV_ONLY causes the option database and defaults to be ignored, and flag bits TK_CONFIG_USER_BIT and higher are used to selectively disable entries in specs. type name type (in) The name of the type of a widget record. field name field (in) The name of a field in records of type type. char *argvName (in) The name used on Tcl command lines to refer to a particular option (e.g. when creating a widget or invoking the configure widget command). If non-NULL, then information is returned only for this option. If NULL, then information is returned for all available options. Display *display (in) Display containing widget whose record is being freed; needed in order to free up resources. DESCRIPTION Tk_ConfigureWidget is called to configure various aspects of a widget, such as colors, fonts, border width, etc. It is intended as a convenience procedure to reduce the amount of code that must be written in individual widget managers to handle configuration information. It is typically invoked when widgets are created, and again when the configure command is invoked for a widget. Although intended primarily for widgets, Tk_ConfigureWidget can be used in other situations where argc-argv information is to be used to fill in a record structure, such as configuring graphical elements for a canvas widget or entries of a menu. Tk_ConfigureWidget processes a table specifying the configuration options that are supported (specs) and a collection of command-line arguments (argc and argv) to fill in fields of a record (widgRec). It uses the option database and defaults specified in specs to fill in fields of widgRec that are not specified in argv. Tk_ConfigureWidget normally returns the value TCL_OK; in this case it does not modify interp. If an error occurs then TCL_ERROR is returned and Tk_ConfigureWidget will leave an error message in interp->result in the standard Tcl fashion. In the event of an error return, some of the fields of widgRec could already have been set, if configuration information for them was successfully processed before the error occurred. The other fields will be set to reasonable initial values so that Tk_FreeOptions can be called for cleanup. The specs array specifies the kinds of configuration options expected by the widget. Each of its entries specifies one configuration option and has the following structure: typedef struct { int type; char *argvName; char *dbName; char *dbClass; char *defValue; int offset; int specFlags; Tk_CustomOption *customPtr; } Tk_ConfigSpec; The type field indicates what type of configuration option this is (e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for an integer value). The type field indicates how to use the value of the option (more on this below). The argvName field is a string such as "-font" or "-bg", which is compared with the values in argv (if argvName is NULL it means this is a grouped entry; see GROUPED ENTRIES below). The dbName and dbClass fields are used to look up a value for this option in the option database. The defValue field specifies a default value for this configuration option if no value is specified in either argv or the option database. Offset indicates where in widgRec to store information about this option, and specFlags contains additional information to control the processing of this configuration option (see FLAGS below). The last field, customPtr, is only used if type is TK_CONFIG_CUSTOM; see CUSTOM OPTION TYPES below. Tk_ConfigureWidget first processes argv to see which (if any) configuration options are specified there. Argv must contain an even number of fields; the first of each pair of fields must match the argvName of some entry in specs (unique abbreviations are acceptable), and the second field of the pair contains the value for that configuration option. If there are entries in spec for which there were no matching entries in argv, Tk_ConfigureWidget uses the dbName and dbClass fields of the specs entry to probe the option database; if a value is found, then it is used as the value for the option. Finally, if no entry is found in the option database, the defValue field of the specs entry is used as the value for the configuration option. If the defValue is NULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in flags, then there is no default value and this specs entry will be ignored if no value is specified in argv or the option database. Once a string value has been determined for a configuration option, Tk_ConfigureWidget translates the string value into a more useful form, such as a color if type is TK_CONFIG_COLOR or an integer if type is TK_CONFIG_INT. This value is then stored in the record pointed to by widgRec. This record is assumed to contain information relevant to the manager of the widget; its exact type is unknown to Tk_ConfigureWidget. The offset field of each specs entry indicates where in widgRec to store the information about this configuration option. You should use the Tk_Offset macro to generate offset values (see below for a description of Tk_Offset). The location indicated by widgRec and offset will be referred to as the "target" in the descriptions below. The type field of each entry in specs determines what to do with the string value of that configuration option. The legal values for type, and the corresponding actions, are: TK_CONFIG_ACTIVE_CURSOR The value must be an ASCII string identifying a cursor in a form suitable for passing to Tk_GetCursor. The value is converted to a Tk_Cursor by calling Tk_GetCursor and the result is stored in the target. In addition, the resulting cursor is made the active cursor for tkwin by calling XDefineCursor. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target and tkwin's active cursor will be set to None. If the previous value of the target wasn't None, then it is freed by passing it to Tk_FreeCursor. TK_CONFIG_ANCHOR The value must be an ASCII string identifying an anchor point in one of the ways accepted by Tk_GetAnchor. The string is converted to a Tk_Anchor by calling Tk_GetAnchor and the result is stored in the target. TK_CONFIG_BITMAP The value must be an ASCII string identifying a bitmap in a form suitable for passing to Tk_GetBitmap. The value is converted to a Pixmap by calling Tk_GetBitmap and the result is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target is set to None. If the previous value of the target wasn't None, then it is freed by passing it to Tk_FreeBitmap. TK_CONFIG_BOOLEAN The value must be an ASCII string specifying a boolean value. Any of the values "true", "yes", "on", or "1", or an abbreviation of one of these values, means true; any of the values "false", "no", "off", or "0", or an abbreviation of one of these values, means false. The target is expected to be an integer; for true values it will be set to 1 and for false values it will be set to 0. TK_CONFIG_BORDER The value must be an ASCII string identifying a border color in a form suitable for passing to Tk_Get3DBorder. The value is converted to a (Tk_3DBorder *) by calling Tk_Get3DBorder and the result is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target wasn't NULL, then it is freed by passing it to Tk_Free3DBorder. TK_CONFIG_CAP_STYLE The value must be an ASCII string identifying a cap style in one of the ways accepted by Tk_GetCapStyle. The string is converted to an integer value corresponding to the cap style by calling Tk_GetCapStyle and the result is stored in the target. TK_CONFIG_COLOR The value must be an ASCII string identifying a color in a form suitable for passing to Tk_GetColor. The value is converted to an (XColor *) by calling Tk_GetColor and the result is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target will be set to None. If the previous value of the target wasn't NULL, then it is freed by passing it to Tk_FreeColor. TK_CONFIG_CURSOR This option is identical to TK_CONFIG_ACTIVE_CURSOR except that the new cursor is not made the active one for tkwin. TK_CONFIG_CUSTOM This option allows applications to define new option types. The customPtr field of the entry points to a structure defining the new option type. See the section CUSTOM OPTION TYPES below for details. TK_CONFIG_DOUBLE The value must be an ASCII floating-point number in the format accepted by strtol. The string is converted to a double value, and the value is stored in the target. TK_CONFIG_END Marks the end of the table. The last entry in specs must have this type; all of its other fields are ignored and it will never match any arguments. TK_CONFIG_FONT The value must be an ASCII string identifying a font in a form suitable for passing to Tk_GetFontStruct. The value is converted to an (XFontStruct *) by calling Tk_GetFontStruct and the result is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target wasn't NULL, then it is freed by passing it to Tk_FreeFontStruct. TK_CONFIG_INT The value must be an ASCII integer string in the format accepted by strtol (e.g. "0" and "0x" prefixes may be used to specify octal or hexadecimal numbers, respectively). The string is converted to an integer value and the integer is stored in the target. TK_CONFIG_JOIN_STYLE The value must be an ASCII string identifying a join style in one of the ways accepted by Tk_GetJoinStyle. The string is converted to an integer value corresponding to the join style by calling Tk_GetJoinStyle and the result is stored in the target. TK_CONFIG_JUSTIFY The value must be an ASCII string identifying a justification method in one of the ways accepted by Tk_GetJustify. The string is converted to a Tk_Justify by calling Tk_GetJustify and the result is stored in the target. TK_CONFIG_MM The value must specify a screen distance in one of the forms acceptable to Tk_GetScreenMM. The string is converted to double-precision floating-point distance in millimeters and the value is stored in the target. TK_CONFIG_PIXELS The value must specify screen units in one of the forms acceptable to Tk_GetPixels. The string is converted to an integer distance in pixels and the value is stored in the target. TK_CONFIG_RELIEF The value must be an ASCII string identifying a relief in a form suitable for passing to Tk_GetRelief. The value is converted to an integer relief value by calling Tk_GetRelief and the result is stored in the target. TK_CONFIG_STRING A copy of the value is made by allocating memory space with malloc and copying the value into the dynamically-allocated space. A pointer to the new string is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target wasn't NULL, then it is freed by passing it to free. TK_CONFIG_SYNONYM This type value identifies special entries in specs that are synonyms for other entries. If an argv value matches the argvName of a TK_CONFIG_SYNONYM entry, the entry isn't used directly. Instead, Tk_ConfigureWidget searches specs for another entry whose argvName is the same as the dbName field in the TK_CONFIG_SYNONYM entry; this new entry is used just as if its argvName had matched the argv value. The synonym mechanism allows multiple argv values to be used for a single configuration option, such as "-background" and "-bg". TK_CONFIG_UID The value is translated to a Tk_Uid (by passing it to Tk_GetUid). The resulting value is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags and the value is an empty string then the target will be set to NULL. TK_CONFIG_WINDOW The value must be a window path name. It is translated to a Tk_Window token and the token is stored in the target. GROUPED ENTRIES In some cases it is useful to generate multiple resources from a single configuration value. For example, a color name might be used both to generate the background color for a widget (using TK_CONFIG_COLOR) and to generate a 3-D border to draw around the widget (using TK_CONFIG_BORDER). In cases like this it is possible to specify that several consecutive entries in specs are to be treated as a group. The first entry is used to determine a value (using its argvName, dbName, dbClass, and defValue fields). The value will be processed several times (one for each entry in the group), generating multiple different resources and modifying multiple targets within widgRec. Each of the entries after the first must have a NULL value in its argvName field; this indicates that the entry is to be grouped with the entry that precedes it. Only the type and offset fields are used from these follow-on entries. FLAGS The flags argument passed to Tk_ConfigureWidget is used in conjunction with the specFlags fields in the entries of specs to provide additional control over the processing of configuration options. These values are used in three different ways as described below. First, if the flags argument to Tk_ConfigureWidget has the TK_CONFIG_ARGV_ONLY bit set (i.e., flags | TK_CONFIG_ARGV_ONLY != 0), then the option database and defValue fields are not used. In this case, if an entry in specs doesn't match a field in argv then nothing happens: the corresponding target isn't modified. This feature is useful when the goal is to modify certain configuration options while leaving others in their current state, such as when a configure widget command is being processed. Second, the specFlags field of an entry in specs may be used to control the processing of that entry. Each specFlags field may consists of an OR-ed combination of the following values: TK_CONFIG_COLOR_ONLY If this bit is set then the entry will only be considered if the display for tkwin has more than one bit plane. If the display is monochromatic then this specs entry will be ignored. TK_CONFIG_MONO_ONLY If this bit is set then the entry will only be considered if the display for tkwin has exactly one bit plane. If the display is not monochromatic then this specs entry will be ignored. TK_CONFIG_NULL_OK This bit is only relevant for some types of entries (see the descriptions of the various entry types above). If this bit is set, it indicates that an empty string value for the field is acceptable and if it occurs then the target should be set to NULL or None, depending on the type of the target. This flag is typically used to allow a feature to be turned off entirely, e.g. set a cursor value to None so that a window simply inherits its parent's cursor. If this bit isn't set then empty strings are processed as strings, which generally results in an error. TK_CONFIG_DONT_SET_DEFAULT If this bit is one, it means that the defValue field of the entry should only be used for returning the default value in Tk_ConfigureInfo. In calls to Tk_ConfigureWidget no default will be supplied for entries with this flag set; it is assumed that the caller has already supplied a default value in the target location. This flag provides a performance optimization where it is expensive to process the default string: the client can compute the default once, save the value, and provide it before calling Tk_ConfigureWidget. TK_CONFIG_OPTION_SPECIFIED This bit is set and cleared by Tk_ConfigureWidget. Whenever Tk_ConfigureWidget returns, this bit will be set in all the entries where a value was specified in argv. It will be zero in all other entries. This bit provides a way for clients to determine which values actually changed in a call to Tk_ConfigureWidget. The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically used to specify different default values for monochrome and color displays. This is done by creating two entries in specs that are identical except for their defValue and specFlags fields. One entry should have the value TK_CONFIG_MONO_ONLY in its specFlags and the default value for monochrome displays in its defValue; the other entry entry should have the value TK_CONFIG_COLOR_ONLY in its specFlags and the appropriate defValue for color displays. Third, it is possible to use flags and specFlags together to selectively disable some entries. This feature is not needed very often. It is useful in cases where several similar kinds of widgets are implemented in one place. It allows a single specs table to be created with all the configuration options for all the widget types. When processing a particular widget type, only entries relevant to that type will be used. This effect is achieved by setting the high-order bits (those in positions equal to or greater than TK_CONFIG_USER_BIT) in specFlags values or in flags. In order for a particular entry in specs to be used, its high-order bits must match exactly the high-order bits of the flags value passed to Tk_ConfigureWidget. If a specs table is being used for N different widget types, then N of the high-order bits will be used. Each specs entry will have one of more of those bits set in its specFlags field to indicate the widget types for which this entry is valid. When calling Tk_ConfigureWidget, flags will have a single one of these bits set to select the entries for the desired widget type. For a working example of this feature, see the code in tkButton.c. TK_OFFSET The Tk_Offset macro is provided as a safe way of generating the offset values for entries in Tk_ConfigSpec structures. It takes two arguments: the name of a type of record, and the name of a field in that record. It returns the byte offset of the named field in records of the given type. TK_CONFIGUREINFO The Tk_ConfigureInfo procedure may be used to obtain information about one or all of the options for a given widget. Given a token for a window (tkwin), a table describing the configuration options for a class of widgets (specs), a pointer to a widget record containing the current information for a widget (widgRec), and a NULL argvName argument, Tk_ConfigureInfo generates a string describing all of the configuration options for the window. The string is placed in interp->result. Under normal circumstances it returns TCL_OK; if an error occurs then it returns TCL_ERROR and interp->result contains an error message. If argvName is NULL, then the value left in interp->result by Tk_ConfigureInfo consists of a list of one or more entries, each of which describes one configuration option (i.e. one entry in specs). Each entry in the list will contain either two or five values. If the corresponding entry in specs has type TK_CONFIG_SYNONYM, then the list will contain two values: the argvName for the entry and the dbName (synonym name). Otherwise the list will contain five values: argvName, dbName, dbClass, defValue, and current value. The current value is computed from the appropriate field of widgRec by calling procedures like Tk_NameOfColor. If the argvName argument to Tk_ConfigureInfo is non-NULL, then it indicates a single option, and information is returned only for that option. The string placed in interp->result will be a list containing two or five values as described above; this will be identical to the corresponding sublist that would have been returned if argvName had been NULL. The flags argument to Tk_ConfigureInfo is used to restrict the specs entries to consider, just as for Tk_ConfigureWidget. TK_CONFIGUREVALUE Tk_ConfigureValue takes arguments similar to Tk_ConfigureInfo; instead of returning a list of values, it just returns the current value of the option given by argvName (argvName must not be NULL). The value is returned in interp->result and TCL_OK is normally returned as the procedure's result. If an error occurs in Tk_ConfigureValue (e.g., argvName is not a valid option name), TCL_ERROR is returned and an error message is left in interp->result. This procedure is typically called to implement cget widget commands. TK_FREEOPTIONS The Tk_FreeOptions procedure may be invoked during widget cleanup to release all of the resources associated with configuration options. It scans through specs and for each entry corresponding to a resource that must be explicitly freed (e.g. those with type TK_CONFIG_COLOR), it frees the resource in the widget record. If the field in the widget record doesn't refer to a resource (e.g. it contains a null pointer) then no resource is freed for that entry. After freeing a resource, Tk_FreeOptions sets the corresponding field of the widget record to null. CUSTOM OPTION TYPES Applications can extend the built-in configuration types with additional configuration types by writing procedures to parse and print options of the a type and creating a structure pointing to those procedures: typedef struct Tk_CustomOption { Tk_OptionParseProc *parseProc; Tk_OptionPrintProc *printProc; ClientData clientData; } Tk_CustomOption; typedef int Tk_OptionParseProc( ClientData clientData, Tcl_Interp *interp, Tk_Window tkwin, char *value, char *widgRec, int offset); typedef char *Tk_OptionPrintProc( ClientData clientData, Tk_Window tkwin, char *widgRec, int offset, Tcl_FreeProc **freeProcPtr); The Tk_CustomOption structure contains three fields, which are pointers to the two procedures and a clientData value to be passed to those procedures when they are invoked. The clientData value typically points to a structure containing information that is needed by the procedures when they are parsing and printing options. The parseProc procedure is invoked by Tk_ConfigureWidget to parse a string and store the resulting value in the widget record. The clientData argument is a copy of the clientData field in the Tk_CustomOption structure. The interp argument points to a Tcl interpreter used for error reporting. Tkwin is a copy of the tkwin argument to Tk_ConfigureWidget. The value argument is a string describing the value for the option; it could have been specified explicitly in the call to Tk_ConfigureWidget or it could come from the option database or a default. Value will never be a null pointer but it may point to an empty string. RecordPtr is the same as the widgRec argument to Tk_ConfigureWidget; it points to the start of the widget record to modify. The last argument, offset, gives the offset in bytes from the start of the widget record to the location where the option value is to be placed. The procedure should translate the string to whatever form is appropriate for the option and store the value in the widget record. It should normally return TCL_OK, but if an error occurs in translating the string to a value then it should return TCL_ERROR and store an error message in interp->result. The printProc procedure is called by Tk_ConfigureInfo to produce a string value describing an existing option. Its clientData, tkwin, widgRec, and offset arguments all have the same meaning as for Tk_OptionParseProc procedures. The printProc procedure should examine the option whose value is stored at offset in widgRec, produce a string describing that option, and return a pointer to the string. If the string is stored in dynamically-allocated memory, then the procedure must set *freeProcPtr to the address of a procedure to call to free the string's memory; Tk_ConfigureInfo will call this procedure when it is finished with the string. If the result string is stored in static memory then printProc need not do anything with the freeProcPtr argument. Once parseProc and printProc have been defined and a Tk_CustomOption structure has been created for them, options of this new type may be manipulated with Tk_ConfigSpec entries whose type fields are TK_CONFIG_CUSTOM and whose customPtr fields point to the Tk_CustomOption structure. EXAMPLES Although the explanation of Tk_ConfigureWidget is fairly complicated, its actual use is pretty straightforward. The easiest way to get started is to copy the code from an existing widget. The library implementation of frames (tkFrame.c) has a simple configuration table, and the library implementation of buttons (tkButton.c) has a much more complex table that uses many of the fancy specFlags mechanisms. KEYWORDS anchor, bitmap, boolean, border, cap style, color, configuration options, cursor, custom, double, font, integer, join style, justify, millimeters, pixels, relief, synonym, uid ═══ 5.9. Tk_ConfigureWindow ═══ NAME Tk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth, Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorder, Tk_SetWindowBorderPixmap, Tk_SetWindowColormap, Tk_DefineCursor, Tk_UndefineCursor - change window configuration or attributes SYNOPSIS #include Tk_ConfigureWindow(tkwin, valueMask, valuePtr) Tk_MoveWindow(tkwin, x, y) Tk_ResizeWindow(tkwin, width, height) Tk_MoveResizeWindow(tkwin, x, y, width, height) Tk_SetWindowBorderWidth(tkwin, borderWidth) Tk_ChangeWindowAttributes(tkwin, valueMask, attsPtr) Tk_SetWindowBackground(tkwin, pixel) Tk_SetWindowBackgroundPixmap(tkwin, pixmap) Tk_SetWindowBorder(tkwin, pixel) Tk_SetWindowBorderPixmap(tkwin, pixmap) Tk_SetWindowColormap(tkwin, colormap) Tk_DefineCursor(tkwin, cursor) Tk_UndefineCursor(tkwin) ARGUMENTS Tk_Window tkwin (in) Token for window. unsigned int valueMask (in) OR-ed mask of values like CWX or CWBorderPixel, indicating which fields of *valuePtr or *attsPtr to use. XWindowChanges *valuePtr (in) Points to a structure containing new values for the configuration parameters selected by valueMask. Fields not selected by valueMask are ignored. int x (in) New x-coordinate for tkwin's top left pixel (including border, if any) within tkwin's parent. int y (in) New y-coordinate for tkwin's top left pixel (including border, if any) within tkwin's parent. int width (in) New width for tkwin (interior, not including border). int height (in) New height for tkwin (interior, not including border). int borderWidth (in) New width for tkwin's border. XSetWindowAttributes *attsPtr (in) Points to a structure containing new values for the attributes given by the valueMask argument. Attributes not selected by valueMask are ignored. unsigned long pixel (in) New background or border color for window. Pixmap pixmap (in) New pixmap to use for background or border of tkwin. WARNING: cannot necessarily be deleted immediately, as for Xlib calls. See note below. Colormap colormap (in) New colormap to use for tkwin. Tk_Cursor cursor (in) New cursor to use for tkwin. If None is specified, then tkwin will not have its own cursor; it will use the cursor of its parent. DESCRIPTION These procedures are analogous to the X library procedures with similar names, such as XConfigureWindow. Each one of the above procedures calls the corresponding X procedure and also saves the configuration information in Tk's local structure for the window. This allows the information to be retrieved quickly by the application (using macros such as Tk_X and Tk_Height) without having to contact the X server. In addition, if no X window has actually been created for tkwin yet, these procedures do not issue X operations or cause event handlers to be invoked; they save the information in Tk's local structure for the window; when the window is created later, the saved information will be used to configure the window. See the X library documentation for details on what these procedures do and how they use their arguments. In the procedures Tk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, and Tk_SetWindowBorderWidth, if tkwin is an internal window then event handlers interested in configure events are invoked immediately, before the procedure returns. If tkwin is a top-level window then the event handlers will be invoked later, after X has seen the request and returned an event for it. Applications using Tk should never call procedures like XConfigureWindow directly; they should always use the corresponding Tk procedures. The size and location of a window should only be modified by the appropriate geometry manager for that window and never by a window itself (but see Tk_MoveToplevelWindow for moving a top-level window). You may not use Tk_ConfigureWindow to change the stacking order of a window (valueMask may not contain the CWSibling or CWStackMode bits). To change the stacking order, use the procedure Tk_RestackWindow. The procedure Tk_SetWindowColormap will automatically add tkwin to the TK_COLORMAP_WINDOWS property of its nearest top-level ancestor if the new colormap is different from that of tkwin's parent and tkwin isn't already in the TK_COLORMAP_WINDOWS property. BUGS Tk_SetWindowBackgroundPixmap and Tk_SetWindowBorderPixmap differ slightly from their Xlib counterparts in that the pixmap argument may not necessarily be deleted immediately after calling one of these procedures. This is because tkwin's window may not exist yet at the time of the call, in which case pixmap is merely saved and used later when tkwin's window is actually created. If you wish to delete pixmap, then call Tk_MakeWindowExist first to be sure that tkwin's window exists and pixmap has been passed to the X server. A similar problem occurs for the cursor argument passed to Tk_DefineCursor. The solution is the same as for pixmaps above: call Tk_MakeWindowExist before freeing the cursor. SEE ALSO Tk_MoveToplevelWindow, Tk_RestackWindow KEYWORDS attributes, border, color, configure, height, pixel, pixmap, width, window, x, y ═══ 5.10. Tk_CoordsToWindow ═══ NAME Tk_CoordsToWindow - Find window containing a point SYNOPSIS #include Tk_Window Tk_CoordsToWindow(rootX, rootY, tkwin) ARGUMENTS int rootX (in) X-coordinate (in root window coordinates). int rootY (in) Y-coordinate (in root window coordinates). Tk_Window tkwin (in) Token for window that identifies application. DESCRIPTION Tk_CoordsToWindow locates the window that contains a given point. The point is specified in root coordinates with rootX and rootY (if a virtual-root window manager is in use then rootX and rootY are in the coordinate system of the virtual root window). The return value from the procedure is a token for the window that contains the given point. If the point is not in any window, or if the containing window is not in the same application as tkwin, then NULL is returned. The containing window is decided using the same rules that determine which window contains the mouse cursor: if a parent and a child both contain the point then the child gets preference, and if two siblings both contain the point then the highest one in the stacking order (i.e. the one that's visible on the screen) gets preference. KEYWORDS containing, coordinates, root window ═══ 5.11. Tk_CreateErrorHandler ═══ NAME Tk_CreateErrorHandler, Tk_DeleteErrorHandler - handle X protocol errors SYNOPSIS #include Tk_ErrorHandler Tk_CreateErrorHandler(display, error, request, minor, proc, clientData) Tk_DeleteErrorHandler(handler) ARGUMENTS Display *display (in) Display whose errors are to be handled. int error (in) Match only error events with this value in the error_code field. If -1, then match any error_code value. int request (in) Match only error events with this value in the request_code field. If -1, then match any request_code value. int minor (in) Match only error events with this value in the minor_code field. If -1, then match any minor_code value. Tk_ErrorProc *proc (in) Procedure to invoke whenever an error event is received for display and matches error, request, and minor. NULL means ignore any matching errors. ClientData clientData (in) Arbitrary one-word value to pass to proc. Tk_ErrorHandler handler (in) Token for error handler to delete (return value from a previous call to Tk_CreateErrorHandler). DESCRIPTION Tk_CreateErrorHandler arranges for a particular procedure (proc) to be called whenever certain protocol errors occur on a particular display (display). Protocol errors occur when the X protocol is used incorrectly, such as attempting to map a window that doesn't exist. See the Xlib documentation for XSetErrorHandler for more information on the kinds of errors that can occur. For proc to be invoked to handle a particular error, five things must occur: 1. The error must pertain to display. 2. Either the error argument to Tk_CreateErrorHandler must have been -1, or the error argument must match the error_code field from the error event. 3. Either the request argument to Tk_CreateErrorHandler must have been -1, or the request argument must match the request_code field from the error event. 4. Either the minor argument to Tk_CreateErrorHandler must have been -1, or the minor argument must match the minor_code field from the error event. 5. The protocol request to which the error pertains must have been made when the handler was active (see below for more information). Proc should have arguments and result that match the following type: typedef int Tk_ErrorProc( ClientData clientData, XErrorEvent *errEventPtr); The clientData parameter to proc is a copy of the clientData argument given to Tcl_CreateErrorHandler when the callback was created. Typically, clientData points to a data structure containing application-specific information that is needed to deal with the error. ErrEventPtr is a pointer to the X error event. The procedure proc should return an integer value. If it returns 0 it means that proc handled the error completely and there is no need to take any other action for the error. If it returns non-zero it means proc was unable to handle the error. If a value of NULL is specified for proc, all matching errors will be ignored: this will produce the same result as if a procedure had been specified that always returns 0. If more than more than one handler matches a particular error, then they are invoked in turn. The handlers will be invoked in reverse order of creation: most recently declared handler first. If any handler returns 0, then subsequent (older) handlers will not be invoked. If no handler returns 0, then Tk invokes X'es default error handler, which prints an error message and aborts the program. If you wish to have a default handler that deals with errors that no other handler can deal with, then declare it first. The X documentation states that "the error handler should not call any functions (directly or indirectly) on the display that will generate protocol requests or that will look for input events." This restriction applies to handlers declared by Tk_CreateErrorHandler; disobey it at your own risk. Tk_DeleteErrorHandler may be called to delete a previously-created error handler. The handler argument identifies the error handler, and should be a value returned by a previous call to Tk_CreateEventHandler. A particular error handler applies to errors resulting from protocol requests generated between the call to Tk_CreateErrorHandler and the call to Tk_DeleteErrorHandler. However, the actual callback to proc may not occur until after the Tk_DeleteErrorHandler call, due to buffering in the client and server. If an error event pertains to a protocol request made just before calling Tk_DeleteErrorHandler, then the error event may not have been processed before the Tk_DeleteErrorHandler call. When this situation arises, Tk will save information about the handler and invoke the handler's proc later when the error event finally arrives. If an application wishes to delete an error handler and know for certain that all relevant errors have been processed, it should first call Tk_DeleteErrorHandler and then call XSync; this will flush out any buffered requests and errors, but will result in a performance penalty because it requires communication to and from the X server. After the XSync call Tk is guaranteed not to call any error handlers deleted before the XSync call. For the Tk error handling mechanism to work properly, it is essential that application code never calls XSetErrorHandler directly; applications should use only Tk_CreateErrorHandler. KEYWORDS callback, error, event, handler ═══ 5.12. Tk_CreateGenericHandler ═══ NAME Tk_CreateGenericHandler, Tk_DeleteGenericHandler - associate procedure callback with all X events SYNOPSIS #include Tk_CreateGenericHandler(proc, clientData) Tk_DeleteGenericHandler(proc, clientData) ARGUMENTS Tk_GenericProc *proc (in) Procedure to invoke whenever any X event occurs on any display. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION Tk_CreateGenericHandler arranges for proc to be invoked in the future whenever any X event occurs. This mechanism is not intended for dispatching X events on windows managed by Tk (you should use Tk_CreateEventHandler for this purpose). Tk_CreateGenericHandler is intended for other purposes, such as tracing X events, monitoring events on windows not owned by Tk, accessing X-related libraries that were not originally designed for use with Tk, and so on. The callback to proc will be made by Tk_HandleEvent; this mechanism only works in programs that dispatch events through Tk_HandleEvent (or through other Tk procedures that call Tk_HandleEvent, such as Tk_DoOneEvent or Tk_MainLoop). Proc should have arguments and result that match the type Tk_GenericProc: typedef int Tk_GenericProc( ClientData clientData, XEvent *eventPtr); The clientData parameter to proc is a copy of the clientData argument given to Tk_CreateGenericHandler when the callback was created. Typically, clientData points to a data structure containing application-specific information about how to handle events. EventPtr is a pointer to the X event. Whenever an X event is processed by Tk_HandleEvent, proc is called. The return value from proc is normally 0. A non-zero return value indicates that the event is not to be handled further; that is, proc has done all processing that is to be allowed for the event. If there are multiple generic event handlers, each one is called for each event, in the order in which they were established. Tk_DeleteGenericHandler may be called to delete a previously-created generic event handler: it deletes each handler it finds that matches the proc and clientData arguments. If no such handler exists, then Tk_DeleteGenericHandler returns without doing anything. Although Tk supports it, it's probably a bad idea to have more than one callback with the same proc and clientData arguments. Establishing a generic event handler does nothing to ensure that the process will actually receive the X events that the handler wants to process. For example, it is the caller's responsibility to invoke XSelectInput to select the desired events, if that is necessary. KEYWORDS bind, callback, event, handler ═══ 5.13. Tk_CreateImageType ═══ NAME Tk_CreateImageType - define new kind of image SYNOPSIS #include Tk_CreateImageType(typePtr) ARGUMENTS Tk_ImageType *typePtr (in) Structure that defines the new type of image. DESCRIPTION Tk_CreateImageType is invoked to define a new kind of image. An image type corresponds to a particular value of the type argument for the image create command. There may exist any number of different image types, and new types may be defined dynamically by calling Tk_CreateImageType. For example, there might be one type for 2-color bitmaps, another for multi-color images, another for dithered images, another for video, and so on. The code that implements a new image type is called an image manager. It consists of a collection of procedures plus three different kinds of data structures. The first data structure is a Tk_ImageType structure, which contains the name of the image type and pointers to five procedures provided by the image manager to deal with images of this type: typedef struct Tk_ImageType { char *name; Tk_ImageCreateProc *createProc; Tk_ImageGetProc *getProc; Tk_ImageDisplayProc *displayProc; Tk_ImageFreeProc *freeProc; Tk_ImageDeleteProc *deleteProc; } Tk_ImageType; The fields of this structure will be described in later subsections of this entry. The second major data structure manipulated by an image manager is called an image master; it contains overall information about a particular image, such as the values of the configuration options specified in an image create command. There will usually be one of these structures for each invocation of the image create command. The third data structure related to images is an image instance. There will usually be one of these structures for each usage of an image in a particular widget. It is possible for a single image to appear simultaneously in multiple widgets, or even multiple times in the same widget. Furthermore, different instances may be on different screens or displays. The image instance data structure describes things that may vary from instance to instance, such as colors and graphics contexts for redisplay. There is usually one instance structure for each -image option specified for a widget or canvas item. The following subsections describe the fields of a Tk_ImageType in more detail. NAME typePtr->name provides a name for the image type. Once Tk_CreateImageType returns, this name may be used in image create commands to create images of the new type. If there already existed an image type by this name then the new image type replaces the old one. CREATEPROC typePtr->createProc provides the address of a procedure for Tk to call whenever image create is invoked to create an image of the new type. typePtr->createProc must match the following prototype: typedef int Tk_ImageCreateProc( Tcl_Interp *interp, char *name, int argc, char **argv, Tk_ImageType *typePtr, Tk_ImageMaster master, ClientData *masterDataPtr); The interp argument is the interpreter in which the image command was invoked, and name is the name for the new image, which was either specified explicitly in the image command or generated automatically by the image command. The argc and argv arguments describe all the configuration options for the new image (everything after the name argument to image). The master argument is a token that refers to Tk's information about this image; the image manager must return this token to Tk when invoking the Tk_ImageChanged procedure. Typically createProc will parse argc and argv and create an image master data structure for the new image. createProc may store an arbitrary one-word value at *masterDataPtr, which will be passed back to the image manager when other callbacks are invoked. Typically the value is a pointer to the master data structure for the image. If createProc encounters an error, it should leave an error message in interp->result and return TCL_ERROR; otherwise it should return TCL_OK. createProc should call Tk_ImageChanged in order to set the size of the image and request an initial redisplay. GETPROC typePtr->getProc is invoked by Tk whenever a widget calls Tk_GetImage to use a particular image. This procedure must match the following prototype: typedef ClientData Tk_ImageGetProc( Tk_Window tkwin, ClientData masterData); The tkwin argument identifies the window in which the image will be used and masterData is the value returned by createProc when the image master was created. getProc will usually create a data structure for the new instance, including such things as the resources needed to display the image in the given window. getProc returns a one-word token for the instance, which is typically the address of the instance data structure. Tk will pass this value back to the image manager when invoking its displayProc and freeProc procedures. DISPLAYPROC typePtr->displayProc is invoked by Tk whenever an image needs to be displayed (i.e., whenever a widget calls Tk_RedrawImage). displayProc must match the following prototype: typedef void Tk_ImageDisplayProc( ClientData instanceData, Display *display, Drawable drawable, int imageX, int imageY, int width, int height, int drawableX, int drawableY); The instanceData will be the same as the value returned by getProc when the instance was created. display and drawable indicate where to display the image; drawable may be a pixmap rather than the window specified to getProc (this is usually the case, since most widgets double-buffer their redisplay to get smoother visual effects). imageX, imageY, width, and height identify the region of the image that must be redisplayed. This region will always be within the size of the image as specified in the most recent call to Tk_ImageChanged. drawableX and drawableY indicate where in drawable the image should be displayed; displayProc should display the given region of the image so that point (imageX, imageY) in the image appears at (drawableX, drawableY) in drawable. FREEPROC typePtr->freeProc contains the address of a procedure that Tk will invoke when an image instance is released (i.e., when Tk_FreeImage is invoked). This can happen, for example, when a widget is deleted or a image item in a canvas is deleted, or when the image displayed in a widget or canvas item is changed. freeProc must match the following prototype: typedef void Tk_ImageFreeProc( ClientData instanceData, Display *display); The instanceData will be the same as the value returned by getProc when the instance was created, and display is the display containing the window for the instance. freeProc should release any resources associated with the image instance, since the instance will never be used again. DELETEPROC typePtr->deleteProc is a procedure that Tk invokes when an image is being deleted (i.e. when the image delete command is invoked). Before invoking deleteProc Tk will invoke freeProc for each of the image's instances. deleteProc must match the following prototype: typedef void Tk_ImageDeleteProc( ClientData masterData); The masterData argument will be the same as the value stored in *masterDataPtr by createProc when the image was created. deleteProc should release any resources associated with the image. SEE ALSO Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage KEYWORDS image manager, image type, instance, master ═══ 5.14. Tk_CreateItemType ═══ NAME Tk_CreateItemType, Tk_GetItemTypes - define new kind of canvas item SYNOPSIS #include Tk_CreateItemType(typePtr) Tk_ItemType * Tk_GetItemTypes() ARGUMENTS Tk_ItemType *typePtr (in) Structure that defines the new type of canvas item. INTRODUCTION Tk_CreateItemType is invoked to define a new kind of canvas item described by the typePtr argument. An item type corresponds to a particular value of the type argument to the create widget command for canvases, and the code that implements a canvas item type is called a type manager. Tk defines several built-in item types, such as rectangle and text and image, but Tk_CreateItemType allows additional item types to be defined. Once Tk_CreateItemType returns, the new item type may be used in new or existing canvas widgets just like the built-in item types. Tk_GetItemTypes returns a pointer to the first in the list of all item types currently defined for canvases. The entries in the list are linked together through their nextPtr fields, with the end of the list marked by a NULL nextPtr. You may find it easier to understand the rest of this manual entry by looking at the code for an existing canvas item type such as bitmap (file tkCanvBmap.c) or text (tkCanvText.c). The easiest way to create a new type manager is to copy the code for an existing type and modify it for the new type. Tk provides a number of utility procedures for the use of canvas type managers, such as Tk_CanvasCoords and Tk_CanvasPsColor; these are described in separate manual entries. DATA STRUCTURES A type manager consists of a collection of procedures that provide a standard set of operations on items of that type. The type manager deals with three kinds of data structures. The first data structure is a Tk_ItemType; it contains information such as the name of the type and pointers to the standard procedures implemented by the type manager: typedef struct Tk_ItemType { char *name; int itemSize; Tk_ItemCreateProc *createProc; Tk_ConfigSpec *configSpecs; Tk_ItemConfigureProc *configProc; Tk_ItemCoordProc *coordProc; Tk_ItemDeleteProc *deleteProc; Tk_ItemDisplayProc *displayProc; int alwaysRedraw; Tk_ItemPointProc *pointProc; Tk_ItemAreaProc *areaProc; Tk_ItemPostscriptProc *postscriptProc; Tk_ItemScaleProc *scaleProc; Tk_ItemTranslateProc *translateProc; Tk_ItemIndexProc *indexProc; Tk_ItemCursorProc *icursorProc; Tk_ItemSelectionProc *selectionProc; Tk_ItemInsertProc *insertProc; Tk_ItemDCharsProc *dCharsProc; Tk_ItemType *nextPtr; } Tk_ItemType; The fields of a Tk_ItemType structure are described in more detail later in this manual entry. When Tk_CreateItemType is called, its typePtr argument must point to a structure with all of the fields initialized except nextPtr, which Tk sets to link all the types together into a list. The structure must be in permanent memory (either statically allocated or dynamically allocated but never freed); Tk retains a pointer to this structure. The second data structure manipulated by a type manager is an item record. For each item in a canvas there exists one item record. All of the items of a given type generally have item records with the same structure, but different types usually have different formats for their item records. The first part of each item record is a header with a standard structure defined by Tk via the type Tk_Item; the rest of the item record is defined by the type manager. A type manager must define its item records with a Tk_Item as the first field. For example, the item record for bitmap items is defined as follows: typedef struct BitmapItem { Tk_Item header; double x, y; Tk_Anchor anchor; Pixmap bitmap; XColor *fgColor; XColor *bgColor; GC gc; } BitmapItem; The header substructure contains information used by Tk to manage the item, such as its identifier, its tags, its type, and its bounding box. The fields starting with x belong to the type manager: Tk will never read or write them. The type manager should not need to read or write any of the fields in the header except for four fields whose names are x1, y1, x2, and y2. These fields give a bounding box for the items using integer canvas coordinates: the item should not cover any pixels with x-coordinate lower than x1 or y-coordinate lower than y1, nor should it cover any pixels with x-coordinate greater than or equal to x2 or y-coordinate greater than or equal to y2. It is up to the type manager to keep the bounding box up to date as the item is moved and reconfigured. Whenever Tk calls a procedure in a type manager it passes in a pointer to an item record. The argument is always passed as a pointer to a Tk_Item; the type manager will typically cast this into a pointer to its own specific type, such as BitmapItem. The third data structure used by type managers has type Tk_Canvas; it serves as an opaque handle for the canvas widget as a whole. Type managers need not know anything about the contents of this structure. A Tk_Canvas handle is typically passed in to the procedures of a type manager, and the type manager can pass the handle back to library procedures such as Tk_CanvasTkwin to fetch information about the canvas. NAME This section and the ones that follow describe each of the fields in a Tk_ItemType structure in detail. The name field provides a string name for the item type. Once Tk_CreateImageType returns, this name may be used in create widget commands to create items of the new type. If there already existed an item type by this name then the new item type replaces the old one. ITEMSIZE typePtr->itemSize gives the size in bytes of item records of this type, including the Tk_Item header. Tk uses this size to allocate memory space for items of the type. All of the item records for a given type must have the same size. If variable length fields are needed for an item (such as a list of points for a polygon), the type manager can allocate a separate object of variable length and keep a pointer to it in the item record. CREATEPROC typePtr->createProc points to a procedure for Tk to call whenever a new item of this type is created. typePtr->createProc must match the following prototype: typedef int Tk_ItemCreateProc( Tcl_Interp *interp, Tk_Canvas canvas, Tk_Item *itemPtr, int argc, char **argv); The interp argument is the interpreter in which the canvas's create widget command was invoked, and canvas is a handle for the canvas widget. itemPtr is a pointer to a newly-allocated item of size typePtr->itemSize. Tk has already initialized the item's header (the first sizeof(Tk_ItemType) bytes). The argc and argv arguments describe all of the arguments to the create command after the type argument. For example, in the widget command .c create rectangle 10 20 50 50 -fill black argc will be 6 and argv[0] will contain the string 10. createProc should use argc and argv to initialize the type-specific parts of the item record and set an initial value for the bounding box in the item's header. It should return a standard Tcl completion code and leave an error message in interp->result if an error occurs. If an error occurs Tk will free the item record, so createProc must be sure to leave the item record in a clean state if it returns an error (e.g., it must free any additional memory that it allocated for the item). CONFIGSPECS Each type manager must provide a standard table describing its configuration options, in a form suitable for use with Tk_ConfigureWidget. This table will normally be used by typePtr->createProc and typePtr->configProc, but Tk also uses it directly to retrieve option information in the itemcget and itemconfigure widget commands. typePtr->configSpecs must point to the configuration table for this type. Note: Tk provides a custom option type tk_CanvasTagsOption for implementing the -tags option; see an existing type manager for an example of how to use it in configSpecs. CONFIGPROC typePtr->configProc is called by Tk whenever the itemconfigure widget command is invoked to change the configuration options for a canvas item. This procedure must match the following prototype: typedef int Tk_ItemConfigureProc( Tcl_Interp *interp, Tk_Canvas canvas, Tk_Item *itemPtr, int argc, char **argv, int flags); The interp argument identifies the interpreter in which the widget command was invoked, canvas is a handle for the canvas widget, and itemPtr is a pointer to the item being configured. argc and argv contain the configuration options. For example, if the following command is invoked: .c itemconfigure 2 -fill red -outline black argc is 4 and argv contains the strings -fill through black. argc will always be an even value. The flags argument contains flags to pass to Tk_ConfigureWidget; currently this value is always TK_CONFIG_ARGV_ONLY when Tk invokes typePtr->configProc, but the type manager's createProc procedure will usually invoke configProc with different flag values. typePtr->configProc returns a standard Tcl completion code and leaves an error message in interp->result if an error occurs. It must update the item's bounding box to reflect the new configuration options. COORDPROC typePtr->coordProc is invoked by Tk to implement the coords widget command for an item. It must match the following prototype: typedef int Tk_ItemCoordProc( Tcl_Interp *interp, Tk_Canvas canvas, Tk_Item *itemPtr, int argc, char **argv); The arguments interp, canvas, and itemPtr all have the standard meanings, and argc and argv describe the coordinate arguments. For example, if the following widget command is invoked: .c coords 2 30 90 argc will be 2 and argv will contain the string values 30 and 90. The coordProc procedure should process the new coordinates, update the item appropriately (e.g., it must reset the bounding box in the item's header), and return a standard Tcl completion code. If an error occurs, coordProc must leave an error message in interp->result. DELETEPROC typePtr->deleteProc is invoked by Tk to delete an item and free any resources allocated to it. It must match the following prototype: typedef void Tk_ItemDeleteProc( Tk_Canvas canvas, Tk_Item *itemPtr, Display *display); The canvas and itemPtr arguments have the usual interpretations, and display identifies the X display containing the canvas. deleteProc must free up any resources allocated for the item, so that Tk can free the item record. deleteProc should not actually free the item record; this will be done by Tk when deleteProc returns. DISPLAYPROC AND ALWAYSREDRAW typePtr->displayProc is invoked by Tk to redraw an item on the screen. It must match the following prototype: typedef void Tk_ItemDisplayProc( Tk_Canvas canvas, Tk_Item *itemPtr, Display *display, Drawable dst, int x, int y, int width, int height); The canvas and itemPtr arguments have the usual meaning. display identifies the display containing the canvas, and dst specifies a drawable in which the item should be rendered; typically this is an off-screen pixmap, which Tk will copy into the canvas's window once all relevant items have been drawn. x, y, width, and height specify a rectangular region in canvas coordinates, which is the area to be redrawn; only information that overlaps this area needs to be redrawn. Tk will not call displayProc unless the item's bounding box overlaps the redraw area, but the type manager may wish to use the redraw area to optimize the redisplay of the item. Because of scrolling and the use of off-screen pixmaps for double-buffered redisplay, the item's coordinates in dst will not necessarily be the same as those in the canvas. displayProc should call Tk_CanvasDrawableCoords to transform coordinates from those of the canvas to those of dst. Normally an item's displayProc is only invoked if the item overlaps the area being displayed. However, if typePtr->alwaysRedraw has a non-zero value, then displayProc is invoked during every redisplay operation, even if the item doesn't overlap the area of redisplay. alwaysRedraw should normally be set to 0; it is only set to 1 in special cases such as window items that need to be unmapped when they are off-screen. POINTPROC typePtr->pointProc is invoked by Tk to find out how close a given point is to a canvas item. Tk uses this procedure for purposes such as locating the item under the mouse or finding the closest item to a given point. The procedure must match the following prototype: typedef double Tk_ItemPointProc( Tk_Canvas canvas, Tk_Item *itemPtr, double *pointPtr); canvas and itemPtr have the usual meaning. pointPtr points to an array of two numbers giving the x and y coordinates of a point. pointProc must return a real value giving the distance from the point to the item, or 0 if the point lies inside the item. AREAPROC typePtr->areaProc is invoked by Tk to find out the relationship between an item and a rectangular area. It must match the following prototype: typedef int Tk_ItemAreaProc( Tk_Canvas canvas, Tk_Item *itemPtr, double *rectPtr); canvas and itemPtr have the usual meaning. rectPtr points to an array of four real numbers; the first two give the x and y coordinates of the upper left corner of a rectangle, and the second two give the x and y coordinates of the lower right corner. areaProc must return -1 if the item lies entirely outside the given area, 0 if it lies partially inside and partially outside the area, and 1 if it lies entirely inside the area. POSTSCRIPTPROC typePtr->postscriptProc is invoked by Tk to generate Postcript for an item during the postscript widget command. If the type manager is not capable of generating Postscript then typePtr->postscriptProc should be NULL. The procedure must match the following prototype: typedef int Tk_ItemPostscriptProc( Tcl_Interp *interp, Tk_Canvas canvas, Tk_Item *itemPtr, int prepass); The interp, canvas, and itemPtr arguments all have standard meanings; prepass will be described below. If postscriptProc completes successfully, it should append Postscript for the item to the information in interp->result (e.g. by calling Tcl_AppendResult, not Tcl_SetResult) and return TCL_OK. If an error occurs, postscriptProc should clear the result and replace its contents with an error message; then it should return TCL_ERROR. Tk provides a collection of utility procedures to simplify postscriptProc. For example, Tk_CanvasPsColor will generate Postscript to set the current color to a given Tk color and Tk_CanvasPsFont will set up font information. When generating Postscript, the type manager is free to change the graphics state of the Postscript interpreter, since Tk places gsave and grestore commands around the Postscript for the item. The type manager can use canvas x coordinates directly in its Postscript, but it must call Tk_CanvasPsY to convert y coordinates from the space of the canvas (where the origin is at the upper left) to the space of Postscript (where the origin is at the lower left). In order to generate Postscript that complies with the Adobe Document Structuring Conventions, Tk actually generates Postscript in two passes. It calls each item's postscriptProc in each pass. The only purpose of the first pass is to collect font information (which is done by Tk_CanvPsFont); the actual Postscript is discarded. Tk sets the prepass argument to postscriptProc to 1 during the first pass; the type manager can use prepass to skip all Postscript generation except for calls to Tk_CanvasPsFont. During the second pass prepass will be 0, so the type manager must generate complete Postscript. SCALEPROC typePtr->scaleProc is invoked by Tk to rescale a canvas item during the scale widget command. The procedure must match the following prototype: typedef void Tk_ItemScaleProc( Tk_Canvas canvas, Tk_Item *itemPtr, double originX, double originY, double scaleX, double scaleY); The canvas and itemPtr arguments have the usual meaning. originX and originY specify an origin relative to which the item is to be scaled, and scaleX and scaleY give the x and y scale factors. The item should adjust its coordinates so that a point in the item that used to have coordinates x and y will have new coordinates x' and y', where x' = originX + scaleX*(x-originX) y' = originY + scaleY*(y-originY) scaleProc must also update the bounding box in the item's header. TRANSLATEPROC typePtr->translateProc is invoked by Tk to translate a canvas item during the move widget command. The procedure must match the following prototype: typedef void Tk_ItemTranslateProc( Tk_Canvas canvas, Tk_Item *itemPtr, double deltaX, double deltaY); The canvas and itemPtr arguments have the usual meaning, and deltaX and deltaY give the amounts that should be added to each x and y coordinate within the item. The type manager should adjust the item's coordinates and update the bounding box in the item's header. INDEXPROC typePtr->indexProc is invoked by Tk to translate a string index specification into a numerical index, for example during the index widget command. It is only relevant for item types that support indexable text; typePtr->indexProc may be specified as NULL for non-textual item types. The procedure must match the following prototype: typedef int Tk_ItemIndexProc( Tcl_Interp *interp, Tk_Canvas canvas, Tk_Item *itemPtr, char indexString, int *indexPtr); The interp, canvas, and itemPtr arguments all have the usual meaning. indexString contains a textual description of an index, and indexPtr points to an integer value that should be filled in with a numerical index. It is up to the type manager to decide what forms of index are supported (e.g., numbers, insert, sel.first, end, etc.). indexProc should return a Tcl completion code and set interp->result in the event of an error. ICURSORPROC typePtr->icursorProc is invoked by Tk during the icursor widget command to set the position of the insertion cursor in a textual item. It is only relevant for item types that support an insertion cursor; typePtr->icursorProc may be specified as NULL for item types that don't support an insertion cursor. The procedure must match the following prototype: typedef void Tk_ItemIndexProc( Tk_Canvas canvas, Tk_Item *itemPtr, int index); canvas and itemPtr have the usual meanings, and index is an index into the item's text, as returned by a previous call to typePtr->insertProc. The type manager should position the insertion cursor in the item just before the character given by index. Whether or not to actually display the insertion cursor is determined by other information provided by Tk_CanvasGetTextInfo. SELECTIONPROC typePtr->selectionProc is invoked by Tk during selection retrievals; it must return part or all of the selected text in the item (if any). It is only relevant for item types that support text; typePtr->selectionProc may be specified as NULL for non-textual item types. The procedure must match the following prototype: typedef int Tk_ItemSelectionProc( Tk_Canvas canvas, Tk_Item *itemPtr, int offset, char *buffer, int maxBytes); canvas and itemPtr have the usual meanings. offset is an offset in bytes into the selection where 0 refers to the first byte of the selection; it identifies the first character that is to be returned in this call. buffer points to an area of memory in which to store the requested bytes, and maxBytes specifies the maximum number of bytes to return. selectionProc should extract up to maxBytes characters from the selection and copy them to maxBytes; it should return a count of the number of bytes actually copied, which may be less than maxBytes if there aren't offset+maxBytes bytes in the selection. INSERTPROC typePtr->insertProc is invoked by Tk during the insert widget command to insert new text into a canvas item. It is only relevant for item types that support text; typePtr->insertProc may be specified as NULL for non-textual item types. The procedure must match the following prototype: typedef void Tk_ItemInsertProc( Tk_Canvas canvas, Tk_Item *itemPtr, int index, char *string); canvas and itemPtr have the usual meanings. index is an index into the item's text, as returned by a previous call to typePtr->insertProc, and string contains new text to insert just before the character given by index. The type manager should insert the text and recompute the bounding box in the item's header. DCHARSPROC typePtr->dCharsProc is invoked by Tk during the dchars widget command to delete a range of text from a canvas item. It is only relevant for item types that support text; typePtr->dCharsProc may be specified as NULL for non-textual item types. The procedure must match the following prototype: typedef void Tk_ItemDCharsProc( Tk_Canvas canvas, Tk_Item *itemPtr, int first, int last); canvas and itemPtr have the usual meanings. first and last give the indices of the first and last bytes to be deleted, as returned by previous calls to typePtr->indexProc. The type manager should delete the specified characters and update the bounding box in the item's header. SEE ALSO Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin KEYWORDS canvas, focus, item type, selection, type manager ═══ 5.15. Tk_CreatePhotoImageFormat ═══ NAME Tk_CreatePhotoImageFormat - define new file format for photo images SYNOPSIS #include #include Tk_CreatePhotoImageFormat(formatPtr) ARGUMENTS Tk_PhotoImageFormat *formatPtr (in) Structure that defines the new file format. DESCRIPTION Tk_CreatePhotoImageFormat is invoked to define a new file format for image data for use with photo images. The code that implements an image file format is called an image file format handler, or handler for short. The photo image code maintains a list of handlers that can be used to read and write data to or from a file. Some handlers may also support reading image data from a string or converting image data to a string format. The user can specify which handler to use with the -format image configuration option or the -format option to the read and write photo image subcommands. An image file format handler consists of a collection of procedures plus a Tk_PhotoImageFormat structure, which contains the name of the image file format and pointers to six procedures provided by the handler to deal with files and strings in this format. The Tk_PhotoImageFormat structure contains the following fields: typedef struct Tk_PhotoImageFormat { char *name; Tk_ImageFileMatchProc *fileMatchProc; Tk_ImageStringMatchProc *stringMatchProc; Tk_ImageFileReadProc *fileReadProc; Tk_ImageStringReadProc *stringReadProc; Tk_ImageFileWriteProc *fileWriteProc; Tk_ImageStringWriteProc *stringWriteProc; } Tk_PhotoImageFormat; The handler need not provide implementations of all six procedures. For example, the procedures that handle string data would not be provided for a format in which the image data are stored in binary, and could therefore contain null characters. If any procedure is not implemented, the corresponding pointer in the Tk_PhotoImageFormat structure should be set to NULL. The handler must provide the fileMatchProc procedure if it provides the fileReadProc procedure, and the stringMatchProc procedure if it provides the stringReadProc procedure. NAME formatPtr->name provides a name for the image type. Once Tk_CreatePhotoImageFormat returns, this name may be used in the -format photo image configuration and subcommand option. The manual page for the photo image (photo(n)) describes how image file formats are chosen based on their names and the value given to the -format option. FILEMATCHPROC formatPtr->fileMatchProc provides the address of a procedure for Tk to call when it is searching for an image file format handler suitable for reading data in a given file. formatPtr->fileMatchProc must match the following prototype: typedef int Tk_ImageFileMatchProc( FILE *f, char *fileName, char *formatString, int *widthPtr, int *heightPtr); The fileName argument is the name of the file containing the image data, which is open for reading as f. The formatString argument contains the value given for the -format option, or NULL if the option was not specified. If the data in the file appears to be in the format supported by this handler, the formatPtr->fileMatchProc procedure should store the width and height of the image in *widthPtr and *heightPtr respectively, and return 1. Otherwise it should return 0. STRINGMATCHPROC formatPtr->stringMatchProc provides the address of a procedure for Tk to call when it is searching for an image file format handler for suitable for reading data from a given string. formatPtr->stringMatchProc must match the following prototype: typedef int Tk_ImageStringMatchProc( char *string, char *formatString, int *widthPtr, int *heightPtr); The string argument points to the string containing the image data. The formatString argument contains the value given for the -format option, or NULL if the option was not specified. If the data in the string appears to be in the format supported by this handler, the formatPtr->stringMatchProc procedure should store the width and height of the image in *widthPtr and *heightPtr respectively, and return 1. Otherwise it should return 0. FILEREADPROC formatPtr->fileReadProc provides the address of a procedure for Tk to call to read data from an image file into a photo image. formatPtr->fileReadProc must match the following prototype: typedef int Tk_ImageFileReadProc( Tcl_Interp *interp, FILE *f, char *fileName, char *formatString, PhotoHandle imageHandle, int destX, int destY, int width, int height, int srcX, int srcY); The interp argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. The image data is in the file named fileName, which is open for reading as f. The formatString argument contains the value given for the -format option, or NULL if the option was not specified. The image data in the file, or a subimage of it, is to be read into the photo image identified by the handle imageHandle. The subimage of the data in the file is of dimensions width x height and has its top-left corner at coordinates (srcX,srcY). It is to be stored in the photo image with its top-left corner at coordinates (destX,destY) using the Tk_PhotoPutBlock procedure. The return value is a standard Tcl return value. STRINGREADPROC formatPtr->stringReadProc provides the address of a procedure for Tk to call to read data from a string into a photo image. formatPtr->stringReadProc must match the following prototype: typedef int Tk_ImageStringReadProc( Tcl_Interp *interp, char *string, char *formatString, PhotoHandle imageHandle, int destX, int destY, int width, int height, int srcX, int srcY); The interp argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. The string argument points to the image data in string form. The formatString argument contains the value given for the -format option, or NULL if the option was not specified. The image data in the string, or a subimage of it, is to be read into the photo image identified by the handle imageHandle. The subimage of the data in the string is of dimensions width x height and has its top-left corner at coordinates (srcX,srcY). It is to be stored in the photo image with its top-left corner at coordinates (destX,destY) using the Tk_PhotoPutBlock procedure. The return value is a standard Tcl return value. FILEWRITEPROC formatPtr->fileWriteProc provides the address of a procedure for Tk to call to write data from a photo image to a file. formatPtr->fileWriteProc must match the following prototype: typedef int Tk_ImageFileWriteProc( Tcl_Interp *interp, char *fileName, char *formatString, Tk_PhotoImageBlock *blockPtr); The interp argument is the interpreter in which the command was invoked to write the image; it should be used for reporting errors. The image data to be written are in memory and are described by the Tk_PhotoImageBlock structure pointed to by blockPtr; see the manual page FindPhoto(3) for details. The fileName argument points to the string giving the name of the file in which to write the image data. The formatString argument contains the value given for the -format option, or NULL if the option was not specified. The format string can contain extra characters after the name of the format. If appropriate, the formatPtr->fileWriteProc procedure may interpret these characters to specify further details about the image file. The return value is a standard Tcl return value. STRINGWRITEPROC formatPtr->stringWriteProc provides the address of a procedure for Tk to call to translate image data from a photo image into a string. formatPtr->stringWriteProc must match the following prototype: typedef int Tk_ImageStringWriteProc( Tcl_Interp *interp, Tcl_DString *dataPtr, char *formatString, Tk_PhotoImageBlock *blockPtr); The interp argument is the interpreter in which the command was invoked to convert the image; it should be used for reporting errors. The image data to be converted are in memory and are described by the Tk_PhotoImageBlock structure pointed to by blockPtr; see the manual page FindPhoto(3) for details. The data for the string should be appended to the dynamic string given by dataPtr. The formatString argument contains the value given for the -format option, or NULL if the option was not specified. The format string can contain extra characters after the name of the format. If appropriate, the formatPtr->stringWriteProc procedure may interpret these characters to specify further details about the image file. The return value is a standard Tcl return value. SEE ALSO Tk_FindPhoto, Tk_PhotoPutBlock KEYWORDS photo image, image file ═══ 5.16. Tk_CreateSelHandler ═══ NAME Tk_CreateSelHandler, Tk_DeleteSelHandler - arrange to handle requests for a selection SYNOPSIS #include Tk_CreateSelHandler(tkwin, selection, target, proc, clientData, format) Tk_DeleteSelHandler(tkwin, selection, target) ARGUMENTS Tk_Window tkwin (in) Window for which proc will provide selection information. Atom selection (in) The name of the selection for which proc will provide selection information. Atom target (in) Form in which proc can provide the selection (e.g. STRING or FILE_NAME). Corresponds to type arguments in selection commands. Tk_SelectionProc *proc (in) Procedure to invoke whenever the selection is owned by tkwin and the selection contents are requested in the format given by target. ClientData clientData (in) Arbitrary one-word value to pass to proc. Atom format (in) If the selection requestor isn't in this process, format determines the representation used to transmit the selection to its requestor. DESCRIPTION Tk_CreateSelHandler arranges for a particular procedure (proc) to be called whenever selection is owned by tkwin and the selection contents are requested in the form given by target. Target should be one of the entries defined in the left column of Table 2 of the X Inter-Client Communication Conventions Manual (ICCCM) or any other form in which an application is willing to present the selection. The most common form is STRING. Proc should have arguments and result that match the type Tk_SelectionProc: typedef int Tk_SelectionProc( ClientData clientData, int offset, char *buffer, int maxBytes); The clientData parameter to proc is a copy of the clientData argument given to Tk_CreateSelHandler. Typically, clientData points to a data structure containing application-specific information that is needed to retrieve the selection. Offset specifies an offset position into the selection, buffer specifies a location at which to copy information about the selection, and maxBytes specifies the amount of space available at buffer. Proc should place a NULL-terminated string at buffer containing maxBytes or fewer characters (not including the terminating NULL), and it should return a count of the number of non-NULL characters stored at buffer. If the selection no longer exists (e.g. it once existed but the user deleted the range of characters containing it), then proc should return -1. When transferring large selections, Tk will break them up into smaller pieces (typically a few thousand bytes each) for more efficient transmission. It will do this by calling proc one or more times, using successively higher values of offset to retrieve successive portions of the selection. If proc returns a count less than maxBytes it means that the entire remainder of the selection has been returned. If proc's return value is maxBytes it means there may be additional information in the selection, so Tk must make another call to proc to retrieve the next portion. Proc always returns selection information in the form of a character string. However, the ICCCM allows for information to be transmitted from the selection owner to the selection requestor in any of several formats, such as a string, an array of atoms, an array of integers, etc. The format argument to Tk_CreateSelHandler indicates what format should be used to transmit the selection to its requestor (see the middle column of Table 2 of the ICCCM for examples). If format is not STRING, then Tk will take the value returned by proc and divided it into fields separated by white space. If format is ATOM, then Tk will return the selection as an array of atoms, with each field in proc's result treated as the name of one atom. For any other value of format, Tk will return the selection as an array of 32-bit values where each field of proc's result is treated as a number and translated to a 32-bit value. In any event, the format atom is returned to the selection requestor along with the contents of the selection. If Tk_CreateSelHandler is called when there already exists a handler for selection and target on tkwin, then the existing handler is replaced with a new one. Tk_DeleteSelHandler removes the handler given by tkwin, selection, and target, if such a handler exists. If there is no such handler then it has no effect. KEYWORDS format, handler, selection, target ═══ 5.17. Tk_DeleteImage ═══ NAME Tk_DeleteImage - Destroy an image. SYNOPSIS #include Tk_DeleteImage(interp, name) ARGUMENTS Tcl_Interp *interp (in) Interpreter for which the image was created. char *name (in) Name of the image. DESCRIPTION Tk_DeleteImage deletes the image given by interp and name, if there is one. All instances of that image will redisplay as empty regions. If the given image does not exist then the procedure has no effect. KEYWORDS delete image, image manager ═══ 5.18. Tk_DrawFocusHighlight ═══ NAME Tk_DrawFocusHighlight - draw the traversal highlight ring for a widget SYNOPSIS #include Tk_GetPixels(tkwin, gc, width, drawable) ARGUMENTS Tk_Window tkwin (in) Window for which the highlight is being drawn. Used to retrieve the window's dimensions, among other things. GC gc (in) Graphics context to use for drawing the highlight. int width (in) Width of the highlight ring, in pixels. Drawable drawable (in) Drawable in which to draw the highlight; usually an offscreen pixmap for double buffering. DESCRIPTION Tk_DrawFocusHighlight is a utility procedure that draws the traversal highlight ring for a widget. It is typically invoked by widgets during redisplay. KEYWORDS focus, traversal highlight ═══ 5.19. Tk_CreateEventHandler ═══ NAME Tk_CreateEventHandler, Tk_DeleteEventHandler - associate procedure callback with an X event SYNOPSIS #include Tk_CreateEventHandler(tkwin, mask, proc, clientData) Tk_DeleteEventHandler(tkwin, mask, proc, clientData) ARGUMENTS Tk_Window tkwin (in) Token for window in which events may occur. unsigned long mask (in) Bit-mask of events (such as ButtonPressMask) for which proc should be called. Tk_EventProc *proc (in) Procedure to invoke whenever an event in mask occurs in the window given by tkwin. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION Tk_CreateEventHandler arranges for proc to be invoked in the future whenever one of the event types specified by mask occurs in the window specified by tkwin. The callback to proc will be made by Tk_HandleEvent; this mechanism only works in programs that dispatch events through Tk_HandleEvent (or through other Tk procedures that call Tk_HandleEvent, such as Tk_DoOneEvent or Tk_MainLoop). Proc should have arguments and result that match the type Tk_EventProc: typedef void Tk_EventProc( ClientData clientData, XEvent *eventPtr); The clientData parameter to proc is a copy of the clientData argument given to Tk_CreateEventHandler when the callback was created. Typically, clientData points to a data structure containing application-specific information about the window in which the event occurred. EventPtr is a pointer to the X event, which will be one of the ones specified in the mask argument to Tk_CreateEventHandler. Tk_DeleteEventHandler may be called to delete a previously-created event handler: it deletes the first handler it finds that is associated with tkwin and matches the mask, proc, and clientData arguments. If no such handler exists, then Tk_EventHandler returns without doing anything. Although Tk supports it, it's probably a bad idea to have more than one callback with the same mask, proc, and clientData arguments. When a window is deleted all of its handlers will be deleted automatically; in this case there is no need to call Tk_DeleteEventHandler. If multiple handlers are declared for the same type of X event on the same window, then the handlers will be invoked in the order they were created. KEYWORDS bind, callback, event, handler ═══ 5.20. Tk_FindPhoto ═══ NAME Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_PhotoBlank, Tk_PhotoExpand, Tk_PhotoGetSize, Tk_PhotoSetSize - manipulate the image data stored in a photo image. SYNOPSIS #include #include Tk_PhotoHandle Tk_FindPhoto(imageName) void Tk_PhotoPutBlock(handle, blockPtr, x, y, width, height) void Tk_PhotoPutZoomedBlock(handle, blockPtr, x, y, width, height, zoomX, zoomY, subsampleX, subsampleY) int Tk_PhotoGetImage(handle, blockPtr) void Tk_PhotoBlank(handle) void Tk_PhotoExpand(handle, width, height) void Tk_PhotoGetSize(handle, widthPtr, heightPtr) void Tk_PhotoSetSize(handle, width, height) ARGUMENTS char *imageName (in) Name of the photo image. Tk_PhotoHandle handle (in) Opaque handle identifying the photo image to be affected. Tk_PhotoImageBlock *blockPtr (in) Specifies the address and storage layout of image data. int x (in) Specifies the X coordinate where the top-left corner of the block is to be placed within the image. int y (in) Specifies the Y coordinate where the top-left corner of the block is to be placed within the image. int width (in) Specifies the width of the image area to be affected (for Tk_PhotoPutBlock) or the desired image width (for Tk_PhotoExpand and Tk_PhotoSetSize). int height (in) Specifies the height of the image area to be affected (for Tk_PhotoPutBlock) or the desired image height (for Tk_PhotoExpand and Tk_PhotoSetSize). int *widthPtr (out) Pointer to location in which to store the image width. int *heightPtr (out) Pointer to location in which to store the image height. int subsampleX (in) Specifies the subsampling factor in the X direction for input image data. int subsampleY (in) Specifies the subsampling factor in the Y direction for input image data. int zoomX (in) Specifies the zoom factor to be applied in the X direction to pixels being written to the photo image. int zoomY (in) Specifies the zoom factor to be applied in the Y direction to pixels being written to the photo image. DESCRIPTION Tk_FindPhoto returns an opaque handle that is used to identify a particular photo image to the other procedures. The parameter is the name of the image, that is, the name specified to the image create photo command, or assigned by that command if no name was specified. Tk_PhotoPutBlock is used to supply blocks of image data to be displayed. The call affects an area of the image of size width x height pixels, with its top-left corner at coordinates (x,y). All of width, height, x, and y must be non-negative. If part of this area lies outside the current bounds of the image, the image will be expanded to include the area, unless the user has specified an explicit image size with the -width and/or -height widget configuration options (see photo(n)); in that case the area is silently clipped to the image boundaries. The block parameter is a pointer to a Tk_PhotoImageBlock structure, defined as follows: typedef struct { unsigned char *pixelPtr; int width; int height; int pitch; int pixelSize; int offset[3]; } Tk_PhotoImageBlock; The pixelPtr field points to the first pixel, that is, the top-left pixel in the block. The width and height fields specify the dimensions of the block of pixels. The pixelSize field specifies the address difference between two horizontally adjacent pixels. Often it is 3 or 4, but it can have any value. The pitch field specifies the address difference between two vertically adjacent pixels. The offset array contains the offsets from the address of a pixel to the addresses of the bytes containing the red, green and blue components. These are normally 0, 1 and 2, but can have other values, e.g., for images that are stored as separate red, green and blue planes. The value given for the width and height parameters to Tk_PhotoPutBlock do not have to correspond to the values specified in block. If they are smaller, Tk_PhotoPutBlock extracts a sub-block from the image data supplied. If they are larger, the data given are replicated (in a tiled fashion) to fill the specified area. These rules operate independently in the horizontal and vertical directions. Tk_PhotoPutZoomedBlock works like Tk_PhotoPutBlock except that the image can be reduced or enlarged for display. The subsampleX and subsampleY parameters allow the size of the image to be reduced by subsampling. Tk_PhotoPutZoomedBlock will use only pixels from the input image whose X coordinates are multiples of subsampleX, and whose Y coordinates are multiples of subsampleY. For example, an image of 512x512 pixels can be reduced to 256x256 by setting subsampleX and subsampleY to 2. The zoomX and zoomY parameters allow the image to be enlarged by pixel replication. Each pixel of the (possibly subsampled) input image will be written to a block zoomX pixels wide and zoomY pixels high of the displayed image. Subsampling and zooming can be used together for special effects. Tk_PhotoGetImage can be used to retrieve image data from a photo image. Tk_PhotoGetImage fills in the structure pointed to by the blockPtr parameter with values that describe the address and layout of the image data that the photo image has stored internally. The values are valid until the image is destroyed or its size is changed. Tk_PhotoGetImage returns 1 for compatibility with the corresponding procedure in the old photo widget. Tk_PhotoBlank blanks the entire area of the photo image. Blank areas of a photo image are transparent. Tk_PhotoExpand requests that the widget's image be expanded to be at least width x height pixels in size. The width and/or height are unchanged if the user has specified an explicit image width or height with the -width and/or -height configuration options, respectively. If the image data are being supplied in many small blocks, it is more efficient to use Tk_PhotoExpand or Tk_PhotoSetSize at the beginning rather than allowing the image to expand in many small increments as image blocks are supplied. Tk_PhotoSetSize specifies the size of the image, as if the user had specified the given width and height values to the -width and -height configuration options. A value of zero for width or height does not change the image's width or height, but allows the width or height to be changed by subsequent calls to Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock or Tk_PhotoExpand. Tk_PhotoGetSize returns the dimensions of the image in *widthPtr and *heightPtr. CREDITS The code for the photo image type was developed by Paul Mackerras, based on his earlier photo widget code. KEYWORDS photo, image ═══ 5.21. Tk_FreeXId ═══ NAME Tk_FreeXId - make X resource identifier available for reuse SYNOPSIS #include Tk_FreeXId(display, id) ARGUMENTS Display *display (in) Display for which id was allocated. XID id (in) Identifier of X resource (window, font, pixmap, cursor, graphics context, or colormap) that is no longer in use. DESCRIPTION The default allocator for resource identifiers provided by Xlib is very simple-minded and does not allow resource identifiers to be re-used. If a long-running application reaches the end of the resource id space, it will generate an X protocol error and crash. Tk replaces the default id allocator with its own allocator, which allows identifiers to be reused. In order for this to work, Tk_FreeXId must be called to tell the allocator about resources that have been freed. Tk automatically calls Tk_FreeXId whenever it frees a resource, so if you use procedures like Tk_GetFontStruct, Tk_GetGC, and Tk_GetPixmap then you need not call Tk_FreeXId. However, if you allocate resources directly from Xlib, for example by calling XCreatePixmap, then you should call Tk_FreeXId when you call the corresponding Xlib free procedure, such as XFreePixmap. If you don't call Tk_FreeXId then the resource identifier will be lost, which could cause problems if the application runs long enough to lose all of the available identifiers. KEYWORDS resource identifier ═══ 5.22. Tk_GeometryRequest ═══ NAME Tk_GeometryRequest, Tk_SetInternalBorder - specify desired geometry or internal border for a window SYNOPSIS #include Tk_GeometryRequest(tkwin, reqWidth, reqHeight) Tk_SetInternalBorder(tkwin, width) ARGUMENTS Tk_Window tkwin (in) Window for which geometry is being requested. int reqWidth (in) Desired width for tkwin, in pixel units. int reqHeight (in) Desired height for tkwin, in pixel units. int width (in) Space to leave for internal border for tkwin, in pixel units. DESCRIPTION Tk_GeometryRequest is called by widget code to indicate its preference for the dimensions of a particular window. The arguments to Tk_GeometryRequest are made available to the geometry manager for the window, which then decides on the actual geometry for the window. Although geometry managers generally try to satisfy requests made to Tk_GeometryRequest, there is no guarantee that this will always be possible. Widget code should not assume that a geometry request will be satisfied until it receives a ConfigureNotify event indicating that the geometry change has occurred. Widget code should never call procedures like Tk_ResizeWindow directly. Instead, it should invoke Tk_GeometryRequest and leave the final geometry decisions to the geometry manager. If tkwin is a top-level window, then the geometry information will be passed to the window manager using the standard ICCCM protocol. Tk_SetInternalBorder is called by widget code to indicate that the widget has an internal border. This means that the widget draws a decorative border inside the window instead of using the standard X borders, which are external to the window's area. For example, internal borders are used to draw 3-D effects. Width specifies the width of the border in pixels. Geometry managers will use this information to avoid placing any children of tkwin overlapping the outermost width pixels of tkwin's area. The information specified in calls to Tk_GeometryRequest and Tk_SetInternalBorder can be retrieved using the macros Tk_ReqWidth, Tk_ReqHeight, and Tk_InternalBorderWidth. See the Tk_WindowId manual entry for details. KEYWORDS geometry, request ═══ 5.23. Tk_GetAnchor ═══ NAME Tk_GetAnchor, Tk_NameOfAnchor - translate between strings and anchor positions SYNOPSIS #include int Tk_GetAnchor(interp, string, anchorPtr) char * Tk_NameOfAnchor(anchor) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. char *string (in) String containing name of anchor point: one of "n", "ne", "e", "se", "s", "sw", "w", "nw", or "center". int *anchorPtr (out) Pointer to location in which to store anchor position corresponding to string. Tk_Anchor anchor (in) Anchor position, e.g. TCL_ANCHOR_CENTER. DESCRIPTION Tk_GetAnchor places in *anchorPtr an anchor position (enumerated type Tk_Anchor) corresponding to string, which will be one of TK_ANCHOR_N, TK_ANCHOR_NE, TK_ANCHOR_E, TK_ANCHOR_SE, TK_ANCHOR_S, TK_ANCHOR_SW, TK_ANCHOR_W, TK_ANCHOR_NW, or TK_ANCHOR_CENTER. Anchor positions are typically used for indicating a point on an object that will be used to position that object, e.g. TK_ANCHOR_N means position the top center point of the object at a particular place. Under normal circumstances the return value is TCL_OK and interp is unused. If string doesn't contain a valid anchor position or an abbreviation of one of these names, then an error message is stored in interp->result, TCL_ERROR is returned, and *anchorPtr is unmodified. Tk_NameOfAnchor is the logical inverse of Tk_GetAnchor. Given an anchor position such as TK_ANCHOR_N it returns a statically-allocated string corresponding to anchor. If anchor isn't a legal anchor value, then "unknown anchor position" is returned. KEYWORDS anchor position ═══ 5.24. Tk_GetBitmap ═══ NAME Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData - maintain database of single-plane pixmaps SYNOPSIS #include Pixmap Tk_GetBitmap(interp, tkwin, id) int Tk_DefineBitmap(interp, nameId, source, width, height) Tk_Uid Tk_NameOfBitmap(display, bitmap) Tk_SizeOfBitmap(display, bitmap, widthPtr, heightPtr) Tk_FreeBitmap(display, bitmap) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. Tk_Window tkwin (in) Token for window in which the bitmap will be used. Tk_Uid id (in) Description of bitmap; see below for possible values. Tk_Uid nameId (in) Name for new bitmap to be defined. char *source (in) Data for bitmap, in standard bitmap format. Must be stored in static memory whose value will never change. int width (in) Width of bitmap. int height (in) Height of bitmap. int *widthPtr (out) Pointer to word to fill in with bitmap's width. int *heightPtr (out) Pointer to word to fill in with bitmap's height. Display *display (in) Display for which bitmap was allocated. Pixmap bitmap (in) Identifier for a bitmap allocated by Tk_GetBitmap. DESCRIPTION These procedures manage a collection of bitmaps (one-plane pixmaps) being used by an application. The procedures allow bitmaps to be re-used efficiently, thereby avoiding server overhead, and also allow bitmaps to be named with character strings. Tk_GetBitmap takes as argument a Tk_Uid describing a bitmap. It returns a Pixmap identifier for a bitmap corresponding to the description. It re-uses an existing bitmap, if possible, and creates a new one otherwise. At present, id must have one of the following forms: @fileName FileName must be the name of a file containing a bitmap description in the standard X11 or X10 format. name Name must be the name of a bitmap defined previously with a call to Tk_DefineBitmap. The following names are pre-defined by Tk: error The international "don't" symbol: a circle with a diagonal line across it. gray50 50% gray: a checkerboard pattern where every other bit is on. gray12 12.5% gray: a pattern where one-eighth of the bits are on, consisting of every fourth pixel in every other row. hourglass An hourglass symbol. info A large letter "i". questhead The silhouette of a human head, with a question mark in it. question A large question-mark. warning A large exclamation point. Under normal conditions, Tk_GetBitmap returns an identifier for the requested bitmap. If an error occurs in creating the bitmap, such as when id refers to a non-existent file, then None is returned and an error message is left in interp->result. Tk_DefineBitmap associates a name with in-memory bitmap data so that the name can be used in later calls to Tk_GetBitmap. The nameId argument gives a name for the bitmap; it must not previously have been used in a call to Tk_DefineBitmap. The arguments source, width, and height describe the bitmap. Tk_DefineBitmap normally returns TCL_OK; if an error occurs (e.g. a bitmap named nameId has already been defined) then TCL_ERROR is returned and an error message is left in interp->result. Note: Tk_DefineBitmap expects the memory pointed to by source to be static: Tk_DefineBitmap doesn't make a private copy of this memory, but uses the bytes pointed to by source later in calls to Tk_GetBitmap. Typically Tk_DefineBitmap is used by #include-ing a bitmap file directly into a C program and then referencing the variables defined by the file. For example, suppose there exists a file stip.bitmap, which was created by the bitmap program and contains a stipple pattern. The following code uses Tk_DefineBitmap to define a new bitmap named foo: Pixmap bitmap; #include "stip.bitmap" Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits, stip_width, stip_height); ... bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo")); This code causes the bitmap file to be read at compile-time and incorporates the bitmap information into the program's executable image. The same bitmap file could be read at run-time using Tk_GetBitmap: Pixmap bitmap; bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap")); The second form is a bit more flexible (the file could be modified after the program has been compiled, or a different string could be provided to read a different file), but it is a little slower and requires the bitmap file to exist separately from the program. Tk_GetBitmap maintains a database of all the bitmaps that are currently in use. Whenever possible, it will return an existing bitmap rather than creating a new one. This approach can substantially reduce server overhead, so Tk_GetBitmap should generally be used in preference to Xlib procedures like XReadBitmapFile. The bitmaps returned by Tk_GetBitmap are shared, so callers should never modify them. If a bitmap must be modified dynamically, then it should be created by calling Xlib procedures such as XReadBitmapFile or XCreatePixmap directly. The procedure Tk_NameOfBitmap is roughly the inverse of Tk_GetBitmap. Given an X Pixmap argument, it returns the id that was passed to Tk_GetBitmap when the bitmap was created. Bitmap must have been the return value from a previous call to Tk_GetBitmap. Tk_SizeOfBitmap returns the dimensions of its bitmap argument in the words pointed to by the widthPtr and heightPtr arguments. As with Tk_NameOfBitmap, bitmap must have been created by Tk_GetBitmap. When a bitmap returned by Tk_GetBitmap is no longer needed, Tk_FreeBitmap should be called to release it. There should be exactly one call to Tk_FreeBitmap for each call to Tk_GetBitmap. When a bitmap is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten) Tk_FreeBitmap will release it to the X server and delete it from the database. BUGS In determining whether an existing bitmap can be used to satisfy a new request, Tk_GetBitmap considers only the immediate value of its id argument. For example, when a file name is passed to Tk_GetBitmap, Tk_GetBitmap will assume it is safe to re-use an existing bitmap created from the same file name: it will not check to see whether the file itself has changed, or whether the current directory has changed, thereby causing the name to refer to a different file. KEYWORDS bitmap, pixmap ═══ 5.25. Tk_GetCapStyle ═══ NAME Tk_GetCapStyle, Tk_NameOfCapStyle - translate between strings and cap styles SYNOPSIS #include int Tk_GetCapStyle(interp, string, capPtr) char * Tk_NameOfCapStyle(cap) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. char *string (in) String containing name of cap style: one of "`butt", "projecting", or "round". int *capPtr (out) Pointer to location in which to store X cap style corresponding to string. int cap (in) Cap style: one of CapButt, CapProjecting, or CapRound. DESCRIPTION Tk_GetCapStyle places in *capPtr the X cap style corresponding to string. This will be one of the values CapButt, CapProjecting, or CapRound. Cap styles are typically used in X graphics contexts to indicate how the end-points of lines should be capped. See the X documentation for information on what each style implies. Under normal circumstances the return value is TCL_OK and interp is unused. If string doesn't contain a valid cap style or an abbreviation of one of these names, then an error message is stored in interp->result, TCL_ERROR is returned, and *capPtr is unmodified. Tk_NameOfCapStyle is the logical inverse of Tk_GetCapStyle. Given a cap style such as CapButt it returns a statically-allocated string corresponding to cap. If cap isn't a legal cap style, then "unknown cap style" is returned. KEYWORDS butt, cap style, projecting, round ═══ 5.26. Tk_GetColormap ═══ NAME Tk_GetColormap, Tk_FreeColormap - allocate and free colormaps SYNOPSIS #include Colormap Tk_GetColormap(interp, tkwin, string) Tk_FreeColormap(display, colormap) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. Tk_Window tkwin (in) Token for window in which colormap will be used. char *string (in) Selects a colormap: either new or the name of a window with the same screen and visual as tkwin. Display *display (in) Display for which colormap was allocated. Colormap colormap (in) Colormap to free; must have been returned by a previous call to Tk_GetColormap or Tk_GetVisual. DESCRIPTION These procedures are used to manage colormaps. Tk_GetColormap returns a colormap suitable for use in tkwin. If its string argument is new then a new colormap is created; otherwise string must be the name of another window with the same screen and visual as tkwin, and the colormap from that window is returned. If string doesn't make sense, or if it refers to a window on a different screen from tkwin or with a different visual than tkwin, then Tk_GetColormap returns None and leaves an error message in interp->result. Tk_FreeColormap should be called when a colormap returned by Tk_GetColormap is no longer needed. Tk maintains a reference count for each colormap returned by Tk_GetColormap, so there should eventually be one call to Tk_FreeColormap for each call to Tk_GetColormap. When a colormap's reference count becomes zero, Tk releases the X colormap. Tk_GetVisual and Tk_GetColormap work together, in that a new colormap created by Tk_GetVisual may later be returned by Tk_GetColormap. The reference counting mechanism for colormaps includes both procedures, so callers of Tk_GetVisual must also call Tk_FreeColormap to release the colormap. If Tk_GetColormap is called with a string value of new then the resulting colormap will never be returned by Tk_GetVisual; however, it can be used in other windows by calling Tk_GetColormap with the original window's name as string. KEYWORDS colormap ═══ 5.27. Tk_GetColor ═══ NAME Tk_GetColor, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColor - maintain database of colors SYNOPSIS #include XColor * Tk_GetColor(interp, tkwin, nameId) XColor * Tk_GetColorByValue(tkwin, prefPtr) char * Tk_NameOfColor(colorPtr) GC Tk_GCForColor(colorPtr, drawable) Tk_FreeColor(colorPtr) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. Tk_Window tkwin (in) Token for window in which color will be used. Tk_Uid nameId (in) Textual description of desired color. XColor *prefPtr (in) Indicates red, green, and blue intensities of desired color. XColor *colorPtr (in) Pointer to X color information. Must have been allocated by previous call to Tk_GetColor or Tk_GetColorByValue, except when passed to Tk_NameOfColor. Drawable drawable (in) Drawable in which the result graphics context will be used. Must have same screen and depth as the window for which the color was allocated. DESCRIPTION The Tk_GetColor and Tk_GetColorByValue procedures locate pixel values that may be used to render particular colors in the window given by tkwin. In Tk_GetColor the desired color is specified with a Tk_Uid (nameId), which may have any of the following forms: colorname Any of the valid textual names for a color defined in the server's color database file, such as red or PeachPuff. #RGB #RRGGBB #RRRGGGBBB #RRRRGGGGBBBB A numeric specification of the red, green, and blue intensities to use to display the color. Each R, G, or B represents a single hexadecimal digit. The four forms permit colors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values. When fewer than 16 bits are provided for each color, they represent the most significant bits of the color. For example, #3a7 is the same as #3000a0007000. In Tk_GetColorByValue, the desired color is indicated with the red, green, and blue fields of the structure pointed to by colorPtr. If Tk_GetColor or Tk_GetColorByValue is successful in allocating the desired color, then it returns a pointer to an XColor structure; the structure indicates the exact intensities of the allocated color (which may differ slightly from those requested, depending on the limitations of the screen) and a pixel value that may be used to draw in the color. If the colormap for tkwin is full, Tk_GetColor and Tk_GetColorByValue will use the closest existing color in the colormap. If Tk_GetColor encounters an error while allocating the color (such as an unknown color name) then NULL is returned and an error message is stored in interp->result; Tk_GetColorByValue never returns an error. Tk_GetColor and Tk_GetColorByValue maintain a database of all the colors currently in use. If the same nameId is requested multiple times from Tk_GetColor (e.g. by different windows), or if the same intensities are requested multiple times from Tk_GetColorByValue, then existing pixel values will be re-used. Re-using an existing pixel avoids any interaction with the X server, which makes the allocation much more efficient. For this reason, you should generally use Tk_GetColor or Tk_GetColorByValue instead of Xlib procedures like XAllocColor, XAllocNamedColor, or XParseColor. Since different calls to Tk_GetColor or Tk_GetColorByValue may return the same shared pixel value, callers should never change the color of a pixel returned by the procedures. If you need to change a color value dynamically, you should use XAllocColorCells to allocate the pixel value for the color. The procedure Tk_NameOfColor is roughly the inverse of Tk_GetColor. If its colorPtr argument was created by Tk_GetColor, then the return value is the nameId string that was passed to Tk_GetColor to create the color. If colorPtr was created by a call to Tk_GetColorByValue, or by any other mechanism, then the return value is a string that could be passed to Tk_GetColor to return the same color. Note: the string returned by Tk_NameOfColor is only guaranteed to persist until the next call to Tk_NameOfColor. Tk_GCForColor returns a graphics context whose Foreground field is the pixel allocated for colorPtr and whose other fields all have default values. This provides an easy way to do basic drawing with a color. The graphics context is cached with the color and will exist only as long as colorPtr exists; it is freed when the last reference to colorPtr is freed by calling Tk_FreeColor. When a pixel value returned by Tk_GetColor or Tk_GetColorByValue is no longer needed, Tk_FreeColor should be called to release the color. There should be exactly one call to Tk_FreeColor for each call to Tk_GetColor or Tk_GetColorByValue. When a pixel value is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten) Tk_FreeColor will release it to the X server and delete it from the database. KEYWORDS color, intensity, pixel value ═══ 5.28. Tk_GetCursor ═══ NAME Tk_GetCursor, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursor - maintain database of cursors SYNOPSIS #include Tk_Cursor Tk_GetCursor(interp, tkwin, nameId) Tk_Cursor Tk_GetCursorFromData(interp, tkwin, source, mask, width, height, xHot, yHot, fg, bg) char * Tk_NameOfCursor(display, cursor) Tk_FreeCursor(display, cursor) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. Tk_Window tkwin (in) Token for window in which the cursor will be used. Tk_Uid nameId (in) Description of cursor; see below for possible values. char *source (in) Data for cursor bitmap, in standard bitmap format. char *mask (in) Data for mask bitmap, in standard bitmap format. int width (in) Width of source and mask. int height (in) Height of source and mask. int xHot (in) X-location of cursor hot-spot. int yHot (in) Y-location of cursor hot-spot. Tk_Uid fg (in) Textual description of foreground color for cursor. Tk_Uid bg (in) Textual description of background color for cursor. Display *display (in) Display for which cursor was allocated. Tk_Cursor cursor (in) Opaque Tk identifier for cursor. If passed toTk_FreeCursor, must have been returned by some previous call to Tk_GetCursor or Tk_GetCursorFromData. DESCRIPTION These procedures manage a collection of cursors being used by an application. The procedures allow cursors to be re-used efficiently, thereby avoiding server overhead, and also allow cursors to be named with character strings (actually Tk_Uids). Tk_GetCursor takes as argument a Tk_Uid describing a cursor, and returns an opaque Tk identifier for a cursor corresponding to the description. It re-uses an existing cursor if possible and creates a new one otherwise. NameId must be a standard Tcl list with one of the following forms: name [fgColor [bgColor]] Name is the name of a cursor in the standard X cursor font, i.e., any of the names defined in cursorfont.h, without the XC_. Some example values are X_cursor, hand2, or left_ptr. Appendix B of "The X Window System" by Scheifler & Gettys has illustrations showing what each of these cursors looks like. If fgColor and bgColor are both specified, they give the foreground and background colors to use for the cursor (any of the forms acceptable to Tk_GetColor may be used). If only fgColor is specified, then there will be no background color: the background will be transparent. If no colors are specified, then the cursor will use black for its foreground color and white for its background color. The Macintosh version of Tk also supports all of the X cursors. Tk on the Mac will also accept any of the standard Mac cursors including ibeam, crosshair, watch, plus, and arrow. In addition, Tk will load Macintosh cursor resources of the types crsr (color) and CURS (black and white) by the name of the of the resource. The application and all its open dynamic library's resource files will be searched for the named cursor. If there are conflicts color cursors will always be loaded in preference to black and white cursors. @sourceName maskName fgColor bgColor In this form, sourceName and maskName are the names of files describing bitmaps for the cursor's source bits and mask. Each file must be in standard X11 or X10 bitmap format. FgColor and bgColor indicate the colors to use for the cursor, in any of the forms acceptable to Tk_GetColor. This form of the command will not work on Macintosh or Windows computers. @sourceName fgColor This form is similar to the one above, except that the source is used as mask also. This means that the cursor's background is transparent. This form of the command will not work on Macintosh or Windows computers. Tk_GetCursorFromData allows cursors to be created from in-memory descriptions of their source and mask bitmaps. Source points to standard bitmap data for the cursor's source bits, and mask points to standard bitmap data describing which pixels of source are to be drawn and which are to be considered transparent. Width and height give the dimensions of the cursor, xHot and yHot indicate the location of the cursor's hot-spot (the point that is reported when an event occurs), and fg and bg describe the cursor's foreground and background colors textually (any of the forms suitable for Tk_GetColor may be used). Typically, the arguments to Tk_GetCursorFromData are created by including a cursor file directly into the source code for a program, as in the following example: Tk_Cursor cursor; #include "source.cursor" #include "mask.cursor" cursor = Tk_GetCursorFromData(interp, tkwin, source_bits, mask_bits, source_width, source_height, source_x_hot, source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue")); Under normal conditions, Tk_GetCursor and Tk_GetCursorFromData will return an identifier for the requested cursor. If an error occurs in creating the cursor, such as when nameId refers to a non-existent file, then None is returned and an error message will be stored in interp->result. Tk_GetCursor and Tk_GetCursorFromData maintain a database of all the cursors they have created. Whenever possible, a call to Tk_GetCursor or Tk_GetCursorFromData will return an existing cursor rather than creating a new one. This approach can substantially reduce server overhead, so the Tk procedures should generally be used in preference to Xlib procedures like XCreateFontCursor or XCreatePixmapCursor, which create a new cursor on each call. The procedure Tk_NameOfCursor is roughly the inverse of Tk_GetCursor. If its cursor argument was created by Tk_GetCursor, then the return value is the nameId argument that was passed to Tk_GetCursor to create the cursor. If cursor was created by a call to Tk_GetCursorFromData, or by any other mechanism, then the return value is a hexadecimal string giving the X identifier for the cursor. Note: the string returned by Tk_NameOfCursor is only guaranteed to persist until the next call to Tk_NameOfCursor. Also, this call is not portable except for cursors returned by Tk_GetCursor. When a cursor returned by Tk_GetCursor or Tk_GetCursorFromData is no longer needed, Tk_FreeCursor should be called to release it. There should be exactly one call to Tk_FreeCursor for each call to Tk_GetCursor or Tk_GetCursorFromData. When a cursor is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten) Tk_FreeCursor will release it to the X server and remove it from the database. BUGS In determining whether an existing cursor can be used to satisfy a new request, Tk_GetCursor and Tk_GetCursorFromData consider only the immediate values of their arguments. For example, when a file name is passed to Tk_GetCursor, Tk_GetCursor will assume it is safe to re-use an existing cursor created from the same file name: it will not check to see whether the file itself has changed, or whether the current directory has changed, thereby causing the name to refer to a different file. Similarly, Tk_GetCursorFromData assumes that if the same source pointer is used in two different calls, then the pointers refer to the same data; it does not check to see if the actual data values have changed. KEYWORDS cursor ═══ 5.29. Tk_GetFontStruct ═══ NAME Tk_GetFontStruct, Tk_NameOfFontStruct, Tk_FreeFontStruct - maintain database of fonts SYNOPSIS #include XFontStruct * Tk_GetFontStruct(interp, tkwin, nameId) char * Tk_NameOfFontStruct(fontStructPtr) Tk_FreeFontStruct(fontStructPtr) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. Tk_Window tkwin (in) Token for window in which font will be used. Tk_Uid nameId (in) Name of desired font. XFontStruct *fontStructPtr (in) Font structure to return name for or delete. DESCRIPTION Tk_GetFont loads the font indicated by nameId and returns a pointer to information about the font. The pointer returned by Tk_GetFont will remain valid until Tk_FreeFont is called to release it. NameId can be either a font name or pattern; any value that could be passed to XLoadQueryFont may be passed to Tk_GetFont. If Tk_GetFont is unsuccessful (because, for example, there is no font corresponding to nameId) then it returns NULL and stores an error message in interp->result. Tk_GetFont maintains a database of all fonts it has allocated. If the same nameId is requested multiple times (e.g. by different windows or for different purposes), then additional calls for the same nameId will be handled very quickly, without involving the X server. For this reason, it is generally better to use Tk_GetFont in place of X library procedures like XLoadQueryFont. The procedure Tk_NameOfFontStruct is roughly the inverse of Tk_GetFontStruct. If its fontStructPtr argument was created by Tk_GetFontStruct, then the return value is the nameId argument that was passed to Tk_GetFontStruct to create the font. If fontStructPtr was not created by a call to Tk_GetFontStruct, then the return value is a hexadecimal string giving the X identifier for the associated font. Note: the string returned by Tk_NameOfFontStruct is only guaranteed to persist until the next call to Tk_NameOfFontStruct. When a font returned by Tk_GetFont is no longer needed, Tk_FreeFont should be called to release it. There should be exactly one call to Tk_FreeFont for each call to Tk_GetFont. When a font is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten) Tk_FreeFont will release it to the X server and delete it from the database. KEYWORDS font ═══ 5.30. Tk_GetGC ═══ NAME Tk_GetGC, Tk_FreeGC - maintain database of read-only graphics contexts SYNOPSIS #include GC Tk_GetGC(tkwin, valueMask, valuePtr) Tk_FreeGC(display, gc) ARGUMENTS Tk_Window tkwin (in) Token for window in which the graphics context will be used. unsigned long valueMask (in) Mask of bits (such as GCForeground or GCStipple) indicating which fields of *valuePtr are valid. XGCValues *valuePtr (in) Pointer to structure describing the desired values for the graphics context. Display *display (in) Display for which gc was allocated. GC gc (in) X identifier for graphics context that is no longer needed. Must have been allocated by Tk_GetGC. DESCRIPTION Tk_GetGC and Tk_FreeGC manage a collection of graphics contexts being used by an application. The procedures allow graphics contexts to be shared, thereby avoiding the server overhead that would be incurred if a separate GC were created for each use. Tk_GetGC takes arguments describing the desired graphics context and returns an X identifier for a GC that fits the description. The graphics context that is returned will have default values in all of the fields not specified explicitly by valueMask and valuePtr. Tk_GetGC maintains a database of all the graphics contexts it has created. Whenever possible, a call to Tk_GetGC will return an existing graphics context rather than creating a new one. This approach can substantially reduce server overhead, so Tk_GetGC should generally be used in preference to the Xlib procedure XCreateGC, which creates a new graphics context on each call. Since the return values of Tk_GetGC are shared, callers should never modify the graphics contexts returned by Tk_GetGC. If a graphics context must be modified dynamically, then it should be created by calling XCreateGC instead of Tk_GetGC. When a graphics context is no longer needed, Tk_FreeGC should be called to release it. There should be exactly one call to Tk_FreeGC for each call to Tk_GetGC. When a graphics context is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten) Tk_FreeGC will release it to the X server and delete it from the database. KEYWORDS graphics context ═══ 5.31. Tk_GetImage ═══ NAME Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage - use an image in a widget SYNOPSIS #include Tk_Image Tk_GetImage(interp, tkwin, name, changeProc, clientData) Tk_RedrawImage(image, imageX, imageY, width, height, drawable, drawableX, drawableY) Tk_SizeOfImage(image, widthPtr, heightPtr) Tk_FreeImage(image) ARGUMENTS Tcl_Interp *interp (in) Place to leave error message. Tk_Window tkwin (in) Window in which image will be used. char *name (in) Name of image. Tk_ImageChangedProc *changeProc (in) Procedure for Tk to invoke whenever image content or size changes. ClientData clientData (in) One-word value for Tk to pass to changeProc. Tk_Image image (in) Token for image instance; must have been returned by a previous call to Tk_GetImage. int imageX (in) X-coordinate of upper-left corner of region of image to redisplay (measured in pixels from the image's upper-left corner). int imageY (in) Y-coordinate of upper-left corner of region of image to redisplay (measured in pixels from the image's upper-left corner). int width ((in)) Width of region of image to redisplay. int height ((in)) Height of region of image to redisplay. Drawable drawable (in) Where to display image. Must either be window specified to Tk_GetImage or a pixmap compatible with that window. int drawableX (in) Where to display image in drawable: this is the x-coordinate in drawable where x-coordinate imageX of the image should be displayed. int drawableY (in) Where to display image in drawable: this is the y-coordinate in drawable where y-coordinate imageY of the image should be displayed. int widthPtr (out) Store width of image (in pixels) here. int heightPtr (out) Store height of image (in pixels) here. DESCRIPTION These procedures are invoked by widgets that wish to display images. Tk_GetImage is invoked by a widget when it first decides to display an image. name gives the name of the desired image and tkwin identifies the window where the image will be displayed. Tk_GetImage looks up the image in the table of existing images and returns a token for a new instance of the image. If the image doesn't exist then Tk_GetImage returns NULL and leaves an error message in interp->result. When a widget wishes to actually display an image it must call Tk_RedrawWidget, identifying the image (image), a region within the image to redisplay (imageX, imageY, width, and height), and a place to display the image (drawable, drawableX, and drawableY). Tk will then invoke the appropriate image manager, which will display the requested portion of the image before returning. A widget can find out the dimensions of an image by calling Tk_SizeOfImage: the width and height will be stored in the locations given by widthPtr and heightPtr, respectively. When a widget is finished with an image (e.g., the widget is being deleted or it is going to use a different image instead of the current one), it must call Tk_FreeImage to release the image instance. The widget should never again use the image token after passing it to Tk_FreeImage. There must be exactly one call to Tk_FreeImage for each call to Tk_GetImage. If the contents or size of an image changes, then any widgets using the image will need to find out about the changes so that they can redisplay themselves. The changeProc and clientData arguments to Tk_GetImage are used for this purpose. changeProc will be called by Tk whenever a change occurs in the image; it must match the following prototype: typedef void Tk_ImageChangedProc( ClientData clientData, int x, int y, int width, int height, int imageWidth, int imageHeight); The clientData argument to changeProc is the same as the clientData argument to Tk_GetImage. It is usually a pointer to the widget record for the widget or some other data structure managed by the widget. The arguments x, y, width, and height identify a region within the image that must be redisplayed; they are specified in pixels measured from the upper-left corner of the image. The arguments imageWidth and imageHeight give the image's (new) size. SEE ALSO Tk_CreateImageType KEYWORDS images, redisplay ═══ 5.32. Tk_GetJoinStyle ═══ NAME Tk_GetJoinStyle, Tk_NameOfJoinStyle - translate between strings and join styles SYNOPSIS #include int Tk_GetJoinStyle(interp, string, joinPtr) char * Tk_NameOfJoinStyle(join) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. char *string (in) String containing name of join style: one of "bevel", "miter", or "round". int *joinPtr (out) Pointer to location in which to store X join style corresponding to string. int join (in) Join style: one of JoinBevel, JoinMiter, JoinRound. DESCRIPTION Tk_GetJoinStyle places in *joinPtr the X join style corresponding to string, which will be one of JoinBevel, JoinMiter, or JoinRound. Join styles are typically used in X graphics contexts to indicate how adjacent line segments should be joined together. See the X documentation for information on what each style implies. Under normal circumstances the return value is TCL_OK and interp is unused. If string doesn't contain a valid join style or an abbreviation of one of these names, then an error message is stored in interp->result, TCL_ERROR is returned, and *joinPtr is unmodified. Tk_NameOfJoinStyle is the logical inverse of Tk_GetJoinStyle. Given a join style such as JoinBevel it returns a statically-allocated string corresponding to join. If join isn't a legal join style, then "unknown join style" is returned. KEYWORDS bevel, join style, miter, round ═══ 5.33. Tk_GetJustify ═══ NAME Tk_GetJustify, Tk_NameOfJustify - translate between strings and justification styles SYNOPSIS #include Tk_Justify Tk_GetJustify(interp, string, justifyPtr) char * Tk_NameOfJustify(justify) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. char *string (in) String containing name of justification style ("left", "right", or "center"). int *justifyPtr (out) Pointer to location in which to store justify value corresponding to string. Tk_Justify justify (in) Justification style (one of the values listed below). DESCRIPTION Tk_GetJustify places in *justifyPtr the justify value corresponding to string. This value will be one of the following: TK_JUSTIFY_LEFT Means that the text on each line should start at the left edge of the line; as a result, the right edges of lines may be ragged. TK_JUSTIFY_RIGHT Means that the text on each line should end at the right edge of the line; as a result, the left edges of lines may be ragged. TK_JUSTIFY_CENTER Means that the text on each line should be centered; as a result, both the left and right edges of lines may be ragged. Under normal circumstances the return value is TCL_OK and interp is unused. If string doesn't contain a valid justification style or an abbreviation of one of these names, then an error message is stored in interp->result, TCL_ERROR is returned, and *justifyPtr is unmodified. Tk_NameOfJustify is the logical inverse of Tk_GetJustify. Given a justify value it returns a statically-allocated string corresponding to justify. If justify isn't a legal justify value, then "unknown justification style" is returned. KEYWORDS center, fill, justification, string ═══ 5.34. Tk_GetOption ═══ NAME Tk_GetOption - retrieve an option from the option database SYNOPSIS #include Tk_Uid Tk_GetOption(tkwin, name, class) ARGUMENTS Tk_Window tkwin (in) Token for window. char *name (in) Name of desired option. char *class (in) Class of desired option. Null means there is no class for this option; do lookup based on name only. DESCRIPTION This procedure is invoked to retrieve an option from the database associated with tkwin's main window. If there is an option for tkwin that matches the given name or class, then it is returned in the form of a Tk_Uid. If multiple options match name and class, then the highest-priority one is returned. If no option matches, then NULL is returned. Tk_GetOption caches options related to tkwin so that successive calls for the same tkwin will execute much more quickly than successive calls for different windows. KEYWORDS class, name, option, retrieve ═══ 5.35. Tk_GetPixels ═══ NAME Tk_GetPixels, Tk_GetScreenMM - translate between strings and screen units SYNOPSIS #include int Tk_GetPixels(interp, tkwin, string, intPtr) int Tk_GetScreenMM(interp, tkwin, string, doublePtr) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. Tk_Window tkwin (in) Window whose screen geometry determines the conversion between absolute units and pixels. char *string (in) String that specifies a distance on the screen. int *intPtr (out) Pointer to location in which to store converted distance in pixels. double *doublePtr (out) Pointer to location in which to store converted distance in millimeters. DESCRIPTION These two procedures take as argument a specification of distance on the screen (string) and compute the corresponding distance either in integer pixels or floating-point millimeters. In either case, string specifies a screen distance as a floating-point number followed by one of the following characters that indicates units: The number specifies a distance in pixels. c The number specifies a distance in centimeters on the screen. i The number specifies a distance in inches on the screen. m The number specifies a distance in millimeters on the screen. p The number specifies a distance in printer's points (1/72 inch) on the screen. Tk_GetPixels converts string to the nearest even number of pixels and stores that value at *intPtr. Tk_GetScreenMM converts string to millimeters and stores the double-precision floating-point result at *doublePtr. Both procedures return TCL_OK under normal circumstances. If an error occurs (e.g. string contains a number followed by a character that isn't one of the ones above) then TCL_ERROR is returned and an error message is left in interp->result. KEYWORDS centimeters, convert, inches, millimeters, pixels, points, screen units ═══ 5.36. Tk_GetPixmap ═══ NAME Tk_GetPixmap, Tk_FreePixmap - allocate and free pixmaps SYNOPSIS #include Pixmap Tk_GetPixmap(display, d, width, height, depth) Tk_FreePixmap(display, pixmap) ARGUMENTS Display *display (in) X display for the pixmap. Drawable d (in) Pixmap or window where the new pixmap will be used for drawing. int width (in) Width of pixmap. int height (in) Height of pixmap. int depth (in) Number of bits per pixel in pixmap. Pixmap pixmap (in) Pixmap to destroy. DESCRIPTION These procedures are identical to the Xlib procedures XCreatePixmap and XFreePixmap, except that they have extra code to manage X resource identifiers so that identifiers for deleted pixmaps can be reused in the future. It is important for Tk applications to use these procedures rather than XCreatePixmap and XFreePixmap; otherwise long-running applications may run out of resource identifiers. Tk_GetPixmap creates a pixmap suitable for drawing in d, with dimensions given by width, height, and depth, and returns its identifier. Tk_FreePixmap destroys the pixmap given by pixmap and makes its resource identifier available for reuse. KEYWORDS pixmap, resource identifier ═══ 5.37. Tk_GetRelief ═══ NAME Tk_GetRelief, Tk_NameOfRelief - translate between strings and relief values SYNOPSIS #include int Tk_GetRelief(interp, name, reliefPtr) char * Tk_NameOfRelief(relief) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. char *name (in) String containing relief name (one of "flat", "groove", "raised", "ridge", or "sunken"). int *reliefPtr (out) Pointer to location in which to store relief value corresponding to name. int relief (in) Relief value (one of TK_RELIEF_FLAT, TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, or TK_RELIEF_RIDGE). DESCRIPTION Tk_GetRelief places in *reliefPtr the relief value corresponding to name. This value will be one of TK_RELIEF_FLAT, TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, or TK_RELIEF_RIDGE. Under normal circumstances the return value is TCL_OK and interp is unused. If name doesn't contain one of the valid relief names or an abbreviation of one of them, then an error message is stored in interp->result, TCL_ERROR is returned, and *reliefPtr is unmodified. Tk_NameOfRelief is the logical inverse of Tk_GetRelief. Given a relief value it returns the corresponding string ("flat", "raised", "sunken", "groove", or "ridge"). If relief isn't a legal relief value, then "unknown relief" is returned. KEYWORDS name, relief, string ═══ 5.38. Tk_GetRootCoords ═══ NAME Tk_GetRootCoords - Compute root-window coordinates of window SYNOPSIS #include Tk_GetRootCoords(tkwin, xPtr, yPtr) ARGUMENTS Tk_Window tkwin (in) Token for window. int *xPtr (out) Pointer to location in which to store root-window x-coordinate corresponding to left edge of tkwin's border. int *yPtr (out) Pointer to location in which to store root-window y-coordinate corresponding to top edge of tkwin's border. DESCRIPTION This procedure scans through the structural information maintained by Tk to compute the root-window coordinates corresponding to the upper-left corner of tkwin's border. If tkwin has no border, then Tk_GetRootCoords returns the root-window coordinates corresponding to location (0,0) in tkwin. Tk_GetRootCoords is relatively efficient, since it doesn't have to communicate with the X server. KEYWORDS coordinates, root window ═══ 5.39. Tk_GetScrollInfo ═══ NAME Tk_GetScrollInfo - parse arguments for scrolling commands SYNOPSIS #include int Tk_GetScrollInfo(interp, argc, argv, dblPtr, intPtr) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. int argc (in) Number of strings in argv array. char *argv[] (in) Argument strings. These represent the entire widget command, of which the first word is typically the widget name and the second word is typically xview or yview. This procedure parses arguments starting with argv[2]. double *dblPtr (out) Filled in with fraction from moveto option, if any. int *intPtr (out) Filled in with line or page count from scroll option, if any. The value may be negative. DESCRIPTION Tk_GetScrollInfo parses the arguments expected by widget scrolling commands such as xview and yview. It receives the entire list of words that make up a widget command and parses the words starting with argv[2]. The words starting with argv[2] must have one of the following forms: moveto fraction scroll number units scroll number pages Any of the moveto, scroll, units, and pages keywords may be abbreviated. If argv has the moveto form, TK_SCROLL_MOVETO is returned as result and *dblPtr is filled in with the fraction argument to the command, which must be a proper real value. If argv has the scroll form, TK_SCROLL_UNITS or TK_SCROLL_PAGES is returned and *intPtr is filled in with the number value, which must be a proper integer. If an error occurs in parsing the arguments, TK_SCROLL_ERROR is returned and an error message is left in interp->result. KEYWORDS parse, scrollbar, scrolling command, xview, yview ═══ 5.40. Tk_GetSelection ═══ NAME Tk_GetSelection - retrieve the contents of a selection SYNOPSIS #include int Tk_GetSelection(interp, tkwin, selection, target, proc, clientData) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for reporting errors. Tk_Window tkwin (in) Window on whose behalf to retrieve the selection (determines display from which to retrieve). Atom selection (in) The name of the selection to be retrieved. Atom target (in) Form in which to retrieve selection. Tk_GetSelProc *proc (in) Procedure to invoke to process pieces of the selection as they are retrieved. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION Tk_GetSelection retrieves the selection specified by the atom selection in the format specified by target. The selection may actually be retrieved in several pieces; as each piece is retrieved, proc is called to process the piece. Proc should have arguments and result that match the type Tk_GetSelProc: typedef int Tk_GetSelProc( ClientData clientData, Tcl_Interp *interp, char *portion); The clientData and interp parameters to proc will be copies of the corresponding arguments to Tk_GetSelection. Portion will be a pointer to a string containing part or all of the selection. For large selections, proc will be called several times with successive portions of the selection. The X Inter-Client Communication Conventions Manual allows a selection to be returned in formats other than strings, e.g. as an array of atoms or integers. If this happens, Tk converts the selection back into a string before calling proc. If a selection is returned as an array of atoms, Tk converts it to a string containing the atom names separated by white space. For any other format besides string, Tk converts a selection to a string containing hexadecimal values separated by white space. Tk_GetSelection returns to its caller when the selection has been completely retrieved and processed by proc, or when a fatal error has occurred (e.g. the selection owner didn't respond promptly). Tk_GetSelection normally returns TCL_OK; if an error occurs, it returns TCL_ERROR and leaves an error message in interp->result. Proc should also return either TCL_OK or TCL_ERROR. If proc encounters an error in dealing with the selection, it should leave an error message in interp->result and return TCL_ERROR; this will abort the selection retrieval. KEYWORDS format, get, selection retrieval ═══ 5.41. Tk_GetUid ═══ NAME Tk_GetUid, Tk_Uid - convert from string to unique identifier SYNOPSIS #include #typedef char *Tk_Uid Tk_Uid Tk_GetUid(string) ARGUMENTS char *string (in) String for which the corresponding unique identifier is desired. DESCRIPTION Tk_GetUid returns the unique identifier corresponding to string. Unique identifiers are similar to atoms in Lisp, and are used in Tk to speed up comparisons and searches. A unique identifier (type Tk_Uid) is a string pointer and may be used anywhere that a variable of type "char *" could be used. However, there is guaranteed to be exactly one unique identifier for any given string value. If Tk_GetUid is called twice, once with string a and once with string b, and if a and b have the same string value (strcmp(a, b) == 0), then Tk_GetUid will return exactly the same Tk_Uid value for each call (Tk_GetUid(a) == Tk_GetUid(b)). This means that variables of type Tk_Uid may be compared directly (x == y) without having to call strcmp. In addition, the return value from Tk_GetUid will have the same string value as its argument (strcmp(Tk_GetUid(a), a) == 0). KEYWORDS atom, unique identifier ═══ 5.42. Tk_GetVRootGeometry ═══ NAME Tk_GetVRootGeometry - Get location and size of virtual root for window SYNOPSIS #include Tk_GetVRootGeometry(tkwin, xPtr, yPtr, widthPtr, heightPtr) ARGUMENTS Tk_Window tkwin (in) Token for window whose virtual root is to be queried. int xPtr (out) Points to word in which to store x-offset of virtual root. int yPtr (out) Points to word in which to store y-offset of virtual root. int widthPtr (out) Points to word in which to store width of virtual root. int heightPtr (out) Points to word in which to store height of virtual root. DESCRIPTION TkGetVRootGeometry returns geometry information about the virtual root window associated with tkwin. The "associated" virtual root is the one in which tkwin's nearest top-level ancestor (or tkwin itself if it is a top-level window) has been reparented by the window manager. This window is identified by a __SWM_ROOT or __WM_ROOT property placed on the top-level window by the window manager. If tkwin is not associated with a virtual root (e.g. because the window manager doesn't use virtual roots) then *xPtr and *yPtr will be set to 0 and *widthPtr and *heightPtr will be set to the dimensions of the screen containing tkwin. KEYWORDS geometry, height, location, virtual root, width, window manager ═══ 5.43. Tk_GetVisual ═══ NAME Tk_GetVisual - translate from string to visual SYNOPSIS #include Visual * Tk_GetVisual(interp, tkwin, string, depthPtr, colormapPtr) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for error reporting. Tk_Window tkwin (in) Token for window in which the visual will be used. char *string (in) String that identifies the desired visual. See below for valid formats. int *depthPtr (out) Depth of returned visual gets stored here. Colormap *colormapPtr (out) If non-NULL then a suitable colormap for visual is found and its identifier is stored here. DESCRIPTION Tk_GetVisual takes a string description of a visual and finds a suitable X Visual for use in tkwin, if there is one. It returns a pointer to the X Visual structure for the visual and stores the number of bits per pixel for it at *depthPtr. If string is unrecognizable or if no suitable visual could be found, then NULL is returned and Tk_GetVisual leaves an error message in interp->result. If colormap is non-NULL then Tk_GetVisual also locates an appropriate colormap for use with the result visual and stores its X identifier at *colormapPtr. The string argument specifies the desired visual in one of the following ways: class depth The string consists of a class name followed by an integer depth, with any amount of white space (including none) in between. class selects what sort of visual is desired and must be one of directcolor, grayscale, greyscale, pseudocolor, staticcolor, staticgray, staticgrey, or truecolor, or a unique abbreviation. depth specifies how many bits per pixel are needed for the visual. If possible, Tk_GetVisual will return a visual with this depth; if there is no visual of the desired depth then Tk_GetVisual looks first for a visual with greater depth, then one with less depth. default Use the default visual for tkwin's screen. pathName Use the visual for the window given by pathName. pathName must be the name of a window on the same screen as tkwin. number Use the visual whose X identifier is number. best ?depth? Choose the "best possible" visual, using the following rules, in decreasing order of priority: (a) a visual that has exactly the desired depth is best, followed by a visual with greater depth than requested (but as little extra as possible), followed by a visual with less depth than requested (but as great a depth as possible); (b) if no depth is specified, then the deepest available visual is chosen; (c) pseudocolor is better than truecolor or directcolor, which are better than staticcolor, which is better than staticgray or grayscale; (d) the default visual for the screen is better than any other visual. CREDITS The idea for Tk_GetVisual, and the first implementation, came from Paul Mackerras. KEYWORDS colormap, screen, visual ═══ 5.44. Tk_HandleEvent ═══ NAME Tk_HandleEvent - invoke event handlers for window system events SYNOPSIS #include Tk_HandleEvent(eventPtr) ARGUMENTS XEvent *eventPtr (in) Pointer to X event to dispatch to relevant handler(s). DESCRIPTION Tk_HandleEvent is a lower-level procedure that deals with window events. It is called by Tk_ServiceEvent (and indirectly by Tk_DoOneEvent), and in a few other cases within Tk. It makes callbacks to any window event handlers (created by calls to Tk_CreateEventHandler) that match eventPtr and then returns. In some cases it may be useful for an application to bypass the Tk event queue and call Tk_HandleEvent directly instead of calling Tk_QueueEvent followed by Tk_ServiceEvent. This procedure may be invoked recursively. For example, it is possible to invoke Tk_HandleEvent recursively from a handler called by Tk_HandleEvent. This sort of operation is useful in some modal situations, such as when a notifier has been popped up and an application wishes to wait for the user to click a button in the notifier before doing anything else. KEYWORDS callback, event, handler, window ═══ 5.45. Tk_IdToWindow ═══ NAME Tk_IdToWindow - Find Tk's window information for an X window SYNOPSIS #include Tk_Window Tk_IdToWindow(display, window) ARGUMENTS Display *display (in) X display containing the window. Window window (in) X id for window. DESCRIPTION Given an X window identifier and the X display it corresponds to, this procedure returns the corresponding Tk_Window handle. If there is no Tk_Window corresponding to window then NULL is returned. KEYWORDS X window id ═══ 5.46. Tk_ImageChanged ═══ NAME Tk_ImageChanged - notify widgets that image needs to be redrawn SYNOPSIS #include Tk_ImageChanged(imageMaster, x, y, width, height, imageWidth, imageHeight) ARGUMENTS Tk_ImageMaster imageMaster (in) Token for image, which was passed to image's createProc when the image was created. int x (in) X-coordinate of upper-left corner of region that needs redisplay (measured from upper-left corner of image). int y (in) Y-coordinate of upper-left corner of region that needs redisplay (measured from upper-left corner of image). int width (in) Width of region that needs to be redrawn, in pixels. int height (in) Height of region that needs to be redrawn, in pixels. int imageWidth (in) Current width of image, in pixels. int imageHeight (in) Current height of image, in pixels. DESCRIPTION An image manager calls Tk_ImageChanged for an image whenever anything happens that requires the image to be redrawn. As a result of calling Tk_ImageChanged, any widgets using the image are notified so that they can redisplay themselves appropriately. The imageMaster argument identifies the image, and x, y, width, and height specify a rectangular region within the image that needs to be redrawn. imageWidth and imageHeight specify the image's (new) size. An image manager should call Tk_ImageChanged during its createProc to specify the image's initial size and to force redisplay if there are existing instances for the image. If any of the pixel values in the image should change later on, Tk_ImageChanged should be called again with x, y, width, and height values that cover all the pixels that changed. If the size of the image should change, then Tk_ImageChanged must be called to indicate the new size, even if no pixels need to be redisplayed. SEE ALSO Tk_CreateImageType KEYWORDS images, redisplay, image size changes ═══ 5.47. Tk_InternAtom ═══ NAME Tk_InternAtom, Tk_GetAtomName - manage cache of X atoms SYNOPSIS #include Atom Tk_InternAtom(tkwin, name) char * Tk_GetAtomName(tkwin, atom) ARGUMENTS Tk_Window tkwin (in) Token for window. Used to map atom or name relative to a particular display. char *name (in) String name for which atom is desired. Atom atom (in) Atom for which corresponding string name is desired. DESCRIPTION These procedures are similar to the Xlib procedures XInternAtom and XGetAtomName. Tk_InternAtom returns the atom identifier associated with string given by name; the atom identifier is only valid for the display associated with tkwin. Tk_GetAtomName returns the string associated with atom on tkwin's display. The string returned by Tk_GetAtomName is in Tk's storage: the caller need not free this space when finished with the string, and the caller should not modify the contents of the returned string. If there is no atom atom on tkwin's display, then Tk_GetAtomName returns the string "?bad atom?". Tk caches the information returned by Tk_InternAtom and Tk_GetAtomName so that future calls for the same information can be serviced from the cache without contacting the server. Thus Tk_InternAtom and Tk_GetAtomName are generally much faster than their Xlib counterparts, and they should be used in place of the Xlib procedures. KEYWORDS atom, cache, display ═══ 5.48. Tk_MainLoop ═══ NAME Tk_MainLoop - loop for events until all windows are deleted SYNOPSIS #include Tk_MainLoop() DESCRIPTION Tk_MainLoop is a procedure that loops repeatedly calling Tcl_DoOneEvent. It returns only when there are no applications left in this process (i.e. no main windows exist anymore). Most windowing applications will call Tk_MainLoop after initialization; the main execution of the application will consist entirely of callbacks invoked via Tcl_DoOneEvent. KEYWORDS application, event, main loop ═══ 5.49. Tk_MainWindow ═══ NAME Tk_MainWindow - find the main window for an application SYNOPSIS #include Tk_Window Tk_MainWindow(interp) ARGUMENTS Tcl_Interp *interp (in/out) Interpreter associated with the application. DESCRIPTION If interp is associated with a Tk application then Tk_MainWindow returns the application's main window. If there is no Tk application associated with interp then Tk_MainWindow returns NULL and leaves an error message in interp->result. KEYWORDS application, main window ═══ 5.50. Tk_MaintainGeometry ═══ NAME Tk_MaintainGeometry, Tk_UnmaintainGeometry - maintain geometry of one window relative to another SYNOPSIS #include Tk_MaintainGeometry(slave, master, x, y, width, height) Tk_UnmaintainGeometry(slave, master) ARGUMENTS Tk_Window slave (in) Window whose geometry is to be controlled. Tk_Window master (in) Window relative to which slave's geometry will be controlled. int x (in) Desired x-coordinate of slave in master, measured in pixels from the inside of master's left border to the outside of slave's left border. int y (in) Desired y-coordinate of slave in master, measured in pixels from the inside of master's top border to the outside of slave's top border. int width (in) Desired width for slave, in pixels. int height (in) Desired height for slave, in pixels. DESCRIPTION Tk_MaintainGeometry and Tk_UnmaintainGeometry make it easier for geometry managers to deal with slaves whose masters are not their parents. Three problems arise if the master for a slave is not its parent: 1. The x- and y-position of the slave must be translated from the coordinate system of the master to that of the parent before positioning the slave. 2. If the master window, or any of its ancestors up to the slave's parent, is moved, then the slave must be repositioned within its parent in order to maintain the correct position relative to the master. 3. If the master or one of its ancestors is mapped or unmapped, then the slave must be mapped or unmapped to correspond. None of these problems is an issue if the parent and master are the same. For example, if the master or one of its ancestors is unmapped, the slave is automatically removed by the screen by X. Tk_MaintainGeometry deals with these problems for slaves whose masters aren't their parents. Tk_MaintainGeometry is typically called by a window manager once it has decided where a slave should be positioned relative to its master. Tk_MaintainGeometry translates the coordinates to the coordinate system of slave's parent and then moves and resizes the slave appropriately. Furthermore, it remembers the desired position and creates event handlers to monitor the master and all of its ancestors up to (but not including) the slave's parent. If any of these windows is moved, mapped, or unmapped, the slave will be adjusted so that it is mapped only when the master is mapped and its geometry relative to the master remains as specified by x, y, width, and height. When a window manager relinquishes control over a window, or if it decides that it does not want the window to appear on the screen under any conditions, it calls Tk_UnmaintainGeometry. Tk_UnmaintainGeometry unmaps the window and cancels any previous calls to Tk_MaintainGeometry for the master-slave pair, so that the slave's geometry and mapped state are no longer maintained automatically. Tk_UnmaintainGeometry need not be called by a geometry manager if the slave, the master, or any of the master's ancestors is destroyed: Tk will call it automatically. If Tk_MaintainGeometry is called repeatedly for the same master-slave pair, the information from the most recent call supersedes any older information. If Tk_UnmaintainGeometry is called for a master-slave pair that is isn't currently managed, the call has no effect. KEYWORDS geometry manager, map, master, parent, position, slave, unmap ═══ 5.51. Tk_ManageGeometry ═══ NAME Tk_ManageGeometry - arrange to handle geometry requests for a window SYNOPSIS #include Tk_ManageGeometry(tkwin, mgrPtr, clientData) ARGUMENTS Tk_Window tkwin (in) Token for window to be managed. Tk_GeomMgr *mgrPtr (in) Pointer to data structure containing information about the geometry manager, or NULL to indicate that tkwin's geometry shouldn't be managed anymore. The data structure pointed to by mgrPtr must be static: Tk keeps a reference to it as long as the window is managed. ClientData clientData (in) Arbitrary one-word value to pass to geometry manager callbacks. DESCRIPTION Tk_ManageGeometry arranges for a particular geometry manager, described by the mgrPtr argument, to control the geometry of a particular slave window, given by tkwin. If tkwin was previously managed by some other geometry manager, the previous manager loses control in favor of the new one. If mgrPtr is NULL, geometry management is cancelled for tkwin. The structure pointed to by mgrPtr contains information about the geometry manager: typedef struct { char *name; Tk_GeomRequestProc *requestProc; Tk_GeomLostSlaveProc *lostSlaveProc; } Tk_GeomMgr; The name field is the textual name for the geometry manager, such as pack or place; this value will be returned by the command winfo manager. requestProc is a procedure in the geometry manager that will be invoked whenever Tk_GeometryRequest is called by the slave to change its desired geometry. requestProc should have arguments and results that match the type Tk_GeomRequestProc: typedef void Tk_GeomRequestProc( ClientData clientData, Tk_Window tkwin); The parameters to requestProc will be identical to the corresponding parameters passed to Tk_ManageGeometry. clientData usually points to a data structure containing application-specific information about how to manage tkwin's geometry. The lostSlaveProc field of mgrPtr points to another procedure in the geometry manager. Tk will invoke lostSlaveProc if some other manager calls Tk_ManageGeometry to claim tkwin away from the current geometry manager. lostSlaveProc is not invoked if Tk_ManageGeometry is called with a NULL value for mgrPtr (presumably the current geometry manager has made this call, so it already knows that the window is no longer managed), nor is it called if mgrPtr is the same as the window's current geometry manager. lostSlaveProc should have arguments and results that match the following prototype: typedef void Tk_GeomLostSlaveProc( ClientData clientData, Tk_Window tkwin); The parameters to lostSlaveProc will be identical to the corresponding parameters passed to Tk_ManageGeometry. KEYWORDS callback, geometry, managed, request, unmanaged ═══ 5.52. Tk_MapWindow ═══ NAME Tk_MapWindow, Tk_UnmapWindow - map or unmap a window SYNOPSIS #include Tk_Window Tk_MapWindow(tkwin) Tk_UnmapWindow(tkwin) ARGUMENTS Tk_Window tkwin (in) Token for window. DESCRIPTION These procedures may be used to map and unmap windows managed by Tk. Tk_MapWindow maps the window given by tkwin, and also creates an X window corresponding to tkwin if it doesn't already exist. See the Tk_CreateWindow manual entry for information on deferred window creation. Tk_UnmapWindow unmaps tkwin's window from the screen. If tkwin is a child window (i.e. Tk_CreateChildWindow was used to create it), then event handlers interested in map and unmap events are invoked immediately. If tkwin isn't an internal window, then the event handlers will be invoked later, after X has seen the request and returned an event for it. These procedures should be used in place of the X procedures XMapWindow and XUnmapWindow, since they update Tk's local data structure for tkwin. Applications using Tk should not invoke XMapWindow and XUnmapWindow directly. KEYWORDS map, unmap, window ═══ 5.53. Tk_MoveToplevelWindow ═══ NAME Tk_MoveToplevelWindow - Adjust the position of a top-level window SYNOPSIS #include Tk_MoveToplevelWindow(tkwin, x, y) ARGUMENTS Tk_Window tkwin (in) Token for top-level window to move. int x (in) New x-coordinate for the top-left pixel of tkwin's border, or the top-left pixel of the decorative border supplied for tkwin by the window manager, if there is one. int y (in) New y-coordinate for the top-left pixel of tkwin's border, or the top-left pixel of the decorative border supplied for tkwin by the window manager, if there is one. DESCRIPTION In general, a window should never set its own position; this should be done only by the geometry manger that is responsible for the window. For top-level windows the window manager is effectively the geometry manager; Tk provides interface code between the application and the window manager to convey the application's desires to the geometry manager. The desired size for a top-level window is conveyed using the usual Tk_GeometryRequest mechanism. The procedure Tk_MoveToplevelWindow may be used by an application to request a particular position for a top-level window; this procedure is similar in function to the wm geometry Tcl command except that negative offsets cannot be specified. It is invoked by widgets such as menus that want to appear at a particular place on the screen. When Tk_MoveToplevelWindow is called it doesn't immediately pass on the new desired location to the window manager; it defers this action until all other outstanding work has been completed, using the Tk_DoWhenIdle mechanism. KEYWORDS position, top-level window, window manager ═══ 5.54. Tk_Name ═══ NAME Tk_Name, Tk_PathName, Tk_NameToWindow - convert between names and window tokens SYNOPSIS #include Tk_Uid Tk_Name(tkwin) char * Tk_PathName(tkwin) Tk_Window Tk_NameToWindow(interp, pathName, tkwin) ARGUMENTS Tk_Window tkwin (in) Token for window. Tcl_Interp *interp (out) Interpreter to use for error reporting. char *pathName (in) Character string containing path name of window. DESCRIPTION Each window managed by Tk has two names, a short name that identifies a window among children of the same parent, and a path name that identifies the window uniquely among all the windows belonging to the same main window. The path name is used more often in Tk than the short name; many commands, like bind, expect path names as arguments. The Tk_Name macro returns a window's short name, which is the same as the name argument passed to Tk_CreateWindow when the window was created. The value is returned as a Tk_Uid, which may be used just like a string pointer but also has the properties of a unique identifier (see the manual entry for Tk_GetUid for details). The Tk_PathName macro returns a hierarchical name for tkwin. Path names have a structure similar to file names in Unix but with dots between elements instead of slashes: the main window for an application has the path name "."; its children have names like ".a" and ".b"; their children have names like ".a.aa" and ".b.bb"; and so on. A window is considered to be be a child of another window for naming purposes if the second window was named as the first window's parent when the first window was created. This is not always the same as the X window hierarchy. For example, a pop-up is created as a child of the root window, but its logical parent will usually be a window within the application. The procedure Tk_NameToWindow returns the token for a window given its path name (the pathName argument) and another window belonging to the same main window (tkwin). It normally returns a token for the named window, but if no such window exists Tk_NameToWindow leaves an error message in interp->result and returns NULL. The tkwin argument to Tk_NameToWindow is needed because path names are only unique within a single application hierarchy. If, for example, a single process has opened two main windows, each will have a separate naming hierarchy and the same path name might appear in each of the hierarchies. Normally tkwin is the main window of the desired hierarchy, but this need not be the case: any window in the desired hierarchy may be used. KEYWORDS name, path name, token, window ═══ 5.55. Tk_NameOfImage ═══ NAME Tk_NameOfImage - Return name of image. SYNOPSIS #include char * Tk_NameOfImage(typePtr) ARGUMENTS Tk_ImageMaster *masterPtr (in) Token for image, which was passed to image manager's createProc when the image was created. DESCRIPTION This procedure is invoked by image managers to find out the name of an image. Given the token for the image, it returns the string name for the image. KEYWORDS image manager, image name ═══ 5.56. Tk_OwnSelection ═══ NAME Tk_OwnSelection - make a window the owner of the primary selection SYNOPSIS #include Tk_OwnSelection(tkwin, selection, proc, clientData) ARGUMENTS Tk_Window tkwin (in) Window that is to become new selection owner. Atom selection (in) The name of the selection to be owned, such as XA_PRIMARY. Tk_LostSelProc *proc (in) Procedure to invoke when tkwin loses selection ownership later. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION Tk_OwnSelection arranges for tkwin to become the new owner of the selection specified by the atom selection. After this call completes, future requests for the selection will be directed to handlers created for tkwin using Tk_CreateSelHandler. When tkwin eventually loses the selection ownership, proc will be invoked so that the window can clean itself up (e.g. by unhighlighting the selection). Proc should have arguments and result that match the type Tk_LostSelProc: typedef void Tk_LostSelProc(ClientData clientData); The clientData parameter to proc is a copy of the clientData argument given to Tk_OwnSelection, and is usually a pointer to a data structure containing application-specific information about tkwin. KEYWORDS own, selection owner ═══ 5.57. Tk_ParseArgv ═══ NAME Tk_ParseArgv - process command-line options SYNOPSIS #include int Tk_ParseArgv(interp, tkwin, argcPtr, argv, argTable, flags) ARGUMENTS Tcl_Interp *interp (in) Interpreter to use for returning error messages. Tk_Window tkwin (in) Window to use when arguments specify Tk options. If NULL, then no Tk options will be processed. int argcPtr (in/out) Pointer to number of arguments in argv; gets modified to hold number of unprocessed arguments that remain after the call. char **argv (in/out) Command line arguments passed to main program. Modified to hold unprocessed arguments that remain after the call. Tk_ArgvInfo *argTable (in) Array of argument descriptors, terminated by element with type TK_ARGV_END. int flags (in) If non-zero, then it specifies one or more flags that control the parsing of arguments. Different flags may be OR'ed together. The flags currently defined are TK_ARGV_DONT_SKIP_FIRST_ARG, TK_ARGV_NO_ABBREV, TK_ARGV_NO_LEFTOVERS, and TK_ARGV_NO_DEFAULTS. DESCRIPTION Tk_ParseArgv processes an array of command-line arguments according to a table describing the kinds of arguments that are expected. Each of the arguments in argv is processed in turn: if it matches one of the entries in argTable, the argument is processed according to that entry and discarded. The arguments that do not match anything in argTable are copied down to the beginning of argv (retaining their original order) and returned to the caller. At the end of the call Tk_ParseArgv sets *argcPtr to hold the number of arguments that are left in argv, and argv[*argcPtr] will hold the value NULL. Normally, Tk_ParseArgv assumes that argv[0] is a command name, so it is treated like an argument that doesn't match argTable and returned to the caller; however, if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in flags then argv[0] will be processed just like the other elements of argv. Tk_ParseArgv normally returns the value TCL_OK. If an error occurs while parsing the arguments, then TCL_ERROR is returned and Tk_ParseArgv will leave an error message in interp->result in the standard Tcl fashion. In the event of an error return, *argvPtr will not have been modified, but argv could have been partially modified. The possible causes of errors are explained below. The argTable array specifies the kinds of arguments that are expected; each of its entries has the following structure: typedef struct { char *key; int type; char *src; char *dst; char *help; } Tk_ArgvInfo; The key field is a string such as "-display" or "-bg" that is compared with the values in argv. Type indicates how to process an argument that matches key (more on this below). Src and dst are additional values used in processing the argument. Their exact usage depends on type, but typically src indicates a value and dst indicates where to store the value. The char * declarations for src and dst are placeholders: the actual types may be different. Lastly, help is a string giving a brief description of this option; this string is printed when users ask for help about command-line options. When processing an argument in argv, Tk_ParseArgv compares the argument to each of the key's in argTable. Tk_ParseArgv selects the first specifier whose key matches the argument exactly, if such a specifier exists. Otherwise Tk_ParseArgv selects a specifier for which the argument is a unique abbreviation. If the argument is a unique abbreviation for more than one specifier, then an error is returned. If there is no matching entry in argTable, then the argument is skipped and returned to the caller. Once a matching argument specifier is found, Tk_ParseArgv processes the argument according to the type field of the specifier. The argument that matched key is called "the matching argument" in the descriptions below. As part of the processing, Tk_ParseArgv may also use the next argument in argv after the matching argument, which is called "the following argument". The legal values for type, and the processing that they cause, are as follows: TK_ARGV_END Marks the end of the table. The last entry in argTable must have this type; all of its other fields are ignored and it will never match any arguments. TK_ARGV_CONSTANT Src is treated as an integer and dst is treated as a pointer to an integer. Src is stored at *dst. The matching argument is discarded. TK_ARGV_INT The following argument must contain an integer string in the format accepted by strtol (e.g. "0" and "0x" prefixes may be used to specify octal or hexadecimal numbers, respectively). Dst is treated as a pointer to an integer; the following argument is converted to an integer value and stored at *dst. Src is ignored. The matching and following arguments are discarded from argv. TK_ARGV_FLOAT The following argument must contain a floating-point number in the format accepted by strtol. Dst is treated as the address of an double-precision floating point value; the following argument is converted to a double-precision value and stored at *dst. The matching and following arguments are discarded from argv. TK_ARGV_STRING In this form, dst is treated as a pointer to a (char *); Tk_ParseArgv stores at *dst a pointer to the following argument, and discards the matching and following arguments from argv. Src is ignored. TK_ARGV_UID This form is similar to TK_ARGV_STRING, except that the argument is turned into a Tk_Uid by calling Tk_GetUid. Dst is treated as a pointer to a Tk_Uid; Tk_ParseArgv stores at *dst the Tk_Uid corresponding to the following argument, and discards the matching and following arguments from argv. Src is ignored. TK_ARGV_CONST_OPTION This form causes a Tk option to be set (as if the option command had been invoked). The src field is treated as a pointer to a string giving the value of an option, and dst is treated as a pointer to the name of the option. The matching argument is discarded. If tkwin is NULL, then argument specifiers of this type are ignored (as if they did not exist). TK_ARGV_OPTION_VALUE This form is similar to TK_ARGV_CONST_OPTION, except that the value of the option is taken from the following argument instead of from src. Dst is used as the name of the option. Src is ignored. The matching and following arguments are discarded. If tkwin is NULL, then argument specifiers of this type are ignored (as if they did not exist). TK_ARGV_OPTION_NAME_VALUE In this case the following argument is taken as the name of a Tk option and the argument after that is taken as the value for that option. Both src and dst are ignored. All three arguments are discarded from argv. If tkwin is NULL, then argument specifiers of this type are ignored (as if they did not exist). TK_ARGV_HELP When this kind of option is encountered, Tk_ParseArgv uses the help fields of argTable to format a message describing all the valid arguments. The message is placed in interp->result and Tk_ParseArgv returns TCL_ERROR. When this happens, the caller normally prints the help message and aborts. If the key field of a TK_ARGV_HELP specifier is NULL, then the specifier will never match any arguments; in this case the specifier simply provides extra documentation, which will be included when some other TK_ARGV_HELP entry causes help information to be returned. TK_ARGV_REST This option is used by programs or commands that allow the last several of their options to be the name and/or options for some other program. If a TK_ARGV_REST argument is found, then Tk_ParseArgv doesn't process any of the remaining arguments; it returns them all at the beginning of argv (along with any other unprocessed arguments). In addition, Tk_ParseArgv treats dst as the address of an integer value, and stores at *dst the index of the first of the TK_ARGV_REST options in the returned argv. This allows the program to distinguish the TK_ARGV_REST options from other unprocessed options that preceded the TK_ARGV_REST. TK_ARGV_FUNC For this kind of argument, src is treated as the address of a procedure, which is invoked to process the following argument. The procedure should have the following structure: int func(dst, key, nextArg) char *dst; char *key; char *nextArg; { } The dst and key parameters will contain the corresponding fields from the argTable entry, and nextArg will point to the following argument from argv (or NULL if there aren't any more arguments left in argv). If func uses nextArg (so that Tk_ParseArgv should discard it), then it should return 1. Otherwise it should return 0 and TkParseArgv will process the following argument in the normal fashion. In either event the matching argument is discarded. TK_ARGV_GENFUNC This form provides a more general procedural escape. It treats src as the address of a procedure, and passes that procedure all of the remaining arguments. The procedure should have the following form: int genfunc(dst, interp, key, argc, argv) char *dst; Tcl_Interp *interp; char *key; int argc; char **argv; { } The dst and key parameters will contain the corresponding fields from the argTable entry. Interp will be the same as the interp argument to Tcl_ParseArgv. Argc and argv refer to all of the options after the matching one. Genfunc should behave in a fashion similar to Tk_ParseArgv: parse as many of the remaining arguments as it can, then return any that are left by compacting them to the beginning of argv (starting at argv[0]). Genfunc should return a count of how many arguments are left in argv; Tk_ParseArgv will process them. If genfunc encounters an error then it should leave an error message in interp->result, in the usual Tcl fashion, and return -1; when this happens Tk_ParseArgv will abort its processing and return TCL_ERROR. FLAGS TK_ARGV_DONT_SKIP_FIRST_ARG Tk_ParseArgv normally treats argv[0] as a program or command name, and returns it to the caller just as if it hadn't matched argTable. If this flag is given, then argv[0] is not given special treatment. TK_ARGV_NO_ABBREV Normally, Tk_ParseArgv accepts unique abbreviations for key values in argTable. If this flag is given then only exact matches will be acceptable. TK_ARGV_NO_LEFTOVERS Normally, Tk_ParseArgv returns unrecognized arguments to the caller. If this bit is set in flags then Tk_ParseArgv will return an error if it encounters any argument that doesn't match argTable. The only exception to this rule is argv[0], which will be returned to the caller with no errors as long as TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified. TK_ARGV_NO_DEFAULTS Normally, Tk_ParseArgv searches an internal table of standard argument specifiers in addition to argTable. If this bit is set in flags, then Tk_ParseArgv will use only argTable and not its default table. EXAMPLE Here is an example definition of an argTable and some sample command lines that use the options. Note the effect on argc and argv; arguments processed by Tk_ParseArgv are eliminated from argv, and argc is updated to reflect reduced number of arguments. /* * Define and set default values for globals. */ int debugFlag = 0; int numReps = 100; char defaultFileName[] = "out"; char *fileName = defaultFileName; Boolean exec = FALSE; /* * Define option descriptions. */ Tk_ArgvInfo argTable[] = { {"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag, "Turn on debugging printfs"}, {"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps, "Number of repetitions"}, {"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName, "Name of file for output"}, {"x", TK_ARGV_REST, (char *) NULL, (char *) &exec, "File to exec, followed by any arguments (must be last argument)."}, {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL, (char *) NULL} }; main(argc, argv) int argc; char *argv[]; { ... if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { fprintf(stderr, "%s\n", interp->result); exit(1); } /* * Remainder of the program. */ } Note that default values can be assigned to variables named in argTable: the variables will only be overwritten if the particular arguments are present in argv. Here are some example command lines and their effects. prog -N 200 infile # just sets the numReps variable to 200 prog -of out200 infile # sets fileName to reference "out200" prog -XN 10 infile # sets the debug flag, also sets numReps In all of the above examples, argc will be set by Tk_ParseArgv to 2, argv[0] will be "prog", argv[1] will be "infile", and argv[2] will be NULL. KEYWORDS arguments, command line, options ═══ 5.58. Tk_QueueWindowEvent ═══ NAME Tk_QueueWindowEvent - Add a window event to the Tcl event queue SYNOPSIS #include Tk_QueueWindowEvent(eventPtr, position) ARGUMENTS XEvent *eventPtr (in) An event to add to the event queue. Tcl_QueuePosition position (in) Where to add the new event in the queue: TCL_QUEUE_TAIL, TCL_QUEUE_HEAD, or TCL_QUEUE_MARK. DESCRIPTION This procedure places a window event on Tcl's internal event queue for eventual servicing. It creates a Tcl_Event structure, copies the event into that structure, and calls Tcl_QueueEvent to add the event to the queue. When the event is eventually removed from the queue it is processed just like all window events. The position argument to Tk_QueueWindowEvent has the same significance as for Tcl_QueueEvent; see the documentation for Tcl_QueueEvent for details. KEYWORDS callback, clock, handler, modal timeout ═══ 5.59. Tk_RestackWindow ═══ NAME Tk_RestackWindow - Change a window's position in the stacking order SYNOPSIS #include int Tk_RestackWindow(tkwin, aboveBelow, other) ARGUMENTS Tk_Window tkwin (in) Token for window to restack. int aboveBelow (in) Indicates new position of tkwin relative to other; must be Above or Below. Tk_Window other (in) Tkwin will be repositioned just above or below this window. Must be a sibling of tkwin or a descendant of a sibling. If NULL then tkwin is restacked above or below all siblings. DESCRIPTION Tk_RestackWindow changes the stacking order of window relative to its siblings. If other is specified as NULL then window is repositioned at the top or bottom of its stacking order, depending on whether aboveBelow is Above or Below. If other has a non-NULL value then window is repositioned just above or below other. The aboveBelow argument must have one of the symbolic values Above or Below. Both of these values are defined by the include file . KEYWORDS above, below, obscure, stacking order ═══ 5.60. Tk_RestrictEvents ═══ NAME Tk_RestrictEvents - filter and selectively delay X events SYNOPSIS #include Tk_RestrictProc * Tk_RestrictEvents(proc, clientData, prevClientDataPtr) ARGUMENTS Tk_RestrictProc *proc (in) Predicate procedure to call to filter incoming X events. NULL means do not restrict events at all. ClientData clientData (in) Arbitrary argument to pass to proc. ClientData *prevClientDataPtr (out) Pointer to place to save argument to previous restrict procedure. DESCRIPTION This procedure is useful in certain situations where applications are only prepared to receive certain X events. After Tk_RestrictEvents is called, Tk_DoOneEvent (and hence Tk_MainLoop) will filter X input events through proc. Proc indicates whether a given event is to be processed immediately, deferred until some later time (e.g. when the event restriction is lifted), or discarded. Proc is a procedure with arguments and result that match the type Tk_RestrictProc: typedef Tk_RestrictAction Tk_RestrictProc( ClientData clientData, XEvent *eventPtr); The clientData argument is a copy of the clientData passed to Tk_RestrictEvents; it may be used to provide proc with information it needs to filter events. The eventPtr points to an event under consideration. Proc returns a restrict action (enumerated type Tk_RestrictAction) that indicates what Tk_DoOneEvent should do with the event. If the return value is TK_PROCESS_EVENT, then the event will be handled immediately. If the return value is TK_DEFER_EVENT, then the event will be left on the event queue for later processing. If the return value is TK_DISCARD_EVENT, then the event will be removed from the event queue and discarded without being processed. Tk_RestrictEvents uses its return value and prevClientDataPtr to return information about the current event restriction procedure (a NULL return value means there are currently no restrictions). These values may be used to restore the previous restriction state when there is no longer any need for the current restriction. There are very few places where Tk_RestrictEvents is needed. In most cases, the best way to restrict events is by changing the bindings with the bind Tcl command or by calling Tk_CreateEventHandler and Tk_DeleteEventHandler from C. The main place where Tk_RestrictEvents must be used is when performing synchronous actions (for example, if you need to wait for a particular event to occur on a particular window but you don't want to invoke any handlers for any other events). The "obvious" solution in these situations is to call XNextEvent or XWindowEvent, but these procedures cannot be used because Tk keeps its own event queue that is separate from the X event queue. Instead, call Tk_RestrictEvents to set up a filter, then call Tk_DoOneEvent to retrieve the desired event(s). KEYWORDS delay, event, filter, restriction ═══ 5.61. Tk_SetAppName ═══ NAME Tk_SetAppName - Set the name of an application for "send" commands SYNOPSIS #include char * Tk_SetAppName(tkwin, name) ARGUMENTS Tk_Window tkwin (in) Token for window in application. Used only to select a particular application. char *name (in) Name under which to register the application. DESCRIPTION Tk_SetAppName associates a name with a given application and records that association on the display containing with the application's main window. After this procedure has been invoked, other applications on the display will be able to use the send command to invoke operations in the application. If name is already in use by some other application on the display, then a new name will be generated by appending " #2" to name; if this name is also in use, the number will be incremented until an unused name is found. The return value from the procedure is a pointer to the name actually used. If the application already has a name when Tk_SetAppName is called, then the new name replaces the old name. Tk_SetAppName also adds a send command to the application's interpreter, which can be used to send commands from this application to others on any of the displays where the application has windows. The application's name registration persists until the interpreter is deleted or the send command is deleted from interp, at which point the name is automatically unregistered and the application becomes inaccessible via send. The application can be made accessible again by calling Tk_SetAppName. Tk_SetAppName is called automatically by Tk_Init, so applications don't normally need to call it explicitly. The command tk appname provides Tcl-level access to the functionality of Tk_SetAppName. KEYWORDS application, name, register, send command ═══ 5.62. Tk_SetClass ═══ NAME Tk_SetClass, Tk_Class - set or retrieve a window's class SYNOPSIS #include Tk_SetClass(tkwin, class) Tk_Uid Tk_Class(tkwin) ARGUMENTS Tk_Window tkwin (in) Token for window. char *class (in) New class name for window. DESCRIPTION Tk_SetClass is called to associate a class with a particular window. The class string identifies the type of the window; all windows with the same general class of behavior (button, menu, etc.) should have the same class. By convention all class names start with a capital letter, and there exists a Tcl command with the same name as each class (except all in lower-case) which can be used to create and manipulate windows of that class. A window's class string is initialized to NULL when the window is created. For main windows, Tk automatically propagates the name and class to the WM_CLASS property used by window managers. This happens either when a main window is actually created (e.g. in Tk_MakeWindowExist), or when Tk_SetClass is called, whichever occurs later. If a main window has not been assigned a class then Tk will not set the WM_CLASS property for the window. Tk_Class is a macro that returns the current value of tkwin's class. The value is returned as a Tk_Uid, which may be used just like a string pointer but also has the properties of a unique identifier (see the manual entry for Tk_GetUid for details). If tkwin has not yet been given a class, then Tk_Class will return NULL. KEYWORDS class, unique identifier, window, window manager ═══ 5.63. Tk_SetGrid ═══ NAME Tk_SetGrid, Tk_UnsetGrid - control the grid for interactive resizing SYNOPSIS #include Tk_SetGrid(tkwin, reqWidth, reqHeight, widthInc, heightInc) Tk_UnsetGrid(tkwin) ARGUMENTS Tk_Window tkwin (in) Token for window. int reqWidth (in) Width in grid units that corresponds to the pixel dimension tkwin has requested via Tk_GeometryRequest. int reqHeight (in) Height in grid units that corresponds to the pixel dimension tkwin has requested via Tk_GeometryRequest. int widthInc (in) Width of one grid unit, in pixels. int heightInc (in) Height of one grid unit, in pixels. DESCRIPTION Tk_SetGrid turns on gridded geometry management for tkwin's toplevel window and specifies the geometry of the grid. Tk_SetGrid is typically invoked by a widget when its setGrid option is true. It restricts interactive resizing of tkwin's toplevel window so that the space allocated to the toplevel is equal to its requested size plus or minus even multiples of widthInc and heightInc. Furthermore, the reqWidth and reqHeight values are passed to the window manager so that it can report the window's size in grid units during interactive resizes. If tkwin's configuration changes (e.g., the size of a grid unit changes) then the widget should invoke Tk_SetGrid again with the new information. Tk_UnsetGrid cancels gridded geometry management for tkwin's toplevel window. For each toplevel window there can be at most one internal window with gridding enabled. If Tk_SetGrid or Tk_UnsetGrid is invoked when some other window is already controlling gridding for tkwin's toplevel, the calls for the new window have no effect. See the wm manual entry for additional information on gridded geometry management. KEYWORDS grid, window, window manager ═══ 5.64. Tk_SetWindowVisual ═══ NAME Tk_SetWindowVisual - change visual characteristics of window SYNOPSIS #include int Tk_SetWindowVisual(tkwin, visual, depth, colormap) ARGUMENTS Tk_Window tkwin (in) Token for window. Visual *visual (in) New visual type to use for tkwin. int depth (in) Number of bits per pixel desired for tkwin. Colormap colormap (in) New colormap for tkwin, which must be compatible with visual and depth. DESCRIPTION When Tk creates a new window it assigns it the default visual characteristics (visual, depth, and colormap) for its screen. Tk_SetWindowVisual may be called to change them. Tk_SetWindowVisual must be called before the window has actually been created in X (e.g. before Tk_MapWindow or Tk_MakeWindowExist has been invoked for the window). The safest thing is to call Tk_SetWindowVisual immediately after calling Tk_CreateWindow. If tkwin has already been created before Tk_SetWindowVisual is called then it returns 0 and doesn't make any changes; otherwise it returns 1 to signify that the operation completed successfully. Note: Tk_SetWindowVisual should not be called if you just want to change a window's colormap without changing its visual or depth; call Tk_SetWindowColormap instead. KEYWORDS colormap, depth, visual ═══ 5.65. Tk_StrictMotif ═══ NAME Tk_StrictMotif - Return value of tk_strictMotif variable SYNOPSIS #include int Tk_StrictMotif(tkwin) ARGUMENTS Tk_Window tkwin (in) Token for window. DESCRIPTION This procedure returns the current value of the tk_strictMotif variable in the interpreter associated with tkwin's application. The value is returned as an integer that is either 0 or 1. 1 means that strict Motif compliance has been requested, so anything that is not part of the Motif specification should be avoided. 0 means that "Motif-like" is good enough, and extra features are welcome. This procedure uses a link to the Tcl variable to provide much faster access to the variable's value than could be had by calling Tcl_GetVar. KEYWORDS Motif compliance, tk_strictMotif variable ═══ 5.66. Tk_Init ═══ NAME Tk_Init - add Tk to an interpreter and make a new Tk application. SYNOPSIS #include int Tk_Init(interp) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to load Tk. Tk should not already be loaded in this interpreter. DESCRIPTION Tk_Init is the package initialization procedure for Tk. It is normally invoked by the Tcl_AppInit procedure for an application or by the load command. Tk_Init adds all of Tk's commands to interp and creates a new Tk application, including its main window. If the initialization is successful Tk_Init returns TCL_OK; if there is an error it returns TCL_ERROR. Tk_Init also leaves a result or error message in interp->result. If there is a variable argv in interp, Tk_Init treats the contents of this variable as a list of options for the new Tk application. The options may have any of the forms documented for the wish application (in fact, wish uses Tk_Init to process its command-line arguments). KEYWORDS application, initialization, load, main window ═══ 5.67. Tk_Main ═══ NAME Tk_Main - main program for Tk-based applications SYNOPSIS #include Tk_Main(argc, argv, appInitProc) ARGUMENTS int argc (in) Number of elements in argv. char *argv[] (in) Array of strings containing command-line arguments. Tcl_AppInitProc *appInitProc (in) Address of an application-specific initialization procedure. The value for this argument is usually Tcl_AppInit. DESCRIPTION Tk_Main acts as the main program for most Tk-based applications. Starting with Tk 4.0 it is not called main anymore because it is part of the Tk library and having a function main in a library (particularly a shared library) causes problems on many systems. Having main in the Tk library would also make it hard to use Tk in C++ programs, since C++ programs must have special C++ main functions. Normally each application contains a small main function that does nothing but invoke Tk_Main. Tk_Main then does all the work of creating and running a wish-like application. When it is has finished its own initialization, but before it processes commands, Tk_Main calls the procedure given by the appInitProc argument. This procedure provides a "hook" for the application to perform its own initialization, such as defining application-specific commands. The procedure must have an interface that matches the type Tcl_AppInitProc: typedef int Tcl_AppInitProc(Tcl_Interp *interp); AppInitProc is almost always a pointer to Tcl_AppInit; for more details on this procedure, see the documentation for Tcl_AppInit. KEYWORDS application-specific initialization, command-line arguments, main program ═══ 5.68. Tk_WindowId ═══ NAME Tk_WindowId, Tk_Parent, Tk_Display, Tk_DisplayName, Tk_ScreenNumber, Tk_Screen, Tk_X, Tk_Y, Tk_Width, Tk_Height, Tk_Changes, Tk_Attributes, Tk_IsMapped, Tk_IsTopLevel, Tk_ReqWidth, Tk_ReqHeight, Tk_InternalBorderWidth, Tk_Visual, Tk_Depth, Tk_Colormap - retrieve information from Tk's local data structure SYNOPSIS #include Window Tk_WindowId(tkwin) Tk_Window Tk_Parent(tkwin) Display * Tk_Display(tkwin) char * Tk_DisplayName(tkwin) int Tk_ScreenNumber(tkwin) Screen * Tk_Screen(tkwin) int Tk_X(tkwin) int Tk_Y(tkwin) int Tk_Width(tkwin) int Tk_Height(tkwin) XWindowChanges * Tk_Changes(tkwin) XSetWindowAttributes * Tk_Attributes(tkwin) int Tk_IsMapped(tkwin) int Tk_IsTopLevel(tkwin) int Tk_ReqWidth(tkwin) int Tk_ReqHeight(tkwin) int Tk_InternalBorderWidth(tkwin) Visual * Tk_Visual(tkwin) int Tk_Depth(tkwin) Colormap Tk_Colormap(tkwin) ARGUMENTS Tk_Window tkwin (in) Token for window. DESCRIPTION Tk_WindowID and the other names listed above are all macros that return fields from Tk's local data structure for tkwin. None of these macros requires any interaction with the server; it is safe to assume that all are fast. Tk_WindowId returns the X identifier for tkwin, or NULL if no X window has been created for tkwin yet. Tk_Parent returns Tk's token for the logical parent of tkwin. The parent is the token that was specified when tkwin was created, or NULL for main windows. Tk_Display returns a pointer to the Xlib display structure corresponding to tkwin. Tk_DisplayName returns an ASCII string identifying tkwin's display. Tk_ScreenNumber returns the index of tkwin's screen among all the screens of tkwin's display. Tk_Screen returns a pointer to the Xlib structure corresponding to tkwin's screen. Tk_X, Tk_Y, Tk_Width, and Tk_Height return information about tkwin's location within its parent and its size. The location information refers to the upper-left pixel in the window, or its border if there is one. The width and height information refers to the interior size of the window, not including any border. Tk_Changes returns a pointer to a structure containing all of the above information plus a few other fields. Tk_Attributes returns a pointer to an XSetWindowAttributes structure describing all of the attributes of the tkwin's window, such as background pixmap, event mask, and so on (Tk keeps track of all this information as it is changed by the application). Note: it is essential that applications use Tk procedures like Tk_ResizeWindow instead of X procedures like XResizeWindow, so that Tk can keep its data structures up-to-date. Tk_IsMapped returns a non-zero value if tkwin is mapped and zero if tkwin isn't mapped. Tk_IsTopLevel returns a non-zero value if tkwin is a top-level window (its X parent is the root window of the screen) and zero if tkwin isn't a top-level window. Tk_ReqWidth and Tk_ReqHeight return information about the window's requested size. These values correspond to the last call to Tk_GeometryRequest for tkwin. Tk_InternalBorderWidth returns the width of internal border that has been requested for tkwin, or 0 if no internal border was requested. The return value is simply the last value passed to Tk_SetInternalBorder for tkwin. Tk_Visual, Tk_Depth, and Tk_Colormap return information about the visual characteristics of a window. Tk_Visual returns the visual type for the window, Tk_Depth returns the number of bits per pixel, and Tk_Colormap returns the current colormap for the window. The visual characteristics are normally set from the defaults for the window's screen, but they may be overridden by calling Tk_SetWindowVisual. KEYWORDS attributes, colormap, depth, display, height, geometry manager, identifier, mapped, requested size, screen, top-level, visual, width, window, x, y ═══ 6. Tk Built-In Commands ═══ ═══ 6.1. bell ═══ NAME bell - Ring a display's bell SYNOPSIS bell ?-displayof window? 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. 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. KEYWORDS beep, bell, ring ═══ 6.2. bind ═══ NAME bind - Arrange for X events to invoke Tcl scripts SYNOPSIS bind tag bind tag sequence bind tag sequence script 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 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: 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: <> 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. MODIFIERS Modifiers consist of any of the following values: Control Mod2, M2 Shift Mod3, M3 Lock Mod4, M4 Button1, B1 Mod5, M5 Button2, B2 Meta, M Button3, B3 Alt Button4, B4 Double Button5, B5 Triple Mod1, M1 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 will match the event, but 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 and Triple modifiers are a convenience for specifying double mouse clicks and other repeated events. They cause a particular event pattern to be repeated 2 or 3 times, and also place a time and space requirement on the sequence: for a sequence of events to match a Double or Triple pattern, all of the events must occur close together in time and without substantial mouse motion in between. For example, is equivalent to with the extra time and space requirement. EVENT TYPES The type field may be any of the standard X event types, with a few extra abbreviations. Below is a list of all the valid types; where two names appear together, they are synonyms. ButtonPress, Button Expose Map ButtonRelease FocusIn Motion Circulate FocusOut Property Colormap Gravity Reparent Configure KeyPress, Key Unmap Destroy KeyRelease Visibility Enter Leave Activate Deactivate 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 . 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 ("Shift_L" is the keysm 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, is equivalent to . 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. %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. %d The detail 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 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. %h The height field from the event. Valid only for Configure and Expose events. %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 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. %t The time field from the event. Valid only for events that contain a time field. %w The width field from the event. Valid only for Configure and Expose events. %x The x field from the event. Valid only for events containing an x field. %y The y field from the event. Valid only for events containing a y field. %A Substitutes the ASCII character corresponding to the event, or the empty string if the event doesn't correspond to an ASCII character (e.g. the shift key was pressed). XLookupString does all the work of translating from the event to an ASCII character. Valid only for KeyPress and KeyRelease events. %B The border_width field from the event. Valid only for Configure events. %E The send_event field from the event. Valid for all event types. %K The keysym corresponding to the event, substituted as a textual string. Valid only for KeyPress and KeyRelease events. %N The keysym corresponding to the event, substituted as a decimal number. Valid only for KeyPress and KeyRelease 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 The x_root field from the event. If a virtual-root window manager is being used then the substituted value is the corresponding x-coordinate in the virtual root. Valid only for ButtonPress, ButtonRelease, KeyPress, KeyRelease, and Motion events. %Y The y_root field from the event. If a virtual-root window manager is being used then the substituted value is the corresponding y-coordinate in the virtual root. Valid only for ButtonPress, ButtonRelease, KeyPress, KeyRelease, and Motion events. The replacement string for a %-replacement is formatted as a proper Tcl list element. This means that it will be surrounded with braces if it contains 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 hadn't 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 command may be used to change this order for a particular window or to associate additional binding tags with the window. The continue and break commands may be used inside a binding script to control the processing of matching scripts. If continue is invoked, then the current binding script is terminated but Tk will continue processing binding scripts associated with other tag's. If the break 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: (a) an event pattern that specifies a specific button or key is more specific than one that doesn't; (b) a longer sequence (in terms of number of events matched) is more specific than a shorter sequence; (c) 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. (d) 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. (e) 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 <> event add <> event add <> bind Entry <> {puts Paste} bind Entry <> {puts Scroll} If the user types Control-y, the <> binding will be invoked, but if the user presses button 2 then one of either the <> or the <> 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 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, 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 mechanism is used to report the error. The bgerror command will be executed at global level (outside the context of any Tcl procedure). SEE ALSO bgerror KEYWORDS form, manual ═══ 6.3. 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 command, it is associated either with a particular window such as .a.b.c, a class name such as Button, 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 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. 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 tag for .b with TrickyButton. This means that the default widget bindings for buttons, which are associated with the Button tag, will no longer apply to .b, but any bindings associated with TrickyButton (perhaps some new button behavior) will apply. SEE ALSO bind KEYWORDS binding, event, tag ═══ 6.4. bitmap ═══ NAME bitmap - Images that display two colors SYNOPSIS image create bitmap ?name? ?options? 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 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 args 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 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 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 bitmap command. KEYWORDS bitmap, image ═══ 6.5. button ═══ NAME button - Create and manipulate button widgets SYNOPSIS button pathName ?options? STANDARD OPTIONS -activebackground -cursor -highlightthickness -takefocus -activeforeground -disabledforeground -image -text -anchor -font -justify -textvariable -background -foreground -padx -underline -bitmap -highlightbackground -pady -wraplength -borderwidth -highlightcolor -relief See the options manual entry for detailed descriptions of the above options. 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: -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); for text it is in lines of text. If this option isn't 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: -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); for text it is in characters. If this option isn't 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 args 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 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 active and normal 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 the following default behavior: 1. A button activates whenever the mouse passes over it and deactivates whenever the mouse leaves 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. KEYWORDS button, widget ═══ 6.6. canvas ═══ NAME canvas - Create and manipulate canvas widgets SYNOPSIS canvas pathName ?options? STANDARD OPTIONS -background -highlightthickness -insertwidth -takefocus -borderwidth -insertbackground -relief -xscrollcommand -cursor -insertborderwidth -selectbackground -yscrollcommand -highlightbackground -insertofftime -selectborderwidth -highlightcolor -insertontime -selectforeground See the options manual entry for detailed descriptions of the above options. 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 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 section below. 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 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 command allows commands to be bound to widgets. For example, a particular command may be associated with the 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. 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" isn't. 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. 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. 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. 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. INDICES Text items support the notion of an index for identifying particular positions within the item. Indices are used for commands such as inserting text, deleting a range of characters, 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. 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. 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. end Refers to the character just after the last one in the item (same as the number of characters in the item). insert Refers to the character just before which the insertion cursor is drawn in this item. sel.first Refers to the first selected character in the item. If the selection isn't in this item then this form is illegal. sel.last Refers to the last selected character in the item. If the selection isn't in this item then this form is illegal. @x,y Refers to the character 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. 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 args 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 args, add tag to the list of tags associated with the item if it isn't already present on that list. It is possible that no items will satisfy the constraints given by searchSpec and args, 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 then 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 then 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 command except that it operates on items in a canvas rather than entire widgets. See the bind 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. The handling of events in canvases uses the current item defined in ITEM IDS AND TAGS 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). 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 command in a binding script terminates that script, and a break command terminates that script and skips any remaining scripts for the event, just as for the bind command. If bindings have been created for a canvas window using the bind 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 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 ...? 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 ...? 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 in the range given by first and last, inclusive. If some of the items given by tagOrId don't support text operations, then they are ignored. First and last are indices of characters within the item(s) as described in INDICES 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 doesn't 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. 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 doesn't refer to any items, or if none of them support the insertion cursor, then the focus isn't 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 command) are totally independent: a given item doesn't 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 command to set the focus window to the canvas (if it wasn't 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 doesn't 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 don't support an insertion cursor then this command has no effect on them. See INDICES 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 widget command focus, below), but the cursor position may be set even when the item doesn't have the focus. This command returns an empty string. 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 above. The return value is guaranteed to lie between 0 and the number of characters 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 insertion then string is inserted into the item's text just before the character whose index is beforeThis. See INDICES 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 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 options and values 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. 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 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. 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" 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: -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 hasn't been specified, or if there isn't an 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 isn't specified then the Postscript is returned as the result of the command instead of being written to a file. -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. pathName scale tagOrId xOrigin yOrigin xScale yScale Rescale 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. 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. 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 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 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 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 isn't 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 isn't 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 doesn't 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 isn't 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 doesn't 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 don't 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, only text items provide this support). 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 option value ...? The arguments x1, y1, x2, and y2 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. The following 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. -fill color Fill the region of the arc with color. Color may have any of the forms accepted by Tk_GetColor. If color is an empty string (the default), then then the arc will not be filled. -outline color Color specifies a color to use for drawing the arc's outline; it may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is specified as an empty string then no outline is drawn for the arc. -outlinestipple bitmap Indicates that the outline for the arc should be drawn with a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -outline option hasn't 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. -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. -stipple bitmap Indicates that the arc should be filled in a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -fill option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then filling is done in a solid fashion. -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. -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 Specifies the width of the outline to be drawn around the arc's region, in any of the forms described in the COORDINATES section above. If the -outline option has been specified as an empty string then this option has no effect. Wide outlines will be drawn centered on the edges of the arc's region. This option defaults to 1.0. 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 option value ...? The arguments x and y specify the coordinates of a point used to position the bitmap on the display (see the -anchor option below for more information on how bitmaps are 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. The following options are supported for bitmaps: -anchor anchorPos AnchorPos tells how to position the bitmap relative to the positioning point for the item; it may have any of the forms accepted by Tk_GetAnchor. For example, if anchorPos is center then the bitmap is centered on the point; if anchorPos is n then the bitmap will be drawn so that its top center point is at the positioning point. This option defaults to center. -background color Specifies a color to use for each of the bitmap pixels whose value is 0. Color may have any of the forms accepted by Tk_GetColor. If this option isn't 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 Specifies the bitmap to display in the item. Bitmap may have any of the forms accepted by Tk_GetBitmap. -foreground color Specifies a color to use for each of the bitmap pixels whose value is 1. Color may have any of the forms accepted by Tk_GetColor and defaults to black. -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. 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 option value ...? The arguments x and y specify the coordinates of a point used to position the image on the display (see the -anchor option below for more information). 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. The following options are supported for images: -anchor anchorPos AnchorPos tells how to position the image relative to the positioning point for the item; it may have any of the forms accepted by Tk_GetAnchor. For example, if anchorPos is center then the image is centered on the point; if anchorPos is n then the image will be drawn so that its top center point is at the positioning point. This option defaults to center. -image name Specifies the name of the image to display in the item. This image must have been created previously with the image create command. -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; it may be an empty list. LINE ITEMS Items of type line appear on the display as one or more connected line segments or curves. Lines are created with widget commands of the following form: pathName create line x1 y1... xn yn ?option value option value ...? The arguments x1 through yn 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. The following 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 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 isn't 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 (butt, projecting, or round). If this option isn't specified then it defaults to butt. Where arrowheads are drawn the cap style is ignored. -fill color Color specifies a color to use for drawing the line; it may have any of the forms acceptable to Tk_GetColor. It may also be an empty string, in which case the line will be transparent. This option defaults to black. -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_GetCapStyle (bevel, miter, or round). If this option isn't specified then it defaults to miter. If the line only contains two points then this option is irrelevant. -smooth boolean Boolean must have one of the forms accepted by Tk_GetBoolean. It indicates whether or not the line should be drawn as a curve. If so, the line is rendered as a set of Bezier 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. -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. -stipple bitmap Indicates that the line should be filled in a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default), then filling is done in a solid fashion. -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 lineWidth LineWidth specifies the width of the line, in any of the forms described in the COORDINATES section above. Wide lines will be drawn centered on the path specified by the points. If this option isn't specified then it defaults to 1.0. 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 option value ...? The arguments x1, y1, x2, and y2 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. The following options are supported for ovals: -fill color Fill the area of the oval with color. Color may have any of the forms accepted by Tk_GetColor. If color is an empty string (the default), then then the oval will not be filled. -outline color Color specifies a color to use for drawing the oval's outline; it may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is an empty string then no outline will be drawn for the oval. -stipple bitmap Indicates that the oval should be filled in a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -fill option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then filling is done in a solid fashion. -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 outlineWidth specifies the width of the outline to be drawn around the oval, in any of the forms described in the COORDINATES section above. If the -outline option hasn't been specified then this option has no effect. Wide outlines are drawn centered on the oval path defined by x1, y1, x2, and y2. This option defaults to 1.0. POLYGON ITEMS Items of type polygon appear as polygonal or curved filled regions on the display. Polygons are created with widget commands of the following form: pathName create polygon x1 y1 ... xn yn ?option value option value ...? The arguments x1 through yn specify the coordinates for three or more points that define a closed polygon. The first and last points may be the same; whether they are or not, Tk will draw the polygon as a closed polygon. 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. The following options are supported for polygons: -fill color Color specifies a color to use for filling the area of the polygon; it may have any of the forms acceptable to Tk_GetColor. If color is an empty string then the polygon will be transparent. This option defaults to black. -outline color Color specifies a color to use for drawing the polygon's outline; it may have any of the forms accepted by Tk_GetColor. If color is an empty string then no outline will be drawn for the polygon. This option defaults to empty (no outline). -smooth boolean Boolean must have one of the forms accepted by Tk_GetBoolean It indicates whether or not the polygon should be drawn with a curved perimeter. If so, the outline of the polygon becomes a set of Bezier splines, one spline for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated in a smoothed polygon by duplicating the end-points of the desired line segment. -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. -stipple bitmap Indicates that the polygon should be filled in a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default), then filling is done in a solid fashion. -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 OutlineWidth specifies the width of the outline to be drawn around the polygon, in any of the forms described in the COORDINATES section above. If the -outline option hasn't been specified then this option has no effect. This option defaults to 1.0. 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 option value ...? The arguments x1, y1, x2, and y2 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. The following options are supported for rectangles: -fill color Fill the area of the rectangle with color, which may be specified in any of the forms accepted by Tk_GetColor. If color is an empty string (the default), then the rectangle will not be filled. -outline color Draw an outline around the edge of the rectangle in color. Color may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is an empty string then no outline will be drawn for the rectangle. -stipple bitmap Indicates that the rectangle should be filled in a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -fill option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then filling is done in a solid fashion. -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 OutlineWidth specifies the width of the outline to be drawn around the rectangle, in any of the forms described in the COORDINATES section above. If the -outline option hasn't been specified then this option has no effect. Wide outlines are drawn centered on the rectangular path defined by x1, y1, x2, and y2. This option defaults to 1.0. TEXT ITEMS A text item displays a string of characters on the screen in one or more lines. Text items support indexing and selection, along with the following text-related canvas widget commands: dchars, focus, icursor, index, insert, select. Text items are created with widget commands of the following form: pathName create text x y ?option value option value ...? The arguments x and y 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. The following options are supported for text items: -anchor anchorPos AnchorPos tells how to position the text relative to the positioning point for the text; it may have any of the forms accepted by Tk_GetAnchor. For example, if anchorPos is center then the text is centered on the point; if anchorPos is n then the text will be drawn such that the top center point of the rectangular region occupied by the text will be at the positioning point. This option defaults to center. -fill color Color specifies a color to use for filling the text characters; it may have any of the forms accepted by Tk_GetColor. If this option isn't specified then it defaults to black. -font fontName Specifies the font to use for the text item. FontName may be any string acceptable to Tk_GetFontStruct. If this option isn't 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. -stipple bitmap Indicates that the text should be drawn in a stippled pattern rather than solid; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default) then the text is drawn in a solid fashion. -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. -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. -width lineLength Specifies a maximum line length for the text, in any of the forms described in the COORDINATES 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 option value ...? The arguments x and y specify the coordinates of a point used to position the window on the display (see the -anchor option below for more information on how bitmaps are 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. The following options are supported for window items: -anchor anchorPos AnchorPos tells how to position the window relative to the positioning point for the item; it may have any of the forms accepted by Tk_GetAnchor. For example, if anchorPos is center then the window is centered on the point; if anchorPos is n then the window will be drawn so that its top center point is at the positioning point. This option defaults to center. -height pixels Specifies the height to assign to the item's window. Pixels may have any of the forms described in the COORDINATES section above. If this option isn't specified, or if it is specified as an empty string, then the window is given whatever height it requests internally. -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 pixels Specifies the width to assign to the item's window. Pixels may have any of the forms described in the COORDINATES section above. If this option isn't specified, or if it is specified as an empty string, 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. 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. BINDINGS In the current implementation, new canvases are not given any default behavior: you'll 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. KEYWORDS canvas, widget ═══ 6.7. checkbutton ═══ NAME checkbutton - Create and manipulate checkbutton widgets SYNOPSIS checkbutton pathName ?options? STANDARD OPTIONS -activebackground -cursor -highlightthickness -takefocus -activeforeground -disabledforeground -image -text -anchor -font -justify -textvariable -background -foreground -padx -underline -bitmap -highlightbackground -pady -wraplength -borderwidth -highlightcolor -relief See the options manual entry for detailed descriptions of the above options. 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); for text it is in lines of text. If this option isn't 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: -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: -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 applicies to the indicator. 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: -variable Database Name: variable Database Class: Variable Specifies name of 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); for text it is in characters. If this option isn't 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 sunken relief and a special color, and a Tcl variable associated with the checkbutton is set to a particular value (normally 1). If the checkbutton is not selected, then the indicator is drawn with a raised relief and no special color, and the associated variable is set to a different value (typically 0). 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" and "off" 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" value. 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 args 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 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. A checkbutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves the checkbutton. 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. 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. KEYWORDS checkbutton, widget ═══ 6.8. tk_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 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. If the user cancels the operation, both commands will return the empty string. EXAMPLE button .b -fg [tk_chooseColor -initialcolor gray -title "Choose color"] KEYWORDS color selection dialog ═══ 6.9. 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. 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 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 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 don't 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 -. KEYWORDS clear, format, clipboard, append, selection, type ═══ 6.10. 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 the entire application will be destroyed. The windows are destroyed in order, and if an error occurs in destroying a window the command aborts without destroying the remaining windows. KEYWORDS application, destroy, window ═══ 6.11. tk_dialog ═══ 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. 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 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 won't 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. KEYWORDS bitmap, dialog, modal ═══ 6.12. entry ═══ NAME entry - Create and manipulate entry widgets SYNOPSIS entry pathName ?options? STANDARD OPTIONS -background -highlightbackground -insertontime -selectforeground -borderwidth -highlightcolor -insertwidth -takefocus -cursor -highlightthickness -justify -textvariable -exportselection -insertbackground -relief -xscrollcommand -font -insertborderwidth -selectbackground -foreground -insertofftime -selectborderwidth See the options manual entry for detailed descriptions of the above options. WIDGET-SPECIFIC OPTIONS 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 two states for the entry: normal or disabled. If the entry is disabled 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. 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. 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 option ?arg arg ...? Option and the args determine the exact behavior of the command. 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 isn't 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 isn't 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. 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 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 isn't 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 isn't 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 isn't 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. Doesn't 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 isn't in this widget then a new selection is created using the most recent anchor point specified for the widget. Returns an empty string. 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 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 entry 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 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 don't 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-w deletes the word to the left of the insertion cursor. 24. 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. The behavior of entries can be changed by defining new bindings for individual widgets or by redefining the class bindings. KEYWORDS entry, widget ═══ 6.13. event ═══ 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 <> 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 sequences occurs. Virtual may be any string value and sequence may have any of the values allowed for the sequence argument to the bind command. If virtual is already defined, the new physical event sequences add to the existing sequences for the event. event delete <> ?sequence sequence ...? Deletes each of the sequences 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 command. Any sequences 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, and event provides a basic description of the event, such as or <>. Event may have any of the forms allowed for the sequence argument of the bind 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 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. event info ?<>? Returns information about virtual events. If the <> argument is omitted, the return value is a list of all the virtual events that are currently defined. If <> 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. EVENT FIELDS The following options are supported for the event generate command. These correspond to the "%" expansions allowed in binding scripts for the bind 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. -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 th 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. -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 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 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. VIRTUAL EVENT EXAMPLES 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 command. Consider the following virtual event definitions: event add <> event add <> event add <> event add <> In the bind command, a virtual event can be bound like any other builtin event type as follows: bind Entry <> {%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 <> virtual event is synthesized with event generate, then the <> 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 <> bind Entry {puts Control-y} bind Entry <> {puts Paste} When the user types Control-y the 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 <> binding will be invoked, because the Meta modifier in the physical pattern associated with the virtual binding is more specific than the 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 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 {} event add <> the behavior will change such in two ways. First, the shadowed <> binding will emerge. Typing Control-y will no longer invoke the binding, but instead invoke the virtual event <>. Second, pressing the F6 key will now also invoke the <> binding. SEE ALSO bind KEYWORDS event, binding, define, handle, virtual event ═══ 6.14. focus ═══ 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 doesn't 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 isn't 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 doesn't 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 doesn't 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. KEYWORDS events, focus, keyboard, top-level, window manager ═══ 6.15. tk_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 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'll have to write a script that deletes the bindings created by tk_focusFollowsMouse. KEYWORDS focus, keyboard traversal, top-level ═══ 6.16. frame ═══ NAME frame - Create and manipulate frame widgets SYNOPSIS frame pathName ?options? STANDARD OPTIONS -borderwidth -highlightbackground -highlightthickness -takefocus -cursor -highlightcolor -relief See the options manual entry for detailed descriptions of the above options. 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. If this option is less than or equal to zero then the window will not request any size at all. 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. 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. If this option is less than or equal to zero then the window will not request any size at all. 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 args 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 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. KEYWORDS frame, widget ═══ 6.17. tk_getOpenFile ═══ 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 an 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: -defaultextension extension Specifies a string that will be appended to the filename if the user enters a filename without an extension. The defaut value is the empty string, which means no extension will be appended to the filename in any case. This option is ignored on the Macintosh platform, which does not require extensions to filenames. -filetypes filePatternList If a File types listbox exists in the file dialog on the particular platform, this option gives the filetypes 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 listbox is not supported by the particular platform then all files are listed regardless of their types. See the section SPECIFYING FILE PATTERNS 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, then the files in the current working directory are displayed. This option may not always work on the Macintosh. This is not a bug. Rather, the General Controls control panel on the Mac allows the end user to override the application default directory. -initialfile filename Specifies a filename to be displayed in the dialog when it pops up. This option is ignored by the tk_getOpenFile command. -parent window Makes window the logical parent of the file dialog. The file 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 is displayed. This option is ignored on the Macintosh platform. 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 listbox. extension is a file extension for this file pattern. macType is a four-character Macintosh file type. The list of macTypes 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 patterns for one type of file is necessary on the Macintosh platform only. 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 at least one of the extension(s) of the file pattern. The macTypes are ignored. SPECIFYING EXTENSIONS On the Unix and Macintosh platforms, extensions are matched using glob-style pattern matching. On the Windows platforms, 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 != ""} { # Open the file ... } KEYWORDS file selection dialog ═══ 6.18. grab ═══ 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 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. BUGS It took an incredibly complex and gross implementation to produce the simple grab effect described above. Given the current implementation, it isn't 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 doesn't exist. KEYWORDS grab, keyboard events, pointer events, window ═══ 6.19. grid ═══ 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 a window name (any value starting with "."), then the command is processed in the same way as grid configure. 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 and -pad. 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 -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 an 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" section, below. The following options are supported: -column n Insert the slave so that it occupies the nth 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 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. 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. The amount defaults to 0. This space is added outside the slave(s) border. -row n Insert the slave so that it occupies the nth 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. 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 slaves 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" 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 and -pad. 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 -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 an list of "-option value" pairs. grid remove slave ?slave ...? Removes each of the slaves 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 slaves in the same grid command, and the presence of the characters -, ^, 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 columnspan. A - may not follow a ^ or a x. 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 padding plus the size of the largest slave, whichever is greater. Then the slaves whose rowspans or columnspans 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. 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 centered within its master. 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 there minimum sizes, the layout is clipped on the bottom and right. 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 hasn't 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. KEYWORDS geometry manager, location, grid, cell, propagation, size, pack ═══ 6.20. image ═══ 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 returns its name. type specifies the type of the image, which must be one of the types currently defined (e.g., bitmap). name specifies the name for the image; if it is omitted then Tk picks a name of the form imagex, 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. 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 won't 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 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. 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 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 manual entry for more information. KEYWORDS height, image, types of images, width ═══ 6.21. label ═══ NAME label - Create and manipulate label widgets SYNOPSIS label pathName ?options? STANDARD OPTIONS -anchor -font -image -takefocus -background -foreground -justify -text -bitmap -highlightbackground -padx -textvariable -borderwidth -highlightcolor -pady -underline -cursor -highlightthickness -relief -wraplength See the options manual entry for detailed descriptions of the above options. 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); for text it is in lines of text. If this option isn't 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: -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); for text it is in characters. If this option isn't 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 args 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 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. KEYWORDS label, widget ═══ 6.22. listbox ═══ NAME listbox - Create and manipulate listbox widgets SYNOPSIS listbox pathName ?options? STANDARD OPTIONS -background -foreground -relief -takefocus -borderwidth -height -selectbackground -width -cursor -highlightbackground -selectborderwidth -xscrollcommand -exportselection -highlightcolor -selectforeground -yscrollcommand -font -highlightthickness -setgrid See the options manual entry for detailed descriptions of the above options. WIDGET-SPECIFIC OPTIONS 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: -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: -width Database Name: width Database Class: Width Specifies the desired width for the window in characters. If the font doesn't 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; 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 with an underline 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 widget command. end Indicates the end of the listbox. For some commands this means just after the last element; for other commands it means the last element. @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 args 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. The active element is drawn with an underline 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 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 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 isn't 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. 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 a decimal string giving the integer index value that corresponds to index. 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 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. 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 isn't. 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. 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. 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 isn't 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 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 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. KEYWORDS listbox, widget ═══ 6.23. 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. SEE ALSO raise KEYWORDS lower, obscure, stacking order ═══ 6.24. menu ═══ NAME menu - Create and manipulate menu widgets SYNOPSIS menu pathName ?options? STANDARD OPTIONS -activebackground -background -disabledforeground -relief -activeborderwidth -borderwidth -font -takefocus -activeforeground -cursor -foreground See the options manual entry for detailed descriptions of the above options. 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. 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. 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 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. Command-Line Name: -transient Database Name: transient Database Class: Transient This option must have a boolean value. True means that the menu is used on a transient basis, e.g. as a pop-up, pull-down, or cascaded menu. False means that the menu will be displayed on the screen continuously, for example as a torn-off menu. If the option is true, no window manager border will be displayed around the menu and redisplay will be optimized using X's "save under" facility. INTRODUCTION The menu command creates a new top-level window (given by the pathName argument) and makes it into a menu widget. 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 a column. 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. 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 to the right 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. 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. If a -command option is specified for a cascade entry then it is evaluated as a Tcl command whenever the entry is invoked. 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. 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 args 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 indexes and may be specified in any of the following forms: 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. 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. pattern If the index doesn't 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 Tcl_StringMatch are used. 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 any of the following options: -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. This option overrides the -label 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. -command value Specifies a Tcl command to execute when the menu entry is invoked. Not available for separator or tear-off entries. -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. -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. This option overrides the -label and -bitmap options 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. 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 value 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. 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 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 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 values accepted by the add widget command. 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 accepted by the add widget command. 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 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 doesn't correspond to a cascade entry, or if pathName isn't 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 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. 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 CONFIGURATIONS The default bindings support four different ways of using menus: Pulldown Menus This is the most common case. 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 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 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 with -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 don't activate and they ignore mouse button presses and releases. The behavior of menus can be changed by defining new bindings for individual widgets or by redefining the class bindings. BUGS At present it isn't possible to use the option database to specify values for the options to individual entries. KEYWORDS menu, widget ═══ 6.25. tk_menuBar ═══ NAME tk_menuBar, tk_bindForTraversal - Obsolete support for menu bars SYNOPSIS tk_menuBar frame ?menu menu ...? tk_bindForTraversal arg arg ... DESCRIPTION These procedures were used in Tk 3.6 and earlier releases to help manage pulldown menus and to implement keyboard traversal of menus. In Tk 4.0 and later releases they are no longer needed. Stubs for these procedures have been retained for backward compatibility, but they have no effect. You should remove calls to these procedures from your code, since eventually the procedures will go away. KEYWORDS keyboard traversal, menu, menu bar, post ═══ 6.26. menubutton ═══ NAME menubutton - Create and manipulate menubutton widgets SYNOPSIS menubutton pathName ?options? STANDARD OPTIONS -activebackground -cursor -highlightthickness -takefocus -activeforeground -disabledforeground -image -text -anchor -font -justify -textvariable -background -foreground -padx -underline -bitmap -highlightbackground -pady -wraplength -borderwidth -highlightcolor -relief See the options manual entry for detailed descriptions of the above options. WIDGET-SPECIFIC OPTIONS 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); for text it is in lines of text. If this option isn't 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 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); for text it is in characters. If this option isn't 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 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. There are several interactions between menubuttons and menus; see the menu 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 args 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 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 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 isn't 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. KEYWORDS menubutton, widget ═══ 6.27. message ═══ NAME message - Create and manipulate message widgets SYNOPSIS message pathName ?options? STANDARD OPTIONS -anchor -font -highlightthickness -takefocus -background -foreground -padx -text -borderwidth -highlightbackground -pady -textvariable -cursor -highlightcolor -relief -width See the options manual entry for detailed descriptions of the above options. 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 isn't 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 the text will 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. 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. 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 \xhh where hh is the two-digit hexadecimal number corresponding to the character. In the unusual case where the font doesn't 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 args 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 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 don't work very well with text that is centered or right-justified. The most common result is that the line is justified wrong. KEYWORDS message, widget ═══ 6.28. tk_messageBox ═══ 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 the message box has just one button it will automatically be made the default, otherwise if this option is not specified, there won't be any default button. -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 no icon will be displayed. -message string Specifies the message to display in this message box. -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. The default value is an empty string. -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?" -type yesno -icon question] case $answer { yes exit no {tk_messageBox -message "I know you like this application!" -type ok} } KEYWORDS message box ═══ 6.29. option ═══ 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. Value contains a text string to associate with pattern; this is the value that will be returned in calls to Tk_GetOption 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 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 isn't 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. KEYWORDS database, option, priority, retrieve ═══ 6.30. tk_optionMenu ═══ NAME tk_optionMenu - Create an option menubutton and its menu SYNOPSIS tk_optionMenu w varName value ?value value ...? DESCRIPTION This procedure creates an option menubutton whose name is w, 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 values 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 w, so that the caller can change its configuration options or manipulate it in other ways. KEYWORDS option menu ═══ 6.31. options ═══ 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 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. 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. 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. 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; 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. 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. 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, 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 Database Class: Font Specifies the font to use when drawing text inside the widget. 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: -geometry Database Name: geometry Database Class: Geometry Specifies the desired geometry for the widget's window, in the form widthxheight, where width is the desired width of the window and height is the desired height. The units for width and height depend on the particular widget. For widgets displaying text the units are usually the size of the characters in the font being displayed; for other widgets the units are usually pixels. 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. 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 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; 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. 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 doesn't 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. 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. 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. 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. 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, 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. 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 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 Database Class: Text 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 Specifies the name of a 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. 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. KEYWORDS class, name, standard option, switch ═══ 6.32. pack-old ═══ NAME pack - Obsolete syntax for packer geometry manager SYNOPSIS pack after sibling window options ?window options ...? pack append parent window options ?window options ...? pack before sibling window options ?window options ...? pack unpack window DESCRIPTION Note: this manual entry describes the syntax for the pack command as it existed before Tk version 3.3. Although this syntax continues to be supported for backward compatibility, it is obsolete and should not be used anymore. At some point in the future it may cease to be supported. The packer is a geometry manager that arranges the children of a parent by packing them in order around the edges of the parent. The first child is placed against one side of the window, occupying the entire span of the window along that side. This reduces the space remaining for other children as if the side had been moved in by the size of the first child. Then the next child is placed against one side of the remaining cavity, and so on until all children have been placed or there is no space left in the cavity. The before, after, and append forms of the pack command are used to insert one or more children into the packing order for their parent. The before form inserts the children before window sibling in the order; all of the other windows must be siblings of sibling. The after form inserts the windows after sibling, and the append form appends one or more windows to the end of the packing order for parent. If a window named in any of these commands is already packed in its parent, it is removed from its current position in the packing order and repositioned as indicated by the command. All of these commands return an empty string as result. The unpack form of the pack command removes window from the packing order of its parent and unmaps it. After the execution of this command the packer will no longer manage window's geometry. The placement of each child is actually a four-step process; the options argument following each window consists of a list of one or more fields that govern the placement of that window. In the discussion below, the term cavity refers to the space left in a parent when a particular child is placed (i.e. all the space that wasn't claimed by earlier children in the packing order). The term parcel refers to the space allocated to a particular child; this is not necessarily the same as the child window's final geometry. The first step in placing a child is to determine which side of the cavity it will lie against. Any one of the following options may be used to specify a side: top Position the child's parcel against the top of the cavity, occupying the full width of the cavity. bottom Position the child's parcel against the bottom of the cavity, occupying the full width of the cavity. left Position the child's parcel against the left side of the cavity, occupying the full height of the cavity. right Position the child's parcel against the right side of the cavity, occupying the full height of the cavity. At most one of these options should be specified for any given window. If no side is specified, then the default is top. The second step is to decide on a parcel for the child. For top and bottom windows, the desired parcel width is normally the cavity width and the desired parcel height is the window's requested height, as passed to Tk_GeometryRequest. For left and right windows, the desired parcel height is normally the cavity height and the desired width is the window's requested width. However, extra space may be requested for the window using any of the following options: padx num Add num pixels to the window's requested width before computing the parcel size as described above. pady num Add num pixels to the window's requested height before computing the parcel size as described above. expand This option requests that the window's parcel absorb any extra space left over in the parent's cavity after packing all the children. The amount of space left over depends on the sizes requested by the other children, and may be zero. If several windows have all specified expand then the extra width will be divided equally among all the left and right windows that specified expand and the extra height will be divided equally among all the top and bottom windows that specified expand. If the desired width or height for a parcel is larger than the corresponding dimension of the cavity, then the cavity's dimension is used instead. The third step in placing the window is to decide on the window's width and height. The default is for the window to receive either its requested width and height or the those of the parcel, whichever is smaller. If the parcel is larger than the window's requested size, then the following options may be used to expand the window to partially or completely fill the parcel: fill Set the window's size to equal the parcel size. fillx Increase the window's width to equal the parcel's width, but retain the window's requested height. filly Increase the window's height to equal the parcel's height, but retain the window's requested width. The last step is to decide the window's location within its parcel. If the window's size equals the parcel's size, then the window simply fills the entire parcel. If the parcel is larger than the window, then one of the following options may be used to specify where the window should be positioned within its parcel: frame center Center the window in its parcel. This is the default if no framing option is specified. frame n Position the window with its top edge centered on the top edge of the parcel. frame ne Position the window with its upper-right corner at the upper-right corner of the parcel. frame e Position the window with its right edge centered on the right edge of the parcel. frame se Position the window with its lower-right corner at the lower-right corner of the parcel. frame s Position the window with its bottom edge centered on the bottom edge of the parcel. frame sw Position the window with its lower-left corner at the lower-left corner of the parcel. frame w Position the window with its left edge centered on the left edge of the parcel. frame nw Position the window with its upper-left corner at the upper-left corner of the parcel. The packer manages the mapped/unmapped state of all the packed children windows. It automatically maps the windows when it packs them, and it unmaps any windows for which there was no space left in the cavity. The packer makes geometry requests on behalf of the parent windows it manages. For each parent window it requests a size large enough to accommodate all the options specified by all the packed children, such that zero space would be leftover for expand options. KEYWORDS geometry manager, location, packer, parcel, size ═══ 6.33. pack ═══ 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" 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 defaults to 0. -pady amount Amount specifies how much vertical external padding to leave on each side of the slave(s). 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 slaves 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" 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" 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 doesn't 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 hasn't 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 and lower commands to change the stacking order of either the master or the slave. KEYWORDS geometry manager, location, packer, parcel, propagation, size ═══ 6.34. tk_setPalette ═══ 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 don't 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. KEYWORDS bisque, color, palette ═══ 6.35. photo ═══ NAME photo - Full-color images SYNOPSIS image create photo ?name? ?options? DESCRIPTION A photo is an image whose pixels can display any color or be transparent. A photo image is stored internally in full color (24 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 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. CREATING PHOTOS Like all images, photos are created using the image create command. Photos support the following options: -data string Specifies the contents of the image as a string. 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 from a file. -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 args 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 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 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 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 xth pixel in the X direction and yth 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. 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 ?-to x1 y1 x2 y2? Sets pixels in imageName to the colors specified in data. data is used to form a two-dimensional array of pixels that are then copied into the imageName. data is structured as a list of horizontal rows, from top to bottom, each of which is a list of colors, listed from left to right. Each color may be specified by name (e.g., blue) or in hexadecimal form (e.g., #2376af). The -to option can be used to specify the area of imageName to be affected. If only x1 and y1 are given, the area affected has its top-left corner at (x1,y1) and is the same size as the array given in data. If all four coordinates are given, they specify diagonally opposite corners of the affected rectangle, and the array given in data will be replicated as necessary in the X and Y directions to fill the rectangle. 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 write filename ?option value(s) ...? Writes image data from imageName to a file named filename. The following options may be specified: -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 a initial substring of format-name and which has the capability to write an image file. If this option is not given, 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. 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. The standard Tk distribution comes with handlers for PPM/PGM 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 doesn't, 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. 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. KEYWORDS photo, image, color ═══ 6.36. place ═══ NAME place - Geometry manager for fixed or rubber-sheet placement SYNOPSIS place window option value ?option value ...? place configure window option value ?option value ...? place forget window place info window place slaves window 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. If the first argument to the place command is a window path name or configure then the command arranges for the placer to manage the geometry of a slave whose path name is window. The remaining arguments consist of one or more option-value pairs that specify the way in which window's geometry is managed. If the placer is already managing window, then the option-value pairs modify the configuration for window. In this form the place command returns an empty string as result. The following option-value pairs are supported: -in master Master specifes 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 isn't specified then the master defaults to window's parent. -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) and need not lie within the bounds of the master window. -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. -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) and need not lie within the bounds of the master window. -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. -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. -width size Size specifies the width for window in screen units (i.e. any of the forms accepted by Tk_GetPixels). 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. -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. -height size Size specifies the height for window in screen units (i.e. any of the forms accepted by Tk_GetPixels). 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. -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. -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. 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. The place slaves command 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. The place forget command causes the placer to stop managing the geometry of window. As a side effect of this command window will be unmapped so that it doesn't appear on the screen. If window isn't currently managed by the placer then the command has no effect. Place forget returns an empty string as result. The place info command 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. 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" don't 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 doesn't 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. KEYWORDS geometry manager, height, location, master, place, rubber sheet, slave, width ═══ 6.37. tk_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. KEYWORDS menu, popup ═══ 6.38. radiobutton ═══ NAME radiobutton - Create and manipulate radiobutton widgets SYNOPSIS radiobutton pathName ?options? STANDARD OPTIONS -activebackground -cursor -highlightthickness -takefocus -activeforeground -disabledforeground -image -text -anchor -font -justify -textvariable -background -foreground -padx -underline -bitmap -highlightbackground -pady -wraplength -borderwidth -highlightcolor -relief See the options manual entry for detailed descriptions of the above options. 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); for text it is in lines of text. If this option isn't 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, the color applicies to the indicator. 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, 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 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: -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 Database Class: Variable Specifies name of 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); for text it is in characters. If this option isn't 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 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 sunken relief and a special color, and a Tcl variable associated with the radiobutton is set to a particular value. If the radiobutton is not selected, the indicator is drawn with a raised relief and no special color. 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. 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 args 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 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. The radiobutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves the radiobutton. 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. KEYWORDS radiobutton, widget ═══ 6.39. 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. SEE ALSO lower KEYWORDS obscure, raise, stacking order ═══ 6.40. scale ═══ NAME scale - Create and manipulate scale widgets SYNOPSIS scale pathName ?options? STANDARD OPTIONS -activebackground -font -highlightthickness -repeatinterval -background -foreground -orient -takefocus -borderwidth -highlightbackground -relief -troughcolor -cursor -highlightcolor -repeatdelay See the options manual entry for detailed descriptions of the above options. 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). 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 Specfies 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. 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 won't 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). 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 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 args 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 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 isn't 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. KEYWORDS scale, slider, trough, widget ═══ 6.41. scrollbar ═══ NAME scrollbar - Create and manipulate scrollbar widgets SYNOPSIS scrollbar pathName ?options? STANDARD OPTIONS -activebackground -highlightbackground -orient -takefocus -background -highlightcolor -relief -troughcolor -borderwidth -highlightthickness -repeatdelay -cursor -jump -repeatinterval See the options manual entry for detailed descriptions of the above options. 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 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. 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. 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 an 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 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 args 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 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 unit 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 page 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 doesn't 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. KEYWORDS scrollbar, widget ═══ 6.42. selection ═══ 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). 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, 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. selection handle ?-selection selection? ?-type type? ?-format format? window command Creates a handler for selection requests, such that command will be executed whenever selection is owned by window and someone attempts to retrieve it in the form given by type (e.g. type is specified in the selection get command). Selection defaults to PRIMARY, type defaults to STRING, and format defaults to STRING. If command is an empty string then any existing handler for window, type, and selection is removed. 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 maxBytes: offset specifies a starting character position in the selection and maxBytes gives the maximum number of bytes to retrieve. The command should return a value consisting of at most maxBytes of the selection, starting at position offset. For very large selections (larger than maxBytes) the selection will be retrieved using several invocations of command with increasing offset values. If command returns a string whose length is less than maxBytes, the return value is assumed to include all of the remainder of the selection; if the length of command's result is equal to maxBytes then command will be invoked again, until it eventually returns a result shorter than maxBytes. The value of maxBytes will always be relatively large (thousands of bytes). If command returns an error then the selection retrieval is rejected just as if the selection didn't 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). 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 don't 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. KEYWORDS clear, format, handler, ICCCM, own, selection, target, type ═══ 6.43. send ═══ NAME send - Execute a command in a different application SYNOPSIS send ?options? app cmd ?arg arg ...? DESCRIPTION This command arranges for cmd (and args) 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 args are present, they are concatenated to form the command to be executed, just as for the eval 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 command. DISABLING SENDS If the send command is removed from an application (e.g. with the command rename 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 command. SECURITY The send command is potentially a serious security loophole, since 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. KEYWORDS application, name, remote execution, security, send ═══ 6.44. text ═══ NAME text - Create and manipulate text widgets SYNOPSIS text pathName ?options? STANDARD OPTIONS -background -highlightbackground -insertontime -selectborderwidth -borderwidth -highlightcolor -insertwidth -selectforeground -cursor -highlightthickness -padx -setgrid -exportselection -insertbackground -pady -takefocus -font -insertborderwidth -relief -xscrollcommand -foreground -insertofftime -selectbackground -yscrollcommand See the options manual entry for detailed descriptions of the above options. WIDGET-SPECIFIC OPTIONS 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: -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 overriden 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 overriden 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 overriden with -spacing3 options in tags. 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 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. 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. 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 doesn't 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 don't 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 three different kinds of annotations on the text, called tags, marks, and embedded windows. 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 below for more details. The second form of annotation consists of marks, which are floating markers in the text. Marks are used to keep track of various interesting positions in the text as it is edited. See MARKS below for more details. The third form of annotation allows arbitrary windows to be embedded in a text widget. See EMBEDDED WINDOWS 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 modifiers adjust the index from the starting point (e.g. move forward or backward one character). Every index must contain a base, but the modifiers are optional. 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. 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 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 character in the text. Spaces on either side of count are optional. - count 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 character in the text. Spaces on either side of count are optional. + count 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. - count lines Adjust the index backward by count 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. linestart Adjust the index to refer to the first character on the line. lineend Adjust the index to refer to the last character on the line (the newline). 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. 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 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. 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 the characters " " (space), +, or -: these characters have special meaning in indices, so tags containing them can't 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. -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. If bitmap hasn't 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 3-D border to draw around the background. It may have any of the forms accepted by Tk_GetPixels. This option is used in conjunction with the -relief option to give a 3-D appearance to the background for characters; it is ignored unless the -background option has been set for the tag. -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. If bitmap hasn't 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_GetFontStruct. -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. -justify justify If the first 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 character of that display line. -lmargin1 pixels If the first 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 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. -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 Tk_GetBoolean. -relief relief Relief specifies the 3-D relief to use for drawing backgrounds, in any of the forms accepted by Tk_GetRelief. This option is used in conjunction with the -borderwidth option to give a 3-D appearance to the background for characters; it is ignored unless the -background option has been set for the tag. -rmargin pixels If the first 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 character of that display line. -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 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. -underline boolean Boolean specifies whether or not to draw an underline underneath characters. It may have any of the forms accepted by Tk_GetBoolean. -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 hasn't 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 tag bind widget command below. The third use for tags is in managing the selection. See THE SELECTION below. 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 isn't 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 right of the mark. 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 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. 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 character'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. When an embedded window is added to a text widget with the window create widget command, several configuration options may be associated with it. These options may be modified later with the 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. 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. THE SELECTION Text widgets support the standard X 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. 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. 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. 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 args 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 isn't. 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 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 debug ?boolean? If boolean is specified, then it must have one of the true or false values accepted by Tcl_GetBoolean. 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. 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 doesn't specify a position later in the text than index1 then no characters are deleted. If index2 isn't specified then the single character at index1 is deleted. It is not allowable to delete characters in a way that would leave the text without a newline as the last character. The command returns an empty string. 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, and window. The corresponding value is the text, mark name, tag name, or window name. The index information is the index of the start of the text, the mark, the tag transition, or the 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, 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. -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 seqments 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 get 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. 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 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 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 dump operation. If a mark has been set to the special end index, then it appears to be after end with respect to the 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 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 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 doesn't 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 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 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 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. -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 command for details). -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 characters in the matching range will be stored in the variable. -- 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 must be entirely within a single line of text. For regular expression matching the newlines are removed from the ends of the lines before matching: use the $ feature in regular expressions to match the end of a line. For exact matching the newlines are retained. 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. 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 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 isn't 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 command except that it operates on characters in a text rather than entire widgets. See the bind 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. Event bindings for a text widget use the current mark described under MARKS 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. 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 command for details). continue and break commands within binding scripts are processed in the same way as for bindings created with the bind command. If bindings are created for the widget as a whole using the bind 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 tag configure widget command. pathName tag configure tagName ?option? ?value? ?option value ...? This command is similar to the 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 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 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 haven't 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 isn't affected). 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. 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 tag 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. 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 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 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 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. 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. 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 character 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 character just after the last 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 character given by fraction appears on the top line of the window. Fraction is a fraction between 0 and 1; 0 indicates the first character in the text, 0.33 indicates the character one-third the way through the text, and so on. pathName yview scroll number what This command adjust 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 on the display; if it is pages then the view adjusts by number screenfuls. 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 isn't 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 see widget command (see handles both x- and y-motion to make a location visible, whereas -pickplace 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" 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 the line under the mouse and positions the insertion cursor at the beginning 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. Control-v moves the view down one screenful without moving the insertion cursor or adjusting the selection. 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 line and clear any selection in the widget. Shift-Home moves the insertion cursor to the beginning of the line and also extends the selection to that point. 14. End and Control-e move the insertion cursor to the end of the line and clear any selection in the widget. Shift-End moves the cursor to the end of the 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 don't 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. 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. 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. 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. 31. Control-t reverses the order of the two characters to the right of the insertion cursor. 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. 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. KEYWORDS text, widget ═══ 6.45. tk ═══ 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 isn't specified, this command returns the name of the application (the name that may be used in send 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 command, this command will reenable them and recreate the send command. KEYWORDS application name, send ═══ 6.46. 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 because the event loop (which is what usually invokes it) is now part of Tcl. The changes are backward compatible, so that old uses of tkerror should still work, but you should modify your scripts to use bgerror instead of tkerror. Documentation for bgerror is available as part of Tcl's documentation. KEYWORDS background error, reporting ═══ 6.47. tkvars ═══ NAME tkvars - 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 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 isn't set or doesn't 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 decimal integer 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. tkPriv This variable is an array containing several pieces of information that are private to Tk. The elements of tkPriv are used by Tk library procedures and default bindings. They should not be accessed by any code outside 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. 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. KEYWORDS variables, version ═══ 6.48. 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. KEYWORDS variable, visibility, wait, window ═══ 6.49. toplevel ═══ NAME toplevel - Create and manipulate toplevel widgets SYNOPSIS toplevel pathName ?options? STANDARD OPTIONS -borderwidth -highlightbackground -highlightthickness -takefocus -cursor -highlightcolor -relief See the options manual entry for detailed descriptions of the above options. 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: -height Database Name: height Database Class: Height Specifies the desired height for the window in any of the forms acceptable to Tk_GetPixels. If this option is less than or equal to zero then the window will not request any size at all. 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: -visual Database Name: visual Database Class: Visual Specifies visual information for the new window in any of the forms accepted by Tk_GetVisual. 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. 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 args 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 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. KEYWORDS toplevel, widget ═══ 6.50. winfo ═══ 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. 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 hasn't 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) 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, 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 widthxheight+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 fulfill the window's needs. If you need the true height immediately after creating a widget, invoke update 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 indicating the X identifier for window. 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 isn't managed by any geometry manager. The name is usually the name of the Tcl command for the geometry manager, such as pack or place. If the geometry manager is a widget, such as canvases or text, the name is the widget's class command, such as canvas. 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, 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 isn't 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 isn't 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 isn't 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, 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 "XmajorRminor 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-level window containing window. 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 fulfill the window's needs. If you need the true width immediately after creating a widget, invoke update 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). KEYWORDS atom, children, class, geometry, height, identifier, information, interpreters, mapped, parent, path name, screen, virtual root, width, window ═══ 6.51. wm ═══ 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 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 isn't 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 isn't 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 isn't 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. 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 command assumes a passive model of focusing. wm frame window If window has been reparented by the window manager into a decorative frame, the command returns the X window identifier for the outermost frame that contains window (the window whose parent is the root or virtual root). If window hasn't been reparented by the window manager then the command returns the X 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 =widthxheightёxёy, where any of =, widthxheight, 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 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. 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. 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 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 isn't 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 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. wm iconify window Arrange for window to be iconified. It window hasn't 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 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 isn't 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 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 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. If resizing has been disabled with the wm resizable command, then this command has no effect. 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. If resizing has been disabled with the wm resizable command, then this command has no effect. 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. 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 window 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 isn't, 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 haven't asked for one with wm protocol. If a WM_DELETE_WINDOW message arrives when you haven't 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 state window Returns the current state of window: either normal, iconic, withdrawn, or icon. 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). 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 isn't 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). Some window managers will use this information to manage window specially. If master is specified as an empty string then window is marked as not being a transient window any more. If master is specified, then the command returns an empty string. Otherwise the command returns the path name of window's current master, or an empty string if window isn't currently a transient window. 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. 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. 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 won't 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. KEYWORDS aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager