116 lines
4.3 KiB
Groff
116 lines
4.3 KiB
Groff
'\"
|
|
'\" Copyright (c) 1993 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) LinkVar.3 1.15 96/09/05 17:16:57
|
|
'\"
|
|
.so man.macros
|
|
.TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
int
|
|
\fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR)
|
|
.sp
|
|
\fBTcl_UnlinkVar\fR(\fIinterp, varName\fR)
|
|
.sp
|
|
\fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR)
|
|
.SH ARGUMENTS
|
|
.AS Tcl_Interp writable
|
|
.AP Tcl_Interp *interp in
|
|
Interpreter that contains \fIvarName\fR.
|
|
Also used by \fBTcl_LinkVar\fR to return error messages.
|
|
.AP char *varName in
|
|
Name of global variable. Must be in writable memory: Tcl may make
|
|
temporary modifications to it while parsing the variable name.
|
|
.AP char *addr in
|
|
Address of C variable that is to be linked to \fIvarName\fR.
|
|
.AP 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.
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
\fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable
|
|
named by \fIvarName\fR in sync with the C variable at the address
|
|
given by \fIaddr\fR.
|
|
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.
|
|
\fBTcl_LinkVar\fR normally returns TCL_OK; if an error occurs
|
|
while setting up the link (e.g. because \fIvarName\fR is the
|
|
name of array) then TCL_ERROR is returned and \fIinterp->result\fR
|
|
contains an error message.
|
|
.PP
|
|
The \fItype\fR argument specifies the type of the C variable,
|
|
and must have one of the following values, optionally OR'ed with
|
|
TCL_LINK_READ_ONLY:
|
|
.TP
|
|
\fBTCL_LINK_INT\fR
|
|
The C variable is of type \fBint\fR.
|
|
Any value written into the Tcl variable must have a proper integer
|
|
form acceptable to \fBTcl_GetInt\fR; attempts to write
|
|
non-integer values into \fIvarName\fR will be rejected with
|
|
Tcl errors.
|
|
.TP
|
|
\fBTCL_LINK_DOUBLE\fR
|
|
The C variable is of type \fBdouble\fR.
|
|
Any value written into the Tcl variable must have a proper real
|
|
form acceptable to \fBTcl_GetDouble\fR; attempts to write
|
|
non-real values into \fIvarName\fR will be rejected with
|
|
Tcl errors.
|
|
.TP
|
|
\fBTCL_LINK_BOOLEAN\fR
|
|
The C variable is of type \fBint\fR.
|
|
If its value is zero then it will read from Tcl as ``0'';
|
|
otherwise it will read from Tcl as ``1''.
|
|
Whenever \fIvarName\fR 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 \fBTcl_GetBoolean\fR; attempts to write
|
|
non-boolean values into \fIvarName\fR will be rejected with
|
|
Tcl errors.
|
|
.TP
|
|
\fBTCL_LINK_STRING\fR
|
|
The C variable is of type \fBchar *\fR.
|
|
.VS
|
|
If its value is not null then it must be a pointer to a string
|
|
allocated with \fBTcl_Alloc\fR.
|
|
.VE
|
|
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''.
|
|
.PP
|
|
If the TCL_LINK_READ_ONLY flag is present in \fItype\fR 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.
|
|
.PP
|
|
\fBTcl_UnlinkVar\fR removes the link previously set up for the
|
|
variable given by \fIvarName\fR. If there does not exist a link
|
|
for \fIvarName\fR then the procedure has no effect.
|
|
.PP
|
|
\fBTcl_UpdateLinkedVar\fR 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.
|
|
\fBTcl_UpdateLinkedVar\fR ensures that any traces on the Tcl
|
|
variable are invoked.
|
|
|
|
.SH KEYWORDS
|
|
boolean, integer, link, read-only, real, string, traces, variable
|