tag

Usage:

tag command_name [procedure]

where command_name is the name of any magic command, and procedure is any valid Tcl procedure.

Summary:

The tag command is registers callback procedures to be executed after the indicated magic command has been executed. The primary use of the tag command is to register procedures that update the GUI window in response to commands that are typed on the command line or generated from macro calls.

In keeping with standard methods for Tcl callback functions, certain "escape sequences" beginning with the percent ("%") character are allowed to be embedded in the callback function procedure, and are substituted prior to execution, with the substitutions defined as follows:

%W

Substitute the Tk path of the layout window from which or in reference to which command_name was invoked.

%r

Substitute the previous Tcl result string, but do not reset the Tcl result of the execution of procedure.

%R

Substitute the previous Tcl result string and reset the Tcl result from the execution of procedure such that the the result of command_name becomes the result of procedure.

%[0-5]

Substitute the zeroth to fifth argument to the original command.

%%

Substitute a single percent character.

%char

where char is any character not defined above: No action, print exactly as written.

When a tag callback is used, the return value seen by the interpreter is the return value of the function procedure, not the return value of the tagged command command_name. The escape sequence %R can be used to force the result of command_name to become the result of procedure (unless procedure produces an error condition, in which case the error is returned). The escape sequence %r passes the result of command_name as an argument to the procedure, which may choose to return it as a result, or not.

If no procedure is present, then the tag command returns whatever procedure string is attached to the indicated command_name, if any. This can be used as a way to prevent infinite recursion inside a tag callback; for example,

set savetag [tag callback command]
(procedure calls, which may include a call to command)
tag command $savetag

Another way to avoid infinite recursion is to check the procedure depth from within the tag callback procedure using the Tcl command "info level", to avoid executing the callback procedure if the level is not zero.

Only one tag callback is allowed per command name. However, only one is needed as that procedure may call as many other procedures as it wants to.

Implementation Notes:

tag is implemented as a built-in command in magic, but only in the Tcl version.

Return to command index

Last updated: October 8, 2004 at 10:15pm