About Us Documentation

Contact Site Map
 

  

WinPak
Documentation

Tcl_UnlinkVar





Tcl_LinkVar(3)       Tcl Library Procedures                   7.5



_________________________________________________________________

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 tem- porary modifications to it while parsing the variable name. char *addr (in) Address of C variable that is to be linked to var- Name. int type (in) Type of C variable. Must be one of TCL_LINK_INT, TCL_LINK_DOUBLE, TCL_LINK_BOOLEAN, or TCL_LINK_STRING, option- ally 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 Tcl 1 Tcl_LinkVar(3) Tcl Library Procedures 7.5 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 Tcl 2 Tcl_LinkVar(3) Tcl Library Procedures 7.5 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 vari- able are invoked.

KEYWORDS

boolean, integer, link, read-only, real, string, traces, variable Tcl 3 Prepared by Ready-to-Run Software, Inc.

 

Email addresses listed on this site may  NOT be used for unsolicited commercial email.

Ready-to-Run Software, Inc Privacy Statement

Portions (c)Copyright, 1996-2005 by Ready-to-Run Software, Inc
(All rights reserved.)
212 Cedar Cove
Lansing, NY 14882
Phone: 607 533 UNIX (8649)
Fax: 607 533 4002


To return to the Ready-to-Run Software WinPak Table of contents please presshere