OS/2 Shareware BBS: 10 Tools/10-Tools.zip/tcl76inf.zip/tcl76.INF

OS/2 Help File | 1999-06-04 | 763KB | 27,639 lines

ΓòÉΓòÉΓòÉ 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.h>

 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 <tcl.h>

 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.h>

 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 <tcl.h>

 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 <tcl.h>

 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.h>

 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.h>

 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 <tcl.h>

 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.h>

 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 <tcl.h>

 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 <tcl.h>

 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.h>

 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 <tcl.h>

 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 <tcl.h>

 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.h>

 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.h>

 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.h>

 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.h>

 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.h>

 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 <tcl.h>

 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.h>

 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.h>

 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.h>

 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.h>

 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 <tcl.h>

 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.h>

 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 <tcl.h>

 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.h>

 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 <tcl.h>

 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 <tcl.h>

 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.h>

 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 <tcl.h>

 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 <tcl.h>

 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.h>

 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.h>

 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 <tcl.h>

 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 <tcl.h>

 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.h>

 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 <tcl.h>

 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.h>

 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 <tcl.h>

 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.h>

 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.h>

 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 <tcl.h>

 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 <tcl.h>

 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 <tcl.h>

 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 <tcl.h>

 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.h>

 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 <tcl.h>

 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.h>

 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 <tcl.h>

 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.h>

 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.h>

 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 <tcl.h>

 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.h>

 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 <tcl.h>

 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 <tcl.h>

 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 <tcl.h>

 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).

      \<newline>whiteSpace  A single space character replaces the backslash,
                     newline, and all spaces and tabs after the newline. This
                     backslash sequence is unique in that it is replaced in a
                     separate pre-pass before the command is actually parsed.
                     This means that it will be replaced even when it occurs
                     between braces, and the resulting space will be treated as
                     a word separator if it 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. "<fileName").

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

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

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

 <@ fileId  FileId must be the identifier for an open file, such as the return
           value from a previous call to open. 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.h>

 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.h>

 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 <tk.h>

 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.h>

 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.h>

 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 <tk.h>

 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.h>

 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 <tk.h>

 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.h>

 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.h>

 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.h>

 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.h>

 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.h>

 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.h>

 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 <tk.h>
 #include <tkPhoto.h>

 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.h>

 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.h>

 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.h>

 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.h>

 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 <tk.h>
 #include <tkPhoto.h>

 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.h>

 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.h>

 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 <tk.h>

 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 <tk.h>

 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 <tk.h>

 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 <tk.h>

 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 <tk.h>

 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.h>

 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 <tk.h>

 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 <tk.h>

 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.h>

 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 <tk.h>

 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.h>

 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.h>

 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 <tk.h>

 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:

 <none>    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 <tk.h>

 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 <tk.h>

 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.h>

 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 <tk.h>

 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 <tk.h>

 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 <tk.h>

 #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.h>

 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 <tk.h>

 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.h>

 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.h>

 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.h>

 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 <tk.h>

 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.h>

 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.h>

 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.h>

 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.h>

 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.h>

 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.h>

 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.h>

 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 <tk.h>

 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.h>

 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 <tk.h>

 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.h>

 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 <tk.h>

 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 <X11/Xlib.h>.

 KEYWORDS

 above, below, obscure, stacking order


ΓòÉΓòÉΓòÉ 5.60. Tk_RestrictEvents ΓòÉΓòÉΓòÉ

 NAME

Tk_RestrictEvents - filter and selectively delay X events

SYNOPSIS

#include <tk.h>

 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 <tk.h>

 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.h>

 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.h>

 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 <tk.h>

 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 <tk.h>

 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 <tk.h>

 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.h>

 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 <tk.h>

 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:

  <modifier-modifier-type-detail>
 The entire event pattern is surrounded by angle brackets. Inside the angle
 brackets are zero or more modifiers, an event type, and an extra piece of
 information (detail) identifying a particular button or keysym.  Any of the
 fields may be omitted, as long as at least one of type and detail is present.
 The fields must be separated by white space or dashes.

 The third form of pattern is used to specify a user-defined, named virtual
 event.  It has the following syntax:

  <<name>>
 The entire virtual event pattern is surrounded by double angle brackets.
 Inside the angle brackets is the user-defined name of the virtual event.
 Modifiers, such as Shift or Control, may not be combined with a virtual event
 to modify it.  Bindings on a virtual event may be created before the virtual
 event is defined, and if the definition of a virtual event changes
 dynamically, all windows bound to that virtual event will respond immediately
 to the new definition.

 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 <Control-Button-1> will
 match the event, but <Mod1-Button-1> will not. If no modifiers are specified,
 then any combination of modifiers may be present in the event.

 Meta and M refer to whichever of the M1 through M5 modifiers is associated
 with the meta key(s) on the keyboard (keysyms Meta_R and Meta_L). If there are
 no meta keys, or if they are not associated with any modifiers, then Meta and
 M will not match any events. Similarly, the Alt modifier refers to whichever
 modifier is associated with the alt key(s) on the keyboard (keysyms Alt_L and
 Alt_R).

 The Double 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, <Double-Button-1> is equivalent to
 <Button-1><Button-1> 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 <ButtonPress-1>.

 If the event type is KeyPress or KeyRelease, then detail may be specified in
 the form of an X keysym.  Keysyms are textual specifications for particular
 keys on the keyboard; they include all the alphanumeric ASCII characters (e.g.
 "a" is the keysym for the ASCII character "a"), plus descriptions for
 non-alphanumeric characters ("comma" is the keysym for the comma character),
 plus descriptions for all the non-ASCII keys on the keyboard ("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, <Control-comma> is
 equivalent to <Control-KeyPress-comma>.

 BINDING SCRIPTS AND SUBSTITUTIONS

 The script argument to bind is a Tcl script, which will be executed whenever
 the given event sequence occurs. Command will be executed in the same
 interpreter that the bind command was executed in, and it will run at global
 level (only global variables will be accessible). If script contains any %
 characters, then the script will not be executed directly.  Instead, a new
 script will be generated by replacing each %, and the character following it,
 with information from the current event.  The replacement depends on the
 character following the %, as defined in the list below.  Unless otherwise
 indicated, the replacement string is the decimal value of the given field from
 the current event. Some of the substitutions are only valid for certain types
 of events;  if they are used for other types of events the value substituted
 is undefined.

 %%        Replaced with a single percent.

 %#        The number of the last client request processed by the server (the
           serial field from the event).  Valid for all event types.

 %a        The above field from the event, formatted as a hexadecimal number.
           Valid only for Configure events.

 %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 <<Paste>> <Control-y>
  event add <<Paste>> <Button-2>
  event add <<Scroll>> <Button-2>
  bind Entry <<Paste>> {puts Paste}
  bind Entry <<Scroll>> {puts Scroll}
 If the user types Control-y, the <<Paste>> binding will be invoked, but if the
 user presses button 2 then one of either the <<Paste>> or the <<Scroll>>
 bindings will be invoked, but exactly which one gets invoked is undefined.

 If an X event does not match any of the existing bindings, then the event is
 ignored. An unbound event is not considered to be an error.

 MULTI-EVENT SEQUENCES AND IGNORED EVENTS

 When a sequence specified in a bind command contains more than one event
 pattern, then its script is executed whenever the recent events (leading up to
 and including the current event) match the given sequence.  This means, for
 example, that if button 1 is clicked repeatedly the sequence
 <Double-ButtonPress-1> will match each button press but the first. If
 extraneous events that would prevent a match occur in the middle of an event
 sequence then the extraneous events are ignored unless they are KeyPress or
 ButtonPress events. For example, <Double-ButtonPress-1> will match a sequence
 of presses of button 1, even though there will be ButtonRelease events (and
 possibly Motion events) between the ButtonPress events. Furthermore, a
 KeyPress event may be preceded by any number of other KeyPress events for
 modifier keys without the modifier keys preventing a match. For example, the
 event sequence aB will match a press of the a key, a release of the a key, a
 press of the Shift key, and a press of the b key:  the press of Shift is
 ignored because it is a modifier key. Finally, if several Motion events occur
 in a row, only the last one is used for purposes of matching binding
 sequences.

 ERRORS

 If an error occurs in executing the script for a binding then the bgerror
 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 <Button-1> event so that the command is invoked whenever button 1 is
 pressed with the mouse cursor over an item. This means that items in a canvas
 can have behaviors defined by the Tcl scripts bound to them.

 DISPLAY LIST

 The items in a canvas are ordered for purposes of display, with the first item
 in the display list being displayed first, followed by the next item in the
 list, and so on. Items later in the display list obscure those that are
 earlier in the display list and are sometimes referred to as being "on top" of
 earlier items. When a new item is created it is placed at the end of the
 display list, on top of everything else. Widget commands may be used to
 re-arrange the order of the display list.

 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 <<virtual>> sequence ?sequence ...?  Associates the virtual event
           virtual with the physical event sequence(s) given by the sequence
           arguments, so that the virtual event will trigger whenever any one
           of the 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 <<virtual>> ?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 <Shift-Button-2> or
           <<Paste>>. 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 ?<<virtual>>?  Returns information about virtual events. If the
           <<virtual>> argument is omitted, the return value is a list of all
           the virtual events that are currently defined. If <<virtual>> is
           specified then the return value is a list whose elements are the
           physical event sequences currently defined for the given virtual
           event;  if the virtual event is not defined then an empty string is
           returned.

 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 <<Paste>> <Control-y>
  event add <<Paste>> <Button-2>
  event add <<Save>> <Control-X><Control-S>
  event add <<Save>> <Shift-F12>
 In the bind command, a virtual event can be bound like any other builtin event
 type as follows:

  bind Entry <<Paste>> {%W insert [selection get]}
 The double angle brackets are used to specify that a virtual event is being
 bound.  If the user types Control-y or presses button 2, or if a <<Paste>>
 virtual event is synthesized with event generate, then the <<Paste>> binding
 will be invoked.

 If a virtual binding has the exact same sequence as a separate physical
 binding, then the physical binding will take precedence. Consider the
 following example:

  event add <<Paste>> <Control-y> <Meta-Control-y>
  bind Entry <Control-y> {puts Control-y}
  bind Entry <<Paste>> {puts Paste}
 When the user types Control-y the <Control-y> binding will be invoked, because
 a physical event is considered more specific than a virtual event, all other
 things being equal. However, when the user types Meta-Control-y the <<Paste>>
 binding will be invoked, because the Meta modifier in the physical pattern
 associated with the virtual binding is more specific than the <Control-y>
 sequence for the physical event.

 Bindings on a virtual event may be created before the virtual event exists.
 Indeed, the virtual event never actually needs to be defined, for instance, on
 platforms where the specific virtual event would meaningless or ungeneratable.

 When a definition of a virtual event changes at run time, all windows will
 respond immediately to the new definition. Starting from the preceding
 example, if the following code is executed:

  bind <Entry> <Control-y> {}
  event add <<Paste>> <Key-F6>
 the behavior will change such in two ways.  First, the shadowed <<Paste>>
 binding will emerge. Typing Control-y will no longer invoke the <Control-y>
 binding, but instead invoke the virtual event <<Paste>>.  Second, pressing the
 F6 key will now also invoke the <<Paste>> binding.

 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