| 1 |
578 |
markom |
'\"
|
| 2 |
|
|
'\" Copyright (c) 1993 The Regents of the University of California.
|
| 3 |
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
| 4 |
|
|
'\"
|
| 5 |
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
| 6 |
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
| 7 |
|
|
'\"
|
| 8 |
|
|
'\" RCS: @(#) $Id: LinkVar.3,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $
|
| 9 |
|
|
'\"
|
| 10 |
|
|
.so man.macros
|
| 11 |
|
|
.TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
|
| 12 |
|
|
.BS
|
| 13 |
|
|
.SH NAME
|
| 14 |
|
|
Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
|
| 15 |
|
|
.SH SYNOPSIS
|
| 16 |
|
|
.nf
|
| 17 |
|
|
\fB#include \fR
|
| 18 |
|
|
.sp
|
| 19 |
|
|
int
|
| 20 |
|
|
\fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR)
|
| 21 |
|
|
.sp
|
| 22 |
|
|
\fBTcl_UnlinkVar\fR(\fIinterp, varName\fR)
|
| 23 |
|
|
.sp
|
| 24 |
|
|
\fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR)
|
| 25 |
|
|
.SH ARGUMENTS
|
| 26 |
|
|
.AS Tcl_Interp writable
|
| 27 |
|
|
.AP Tcl_Interp *interp in
|
| 28 |
|
|
Interpreter that contains \fIvarName\fR.
|
| 29 |
|
|
Also used by \fBTcl_LinkVar\fR to return error messages.
|
| 30 |
|
|
.AP char *varName in
|
| 31 |
|
|
Name of global variable. Must be in writable memory: Tcl may make
|
| 32 |
|
|
temporary modifications to it while parsing the variable name.
|
| 33 |
|
|
.AP char *addr in
|
| 34 |
|
|
Address of C variable that is to be linked to \fIvarName\fR.
|
| 35 |
|
|
.AP int type in
|
| 36 |
|
|
Type of C variable. Must be one of TCL_LINK_INT, TCL_LINK_DOUBLE,
|
| 37 |
|
|
TCL_LINK_BOOLEAN, or TCL_LINK_STRING, optionally OR'ed with
|
| 38 |
|
|
TCL_LINK_READ_ONLY to make Tcl variable read-only.
|
| 39 |
|
|
.BE
|
| 40 |
|
|
|
| 41 |
|
|
.SH DESCRIPTION
|
| 42 |
|
|
.PP
|
| 43 |
|
|
\fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable
|
| 44 |
|
|
named by \fIvarName\fR in sync with the C variable at the address
|
| 45 |
|
|
given by \fIaddr\fR.
|
| 46 |
|
|
Whenever the Tcl variable is read the value of the C variable will
|
| 47 |
|
|
be returned, and whenever the Tcl variable is written the C
|
| 48 |
|
|
variable will be updated to have the same value.
|
| 49 |
|
|
\fBTcl_LinkVar\fR normally returns TCL_OK; if an error occurs
|
| 50 |
|
|
while setting up the link (e.g. because \fIvarName\fR is the
|
| 51 |
|
|
name of array) then TCL_ERROR is returned and \fIinterp->result\fR
|
| 52 |
|
|
contains an error message.
|
| 53 |
|
|
.PP
|
| 54 |
|
|
The \fItype\fR argument specifies the type of the C variable,
|
| 55 |
|
|
and must have one of the following values, optionally OR'ed with
|
| 56 |
|
|
TCL_LINK_READ_ONLY:
|
| 57 |
|
|
.TP
|
| 58 |
|
|
\fBTCL_LINK_INT\fR
|
| 59 |
|
|
The C variable is of type \fBint\fR.
|
| 60 |
|
|
Any value written into the Tcl variable must have a proper integer
|
| 61 |
|
|
form acceptable to \fBTcl_GetInt\fR; attempts to write
|
| 62 |
|
|
non-integer values into \fIvarName\fR will be rejected with
|
| 63 |
|
|
Tcl errors.
|
| 64 |
|
|
.TP
|
| 65 |
|
|
\fBTCL_LINK_DOUBLE\fR
|
| 66 |
|
|
The C variable is of type \fBdouble\fR.
|
| 67 |
|
|
Any value written into the Tcl variable must have a proper real
|
| 68 |
|
|
form acceptable to \fBTcl_GetDouble\fR; attempts to write
|
| 69 |
|
|
non-real values into \fIvarName\fR will be rejected with
|
| 70 |
|
|
Tcl errors.
|
| 71 |
|
|
.TP
|
| 72 |
|
|
\fBTCL_LINK_BOOLEAN\fR
|
| 73 |
|
|
The C variable is of type \fBint\fR.
|
| 74 |
|
|
If its value is zero then it will read from Tcl as ``0'';
|
| 75 |
|
|
otherwise it will read from Tcl as ``1''.
|
| 76 |
|
|
Whenever \fIvarName\fR is
|
| 77 |
|
|
modified, the C variable will be set to a 0 or 1 value.
|
| 78 |
|
|
Any value written into the Tcl variable must have a proper boolean
|
| 79 |
|
|
form acceptable to \fBTcl_GetBoolean\fR; attempts to write
|
| 80 |
|
|
non-boolean values into \fIvarName\fR will be rejected with
|
| 81 |
|
|
Tcl errors.
|
| 82 |
|
|
.TP
|
| 83 |
|
|
\fBTCL_LINK_STRING\fR
|
| 84 |
|
|
The C variable is of type \fBchar *\fR.
|
| 85 |
|
|
.VS
|
| 86 |
|
|
If its value is not null then it must be a pointer to a string
|
| 87 |
|
|
allocated with \fBTcl_Alloc\fR.
|
| 88 |
|
|
.VE
|
| 89 |
|
|
Whenever the Tcl variable is modified the current C string will be
|
| 90 |
|
|
freed and new memory will be allocated to hold a copy of the variable's
|
| 91 |
|
|
new value.
|
| 92 |
|
|
If the C variable contains a null pointer then the Tcl variable
|
| 93 |
|
|
will read as ``NULL''.
|
| 94 |
|
|
.PP
|
| 95 |
|
|
If the TCL_LINK_READ_ONLY flag is present in \fItype\fR then the
|
| 96 |
|
|
variable will be read-only from Tcl, so that its value can only be
|
| 97 |
|
|
changed by modifying the C variable.
|
| 98 |
|
|
Attempts to write the variable from Tcl will be rejected with errors.
|
| 99 |
|
|
.PP
|
| 100 |
|
|
\fBTcl_UnlinkVar\fR removes the link previously set up for the
|
| 101 |
|
|
variable given by \fIvarName\fR. If there does not exist a link
|
| 102 |
|
|
for \fIvarName\fR then the procedure has no effect.
|
| 103 |
|
|
.PP
|
| 104 |
|
|
\fBTcl_UpdateLinkedVar\fR may be invoked after the C variable has
|
| 105 |
|
|
changed to force the Tcl variable to be updated immediately.
|
| 106 |
|
|
In many cases this procedure is not needed, since any attempt to
|
| 107 |
|
|
read the Tcl variable will return the latest value of the C variable.
|
| 108 |
|
|
However, if a trace has been set on the Tcl variable (such as a
|
| 109 |
|
|
Tk widget that wishes to display the value of the variable), the
|
| 110 |
|
|
trace will not trigger when the C variable has changed.
|
| 111 |
|
|
\fBTcl_UpdateLinkedVar\fR ensures that any traces on the Tcl
|
| 112 |
|
|
variable are invoked.
|
| 113 |
|
|
|
| 114 |
|
|
.SH KEYWORDS
|
| 115 |
|
|
boolean, integer, link, read-only, real, string, traces, variable
|
