itcl2.2/ 40755 1751 0 0 6423673776 10757 5ustar kunkeewheelitcl2.2/CVS/ 40755 1751 0 0 6423673673 11406 5ustar kunkeewheelitcl2.2/CVS/Root100644 1751 0 26 6423554630 12276 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/CVS/Repository100644 1751 0 11 6423674263 13531 0ustar kunkeewheel/usr/cvs itcl2.2/CVS/Entries100644 1751 0 1115 6423673673 13035 0ustar kunkeewheel/INSTALL/1.1/Thu Oct 23 04:59:04 1997// /ITCL.CHANGES/1.1.1.1/Thu Oct 23 04:59:05 1997// /ITCL.README/1.1.1.1/Thu Oct 23 04:59:05 1997// /ITCL.TODO/1.1.1.1/Thu Oct 23 04:59:05 1997// /Makefile.in/1.2/Thu Oct 23 04:59:06 1997// /license.terms/1.1.1.1/Thu Oct 23 04:59:06 1997// /makefile.bc/1.1.1.1/Thu Oct 23 04:59:06 1997// /makefile.vc/1.1.1.1/Thu Oct 23 04:59:06 1997// /checkout.sh/1.2/Thu Oct 23 07:21:10 1997// /configure/1.2/Thu Oct 23 07:24:39 1997// /configure.in/1.2/Thu Oct 23 07:24:39 1997// /README/1.2/Thu Oct 23 16:06:26 1997// /RELEASE_NOTES/1.2/Thu Oct 23 15:59:08 1997// itcl2.2/config/ 40755 1751 0 0 6423554633 12212 5ustar kunkeewheelitcl2.2/config/CVS/ 40755 1751 0 0 6423570006 12635 5ustar kunkeewheelitcl2.2/config/CVS/Root100644 1751 0 26 6423554633 13546 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/config/CVS/Repository100644 1751 0 11 6423674263 14776 0ustar kunkeewheel/usr/cvs itcl2.2/config/CVS/Entries100644 1751 0 301 6423570006 14240 0ustar kunkeewheel/config.guess/1.1.1.1/Thu Oct 23 04:59:07 1997// /config.sub/1.1.1.1/Thu Oct 23 04:59:07 1997// /install-sh/1.1.1.1/Thu Oct 23 04:59:07 1997// /mkinstalldirs/1.1.1.1/Thu Oct 23 04:59:07 1997// itcl2.2/config/config.guess100777 1751 0 32325 6423554633 14660 0ustar kunkeewheel#!/bin/sh # Attempt to guess a canonical system name. # Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. # # This file is free software; you can redistribute it and/or modify it # under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, but # WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU # General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. # # As a special exception to the GNU General Public License, if you # distribute this file as part of a program that contains a # configuration script generated by Autoconf, you may include it under # the same distribution terms that you use for the rest of that program. # Written by Per Bothner . # The master version of this file is at the FSF in /home/gd/gnu/lib. # # This script attempts to guess a canonical system name similar to # config.sub. If it succeeds, it prints the system name on stdout, and # exits with 0. Otherwise, it exits with 1. # # The plan is that this can be called by configure scripts if you # don't specify an explicit system type (host/target name). # # Only a few systems have been added to this list; please add others # (but try to keep the structure clean). # # This is needed to find uname on a Pyramid OSx when run in the BSD universe. # (ghazi@noc.rutgers.edu 8/24/94.) if (test -f /.attbin/uname) >/dev/null 2>&1 ; then PATH=$PATH:/.attbin ; export PATH fi UNAME_MACHINE=`(uname -m) 2>/dev/null` || UNAME_MACHINE=unknown UNAME_RELEASE=`(uname -r) 2>/dev/null` || UNAME_RELEASE=unknown UNAME_SYSTEM=`(uname -s) 2>/dev/null` || UNAME_SYSTEM=unknown UNAME_VERSION=`(uname -v) 2>/dev/null` || UNAME_VERSION=unknown trap 'rm -f dummy.c dummy.o dummy; exit 1' 1 2 15 # Note: order is significant - the case branches are not exclusive. case "${UNAME_MACHINE}:${UNAME_SYSTEM}:${UNAME_RELEASE}:${UNAME_VERSION}" in alpha:OSF1:V*:*) # After 1.2, OSF1 uses "V1.3" for uname -r. echo alpha-dec-osf`echo ${UNAME_RELEASE} | sed -e 's/^V//'` exit 0 ;; alpha:OSF1:*:*) # 1.2 uses "1.2" for uname -r. echo alpha-dec-osf${UNAME_RELEASE} exit 0 ;; arm:RISC*:1.[012]*:*|arm:riscix:1.[012]*:*) echo arm-acorn-riscix${UNAME_RELEASE} exit 0;; Pyramid*:OSx*:*:*) if test "`(/bin/universe) 2>/dev/null`" = att ; then echo pyramid-pyramid-sysv3 else echo pyramid-pyramid-bsd fi exit 0 ;; i86pc:SunOS:5.*:*) echo i486-unknown-solaris2`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` exit 0 ;; sun4*:SunOS:5.*:*) echo sparc-sun-solaris2`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` exit 0 ;; sun4*:SunOS:6*:*) # According to config.sub, this is the proper way to canonicalize # SunOS6. Hard to guess exactly what SunOS6 will be like, but # it's likely to be more like Solaris than SunOS4. echo sparc-sun-solaris3`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` exit 0 ;; sun4*:SunOS:*:*) # Japanese Language versions have a version number like `4.1.3-JL'. echo sparc-sun-sunos`echo ${UNAME_RELEASE}|sed -e 's/-/_/'` exit 0 ;; sun3*:SunOS:*:*) echo m68k-sun-sunos${UNAME_RELEASE} exit 0 ;; tp_s2*:SunOS:*:*) # Tadpole Sparcbook 2 running a modified 4.1.3 echo sparc-sun-sunos`echo ${UNAME_RELEASE}|sed -e 's/-/_/'` exit 0 ;; RISC*:ULTRIX:*:*) echo mips-dec-ultrix${UNAME_RELEASE} exit 0 ;; VAX*:ULTRIX*:*:*) echo vax-dec-ultrix${UNAME_RELEASE} exit 0 ;; mips:*:5*:RISCos) echo mips-mips-riscos${UNAME_RELEASE} exit 0 ;; m88k:CX/UX:7*:*) echo m88k-harris-cxux7 exit 0 ;; m88k:*:4*:R4*) echo m88k-motorola-sysv4 exit 0 ;; m88k:*:3*:R3*) echo m88k-motorola-sysv3 exit 0 ;; AViiON:dgux:*:*) if [ ${TARGET_BINARY_INTERFACE}x = m88kdguxelfx \ -o ${TARGET_BINARY_INTERFACE}x = x ] ; then echo m88k-dg-dgux${UNAME_RELEASE} else echo m88k-dg-dguxbcs${UNAME_RELEASE} fi exit 0 ;; M88*:DolphinOS:*:*) # DolphinOS (SVR3) echo m88k-dolphin-sysv3 exit 0 ;; M88*:*:R3*:*) # Delta 88k system running SVR3 echo m88k-motorola-sysv3 exit 0 ;; XD88*:*:*:*) # Tektronix XD88 system running UTekV (SVR3) echo m88k-tektronix-sysv3 exit 0 ;; Tek43[0-9][0-9]:UTek:*:*) # Tektronix 4300 system running UTek (BSD) echo m68k-tektronix-bsd exit 0 ;; *:IRIX:*:*) echo mips-sgi-irix${UNAME_RELEASE} exit 0 ;; i[34]86:AIX:*:*) echo i386-ibm-aix exit 0 ;; *:AIX:2:3) if grep bos325 /usr/include/stdio.h >/dev/null 2>&1; then sed 's/^ //' << EOF >dummy.c #include main() { if (!__power_pc()) exit(1); puts("powerpc-ibm-aix3.2.5"); exit(0); } EOF ${CC-cc} dummy.c -o dummy && ./dummy && rm dummy.c dummy && exit 0 rm -f dummy.c dummy echo rs6000-ibm-aix3.2.5 elif grep bos324 /usr/include/stdio.h >/dev/null 2>&1; then echo rs6000-ibm-aix3.2.4 else echo rs6000-ibm-aix3.2 fi exit 0 ;; *:AIX:*:4) if /usr/sbin/lsattr -EHl proc0 | grep POWER >/dev/null 2>&1; then IBM_ARCH=rs6000 else IBM_ARCH=powerpc fi if grep bos410 /usr/include/stdio.h >/dev/null 2>&1; then IBM_REV=4.1 elif grep bos411 /usr/include/stdio.h >/dev/null 2>&1; then IBM_REV=4.1.1 else IBM_REV=4.${UNAME_RELEASE} fi echo ${IBM_ARCH}-ibm-aix${IBM_REV} exit 0 ;; *:AIX:*:*) echo rs6000-ibm-aix exit 0 ;; *:BOSX:*:*) echo rs6000-bull-bosx exit 0 ;; DPX/2?00:B.O.S.:*:*) echo m68k-bull-sysv3 exit 0 ;; 9000/[34]??:4.3bsd:1.*:*) echo m68k-hp-bsd exit 0 ;; hp300:4.4BSD:*:* | 9000/[34]??:4.3bsd:2.*:*) echo m68k-hp-bsd4.4 exit 0 ;; 9000/[3478]??:HP-UX:*:*) case "${UNAME_MACHINE}" in 9000/31? ) HP_ARCH=m68000 ;; 9000/[34]?? ) HP_ARCH=m68k ;; 9000/7?? | 9000/8?7 ) HP_ARCH=hppa1.1 ;; 9000/8?? ) HP_ARCH=hppa1.0 ;; esac HPUX_REV=`echo ${UNAME_RELEASE}|sed -e 's/[^.]*.[0B]*//'` echo ${HP_ARCH}-hp-hpux${HPUX_REV} exit 0 ;; 3050*:HI-UX:*:*) sed 's/^ //' << EOF >dummy.c #include int main () { long cpu = sysconf (_SC_CPU_VERSION); /* The order matters, because CPU_IS_HP_MC68K erroneously returns true for CPU_PA_RISC1_0. CPU_IS_PA_RISC returns correct results, however. */ if (CPU_IS_PA_RISC (cpu)) { switch (cpu) { case CPU_PA_RISC1_0: puts ("hppa1.0-hitachi-hiuxwe2"); break; case CPU_PA_RISC1_1: puts ("hppa1.1-hitachi-hiuxwe2"); break; case CPU_PA_RISC2_0: puts ("hppa2.0-hitachi-hiuxwe2"); break; default: puts ("hppa-hitachi-hiuxwe2"); break; } } else if (CPU_IS_HP_MC68K (cpu)) puts ("m68k-hitachi-hiuxwe2"); else puts ("unknown-hitachi-hiuxwe2"); exit (0); } EOF ${CC-cc} dummy.c -o dummy && ./dummy && rm dummy.c dummy && exit 0 rm -f dummy.c dummy echo unknown-hitachi-hiuxwe2 exit 0 ;; 9000/7??:4.3bsd:*:* | 9000/8?7:4.3bsd:*:* ) echo hppa1.1-hp-bsd exit 0 ;; 9000/8??:4.3bsd:*:*) echo hppa1.0-hp-bsd exit 0 ;; hp7??:OSF1:*:* | hp8?7:OSF1:*:* ) echo hppa1.1-hp-osf exit 0 ;; hp8??:OSF1:*:*) echo hppa1.0-hp-osf exit 0 ;; C1*:ConvexOS:*:* | convex:ConvexOS:C1*:*) echo c1-convex-bsd exit 0 ;; C2*:ConvexOS:*:* | convex:ConvexOS:C2*:*) if getsysinfo -f scalar_acc then echo c32-convex-bsd else echo c2-convex-bsd fi exit 0 ;; C34*:ConvexOS:*:* | convex:ConvexOS:C34*:*) echo c34-convex-bsd exit 0 ;; C38*:ConvexOS:*:* | convex:ConvexOS:C38*:*) echo c38-convex-bsd exit 0 ;; C4*:ConvexOS:*:* | convex:ConvexOS:C4*:*) echo c4-convex-bsd exit 0 ;; CRAY*X-MP:UNICOS:*:*) echo xmp-cray-unicos exit 0 ;; CRAY*Y-MP:UNICOS:*:*) echo ymp-cray-unicos exit 0 ;; CRAY-2:UNICOS:*:*) echo cray2-cray-unicos exit 0 ;; hp3[0-9][05]:NetBSD:*:*) echo m68k-hp-netbsd${UNAME_RELEASE} exit 0 ;; i[34]86:BSD/386:*:*) echo ${UNAME_MACHINE}-unknown-bsdi${UNAME_RELEASE} exit 0 ;; i[34]86:BSD/OS:*:*) echo ${UNAME_MACHINE}-unknown-bsdi${UNAME_RELEASE} exit 0 ;; *:FreeBSD:*:*) echo ${UNAME_MACHINE}-unknown-freebsd`echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'` exit 0 ;; *:NetBSD:*:*) echo ${UNAME_MACHINE}-unknown-netbsd`echo ${UNAME_RELEASE}|sed -e 's/[-_].*/\./'` exit 0 ;; *:GNU:*:*) echo `echo ${UNAME_MACHINE}|sed -e 's,/.*$,,'`-unknown-gnu`echo ${UNAME_RELEASE}|sed -e 's,/.*$,,'` exit 0 ;; *:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux exit 0 ;; # ptx 4.0 does uname -s correctly, with DYNIX/ptx in there. earlier versions # are messed up and put the nodename in both sysname and nodename. i[34]86:DYNIX/ptx:4*:*) echo i386-sequent-sysv4 exit 0 ;; i[34]86:*:4.*:* | i[34]86:SYSTEM_V:4.*:*) if grep Novell /usr/include/link.h >/dev/null 2>/dev/null; then echo ${UNAME_MACHINE}-univel-sysv${UNAME_RELEASE} else echo ${UNAME_MACHINE}-unknown-sysv${UNAME_RELEASE} fi exit 0 ;; i[34]86:*:3.2:*) if /bin/uname -X 2>/dev/null >/dev/null ; then UNAME_REL=`(/bin/uname -X|egrep Release|sed -e 's/.*= //')` (/bin/uname -X|egrep i80486 >/dev/null) && UNAME_MACHINE=i486 echo ${UNAME_MACHINE}-unknown-sco$UNAME_REL elif test -f /usr/options/cb.name; then UNAME_REL=`sed -n 's/.*Version //p' /dev/null 2>&1 ; then echo i860-stardent-sysv${UNAME_RELEASE} # Stardent Vistra i860-SVR4 else # Add other i860-SVR4 vendors below as they are discovered. echo i860-unknown-sysv${UNAME_RELEASE} # Unknown i860-SVR4 fi exit 0 ;; mini*:CTIX:SYS*5:*) # "miniframe" echo m68010-convergent-sysv exit 0 ;; M680[234]0:*:R3V[567]*:*) test -r /sysV68 && echo 'm68k-motorola-sysv' && exit 0 ;; 3[34]??:*:4.0:3.0 | 3[34]??,*:*:4.0:3.0) uname -p 2>/dev/null | grep 86 >/dev/null \ && echo i486-ncr-sysv4.3 && exit 0 ;; 3[34]??:*:4.0:* | 3[34]??,*:*:4.0:*) uname -p 2>/dev/null | grep 86 >/dev/null \ && echo i486-ncr-sysv4 && exit 0 ;; m680[234]0:LynxOS:2.2*:*) echo m68k-lynx-lynxos${UNAME_RELEASE} exit 0 ;; PowerPC:LynxOS:2.2*:*) echo powerpc-lynx-lynxos${UNAME_RELEASE} exit 0 ;; mc68030:UNIX_System_V:4.*:*) echo m68k-atari-sysv4 exit 0 ;; i[34]86:LynxOS:2.2*:*) echo i386-lynx-lynxos${UNAME_RELEASE} exit 0 ;; TSUNAMI:LynxOS:2.2*:*) echo sparc-lynx-lynxos${UNAME_RELEASE} exit 0 ;; rs6000:LynxOS:2.2*:*) echo rs6000-lynx-lynxos${UNAME_RELEASE} exit 0 ;; RM*:SINIX-*:*:*) echo mips-sni-sysv4 exit 0 ;; *:SINIX-*:*:*) if uname -p 2>/dev/null >/dev/null ; then UNAME_MACHINE=`(uname -p) 2>/dev/null` echo ${UNAME_MACHINE}-sni-sysv4 else echo ns32k-sni-sysv fi exit 0 ;; esac #echo '(No uname command or uname output not recognized.)' 1>&2 #echo "${UNAME_MACHINE}:${UNAME_SYSTEM}:${UNAME_RELEASE}:${UNAME_VERSION}" 1>&2 cat >dummy.c </dev/null`; printf ("%s-next-nextstep%s\n", __ARCHITECTURE__, version==2 ? "2" : "3"); exit (0); #endif #if defined (MULTIMAX) || defined (n16) #if defined (UMAXV) printf ("ns32k-encore-sysv\n"); exit (0); #else #if defined (CMU) printf ("ns32k-encore-mach\n"); exit (0); #else printf ("ns32k-encore-bsd\n"); exit (0); #endif #endif #endif #if defined (__386BSD__) printf ("i386-unknown-bsd\n"); exit (0); #endif #if defined (sequent) #if defined (i386) printf ("i386-sequent-dynix\n"); exit (0); #endif #if defined (ns32000) printf ("ns32k-sequent-dynix\n"); exit (0); #endif #endif #if defined (_SEQUENT_) printf ("i386-sequent-ptx\n"); exit (0); #endif #if defined (vax) #if !defined (ultrix) printf ("vax-dec-bsd\n"); exit (0); #else printf ("vax-dec-ultrix\n"); exit (0); #endif #endif #if defined (alliant) && defined (i860) printf ("i860-alliant-bsd\n"); exit (0); #endif exit (1); } EOF ${CC-cc} dummy.c -o dummy 2>/dev/null && ./dummy && rm dummy.c dummy && exit 0 rm -f dummy.c dummy # Apollos put the system type in the environment. test -d /usr/apollo && { echo ${ISP}-apollo-${SYSTYPE}; exit 0; } # Convex versions that predate uname can use getsysinfo(1) if [ -x /usr/convex/getsysinfo ] then case `getsysinfo -f cpu_type` in c1*) echo c1-convex-bsd exit 0 ;; c2*) if getsysinfo -f scalar_acc then echo c32-convex-bsd else echo c2-convex-bsd fi exit 0 ;; c34*) echo c34-convex-bsd exit 0 ;; c38*) echo c38-convex-bsd exit 0 ;; c4*) echo c4-convex-bsd exit 0 ;; esac fi #echo '(Unable to guess system type)' 1>&2 exit 1 itcl2.2/config/config.sub100777 1751 0 37676 6423554633 14341 0ustar kunkeewheel#!/bin/sh # Configuration validation subroutine script, version 1.1. # Copyright (C) 1991, 1992, 1993, 1994 Free Software Foundation, Inc. # This file is (in principle) common to ALL GNU software. # The presence of a machine in this file suggests that SOME GNU software # can handle that machine. It does not imply ALL GNU software can. # # This file is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. # As a special exception to the GNU General Public License, if you # distribute this file as part of a program that contains a # configuration script generated by Autoconf, you may include it under # the same distribution terms that you use for the rest of that program. # Configuration subroutine to validate and canonicalize a configuration type. # Supply the specified configuration type as an argument. # If it is invalid, we print an error message on stderr and exit with code 1. # Otherwise, we print the canonical config type on stdout and succeed. # This file is supposed to be the same for all GNU packages # and recognize all the CPU types, system types and aliases # that are meaningful with *any* GNU software. # Each package is responsible for reporting which valid configurations # it does not support. The user should be able to distinguish # a failure to support a valid configuration from a meaningless # configuration. # The goal of this file is to map all the various variations of a given # machine specification into a single specification in the form: # CPU_TYPE-MANUFACTURER-OPERATING_SYSTEM # It is wrong to echo any other type of specification. # First pass through any local machine types. case $1 in *local*) echo $1 exit 0 ;; *) ;; esac # Separate what the user gave into CPU-COMPANY and OS (if any). basic_machine=`echo $1 | sed 's/-[^-]*$//'` if [ $basic_machine != $1 ] then os=`echo $1 | sed 's/.*-/-/'` else os=; fi ### Let's recognize common machines as not being operating systems so ### that things like config.sub decstation-3100 work. We also ### recognize some manufacturers as not being operating systems, so we ### can provide default operating systems below. case $os in -sun*os*) # Prevent following clause from handling this invalid input. ;; -dec* | -mips* | -sequent* | -encore* | -pc532* | -sgi* | -sony* | \ -att* | -7300* | -3300* | -delta* | -motorola* | -sun[234]* | \ -unicom* | -ibm* | -next | -hp | -isi* | -apollo | -altos* | \ -convergent* | -ncr* | -news | -32* | -3600* | -3100* | -hitachi* |\ -c[123]* | -convex* | -sun | -crds | -omron* | -dg | -ultra | -tti* | \ -harris | -dolphin | -highlevel | -gould | -cbm | -ns | -masscomp ) os= basic_machine=$1 ;; -hiux*) os=-hiuxwe2 ;; -sco4) os=-sco3.2v4 basic_machine=`echo $1 | sed -e 's/86-.*/86-unknown/'` ;; -sco3.2.[4-9]*) os=`echo $os | sed -e 's/sco3.2./sco3.2v/'` basic_machine=`echo $1 | sed -e 's/86-.*/86-unknown/'` ;; -sco3.2v[4-9]*) # Don't forget version if it is 3.2v4 or newer. basic_machine=`echo $1 | sed -e 's/86-.*/86-unknown/'` ;; -sco*) os=-sco3.2v2 basic_machine=`echo $1 | sed -e 's/86-.*/86-unknown/'` ;; -isc) os=-isc2.2 basic_machine=`echo $1 | sed -e 's/86-.*/86-unknown/'` ;; -clix*) basic_machine=clipper-intergraph ;; -isc*) basic_machine=`echo $1 | sed -e 's/86-.*/86-unknown/'` ;; -lynx) os=-lynxos ;; -ptx*) basic_machine=`echo $1 | sed -e 's/86-.*/86-sequent/'` ;; -windowsnt*) os=`echo $os | sed -e 's/windowsnt/winnt/'` ;; esac # Decode aliases for certain CPU-COMPANY combinations. case $basic_machine in # Recognize the basic CPU types without company name. # Some are omitted here because they have special meanings below. tahoe | i[345]86 | i860 | m68k | m68000 | m88k | ns32k | arm | pyramid \ | tron | a29k | 580 | i960 | h8300 | hppa1.0 | hppa1.1 \ | alpha | we32k | ns16k | clipper | sparclite | i370 | sh \ | powerpc | sparc64 | 1750a | dsp16xx | mips64 | mipsel \ | pdp11 | mips64el | mips64orion | mips64orionel ) basic_machine=$basic_machine-unknown ;; # Object if more than one company name word. *-*-*) echo Invalid configuration \`$1\': machine \`$basic_machine\' not recognized 1>&2 exit 1 ;; # Recognize the basic CPU types with company name. vax-* | tahoe-* | i[345]86-* | i860-* | m68k-* | m68000-* | m88k-* \ | sparc-* | ns32k-* | fx80-* | arm-* | c[123]* \ | mips-* | pyramid-* | tron-* | a29k-* | romp-* | rs6000-* \ | none-* | 580-* | cray2-* | h8300-* | i960-* | xmp-* | ymp-* \ | hppa1.0-* | hppa1.1-* | alpha-* | we32k-* | cydra-* | ns16k-* \ | pn-* | np1-* | xps100-* | clipper-* | orion-* | sparclite-* \ | pdp11-* | sh-* | powerpc-* | sparc64-* | mips64-* | mipsel-* \ | mips64el-* | mips64orion-* | mips64orionel-* ) ;; # Recognize the various machine names and aliases which stand # for a CPU type and a company and sometimes even an OS. 3b1 | 7300 | 7300-att | att-7300 | pc7300 | safari | unixpc) basic_machine=m68000-att ;; 3b*) basic_machine=we32k-att ;; alliant | fx80) basic_machine=fx80-alliant ;; altos | altos3068) basic_machine=m68k-altos ;; am29k) basic_machine=a29k-none os=-bsd ;; amdahl) basic_machine=580-amdahl os=-sysv ;; amiga | amiga-*) basic_machine=m68k-cbm ;; amigados) basic_machine=m68k-cbm os=-amigados ;; amigaunix | amix) basic_machine=m68k-cbm os=-sysv4 ;; apollo68) basic_machine=m68k-apollo os=-sysv ;; balance) basic_machine=ns32k-sequent os=-dynix ;; convex-c1) basic_machine=c1-convex os=-bsd ;; convex-c2) basic_machine=c2-convex os=-bsd ;; convex-c32) basic_machine=c32-convex os=-bsd ;; convex-c34) basic_machine=c34-convex os=-bsd ;; convex-c38) basic_machine=c38-convex os=-bsd ;; cray | ymp) basic_machine=ymp-cray os=-unicos ;; cray2) basic_machine=cray2-cray os=-unicos ;; crds | unos) basic_machine=m68k-crds ;; da30 | da30-*) basic_machine=m68k-da30 ;; decstation | decstation-3100 | pmax | pmax-* | pmin | dec3100 | decstatn) basic_machine=mips-dec ;; delta | 3300 | motorola-3300 | motorola-delta \ | 3300-motorola | delta-motorola) basic_machine=m68k-motorola ;; delta88) basic_machine=m88k-motorola os=-sysv3 ;; dpx20 | dpx20-*) basic_machine=rs6000-bull os=-bosx ;; dpx2* | dpx2*-bull) basic_machine=m68k-bull os=-sysv3 ;; ebmon29k) basic_machine=a29k-amd os=-ebmon ;; elxsi) basic_machine=elxsi-elxsi os=-bsd ;; encore | umax | mmax) basic_machine=ns32k-encore ;; fx2800) basic_machine=i860-alliant ;; genix) basic_machine=ns32k-ns ;; gmicro) basic_machine=tron-gmicro os=-sysv ;; h3050r* | hiux*) basic_machine=hppa1.1-hitachi os=-hiuxwe2 ;; h8300hms) basic_machine=h8300-hitachi os=-hms ;; harris) basic_machine=m88k-harris os=-sysv3 ;; hp300-*) basic_machine=m68k-hp ;; hp300bsd) basic_machine=m68k-hp os=-bsd ;; hp300hpux) basic_machine=m68k-hp os=-hpux ;; hp9k2[0-9][0-9] | hp9k31[0-9]) basic_machine=m68000-hp ;; hp9k3[2-9][0-9]) basic_machine=m68k-hp ;; hp9k7[0-9][0-9] | hp7[0-9][0-9] | hp9k8[0-9]7 | hp8[0-9]7) basic_machine=hppa1.1-hp ;; hp9k8[0-9][0-9] | hp8[0-9][0-9]) basic_machine=hppa1.0-hp ;; i370-ibm* | ibm*) basic_machine=i370-ibm os=-mvs ;; # I'm not sure what "Sysv32" means. Should this be sysv3.2? i[345]86v32) basic_machine=`echo $1 | sed -e 's/86.*/86-unknown/'` os=-sysv32 ;; i[345]86v4*) basic_machine=`echo $1 | sed -e 's/86.*/86-unknown/'` os=-sysv4 ;; i[345]86v) basic_machine=`echo $1 | sed -e 's/86.*/86-unknown/'` os=-sysv ;; i[345]86sol2) basic_machine=`echo $1 | sed -e 's/86.*/86-unknown/'` os=-solaris2 ;; iris | iris4d) basic_machine=mips-sgi case $os in -irix*) ;; *) os=-irix4 ;; esac ;; isi68 | isi) basic_machine=m68k-isi os=-sysv ;; m88k-omron*) basic_machine=m88k-omron ;; magnum | m3230) basic_machine=mips-mips os=-sysv ;; merlin) basic_machine=ns32k-utek os=-sysv ;; miniframe) basic_machine=m68000-convergent ;; mips3*-*) basic_machine=`echo $basic_machine | sed -e 's/mips3/mips64/'` ;; mips3*) basic_machine=`echo $basic_machine | sed -e 's/mips3/mips64/'`-unknown ;; ncr3000) basic_machine=i486-ncr os=-sysv4 ;; news | news700 | news800 | news900) basic_machine=m68k-sony os=-newsos ;; news1000) basic_machine=m68030-sony os=-newsos ;; news-3600 | risc-news) basic_machine=mips-sony os=-newsos ;; next | m*-next ) basic_machine=m68k-next case $os in -nextstep* ) ;; -ns2*) os=-nextstep2 ;; *) os=-nextstep3 ;; esac ;; nh3000) basic_machine=m68k-harris os=-cxux ;; nh[45]000) basic_machine=m88k-harris os=-cxux ;; nindy960) basic_machine=i960-intel os=-nindy ;; np1) basic_machine=np1-gould ;; pa-hitachi) basic_machine=hppa1.1-hitachi os=-hiuxwe2 ;; paragon) basic_machine=i860-intel os=-osf ;; pbd) basic_machine=sparc-tti ;; pbb) basic_machine=m68k-tti ;; pc532 | pc532-*) basic_machine=ns32k-pc532 ;; pentium-*) # We will change tis to say i586 once there has been # time for various packages to start to recognize that. basic_machine=i486-`echo $basic_machine | sed 's/^[^-]*-//'` ;; pn) basic_machine=pn-gould ;; ps2) basic_machine=i386-ibm ;; rtpc | rtpc-*) basic_machine=romp-ibm ;; sequent) basic_machine=i386-sequent ;; sh) basic_machine=sh-hitachi os=-hms ;; sps7) basic_machine=m68k-bull os=-sysv2 ;; spur) basic_machine=spur-unknown ;; sun2) basic_machine=m68000-sun ;; sun2os3) basic_machine=m68000-sun os=-sunos3 ;; sun2os4) basic_machine=m68000-sun os=-sunos4 ;; sun3os3) basic_machine=m68k-sun os=-sunos3 ;; sun3os4) basic_machine=m68k-sun os=-sunos4 ;; sun4os3) basic_machine=sparc-sun os=-sunos3 ;; sun4os4) basic_machine=sparc-sun os=-sunos4 ;; sun3 | sun3-*) basic_machine=m68k-sun ;; sun4) basic_machine=sparc-sun ;; sun386 | sun386i | roadrunner) basic_machine=i386-sun ;; symmetry) basic_machine=i386-sequent os=-dynix ;; tower | tower-32) basic_machine=m68k-ncr ;; ultra3) basic_machine=a29k-nyu os=-sym1 ;; vaxv) basic_machine=vax-dec os=-sysv ;; vms) basic_machine=vax-dec os=-vms ;; vxworks960) basic_machine=i960-wrs os=-vxworks ;; vxworks68) basic_machine=m68k-wrs os=-vxworks ;; xmp) basic_machine=xmp-cray os=-unicos ;; xps | xps100) basic_machine=xps100-honeywell ;; none) basic_machine=none-none os=-none ;; # Here we handle the default manufacturer of certain CPU types. It is in # some cases the only manufacturer, in others, it is the most popular. mips) basic_machine=mips-mips ;; romp) basic_machine=romp-ibm ;; rs6000) basic_machine=rs6000-ibm ;; vax) basic_machine=vax-dec ;; pdp11) basic_machine=pdp11-dec ;; we32k) basic_machine=we32k-att ;; sparc) basic_machine=sparc-sun ;; cydra) basic_machine=cydra-cydrome ;; orion) basic_machine=orion-highlevel ;; orion105) basic_machine=clipper-highlevel ;; *) echo Invalid configuration \`$1\': machine \`$basic_machine\' not recognized 1>&2 exit 1 ;; esac # Here we canonicalize certain aliases for manufacturers. case $basic_machine in *-digital*) basic_machine=`echo $basic_machine | sed 's/digital.*/dec/'` ;; *-commodore*) basic_machine=`echo $basic_machine | sed 's/commodore.*/cbm/'` ;; *) ;; esac # Decode manufacturer-specific aliases for certain operating systems. if [ x"$os" != x"" ] then case $os in # -solaris* is a basic system type, with this one exception. -solaris1 | -solaris1.*) os=`echo $os | sed -e 's|solaris1|sunos4|'` ;; -solaris) os=-solaris2 ;; -gnu/linux*) os=`echo $os | sed -e 's|gnu/linux|linux|'` ;; # First accept the basic system types. # The portable systems comes first. # Each alternative must end in a *, to match a version number. # -sysv* is not here because it comes later, after sysvr4. -gnu* | -bsd* | -mach* | -minix* | -genix* | -ultrix* | -irix* \ | -vms* | -sco* | -esix* | -isc* | -aix* | -sunos | -sunos[345]* \ | -hpux* | -unos* | -osf* | -luna* | -dgux* | -solaris* | -sym* \ | -amigados* | -msdos* | -newsos* | -unicos* | -aos* \ | -nindy* | -vxworks* | -ebmon* | -hms* | -mvs* | -clix* \ | -riscos* | -linux* | -uniplus* | -iris* | -rtu* | -xenix* \ | -hiux* | -386bsd* | -netbsd* | -freebsd* | -riscix* \ | -lynxos* | -bosx* | -nextstep* | -cxux* | -aout* | -elf* \ | -ptx* | -coff* | -winnt*) ;; -sunos5*) os=`echo $os | sed -e 's|sunos5|solaris2|'` ;; -sunos6*) os=`echo $os | sed -e 's|sunos6|solaris3|'` ;; -osfrose*) os=-osfrose ;; -osf*) os=-osf ;; -utek*) os=-bsd ;; -dynix*) os=-bsd ;; -acis*) os=-aos ;; -ctix* | -uts*) os=-sysv ;; -triton*) os=-sysv3 ;; -oss*) os=-sysv3 ;; -svr4) os=-sysv4 ;; -svr3) os=-sysv3 ;; -sysvr4) os=-sysv4 ;; # This must come after -sysvr4. -sysv*) ;; -xenix) os=-xenix ;; -none) ;; *) # Get rid of the `-' at the beginning of $os. os=`echo $os | sed 's/[^-]*-//'` echo Invalid configuration \`$1\': system \`$os\' not recognized 1>&2 exit 1 ;; esac else # Here we handle the default operating systems that come with various machines. # The value should be what the vendor currently ships out the door with their # machine or put another way, the most popular os provided with the machine. # Note that if you're going to try to match "-MANUFACTURER" here (say, # "-sun"), then you have to tell the case statement up towards the top # that MANUFACTURER isn't an operating system. Otherwise, code above # will signal an error saying that MANUFACTURER isn't an operating # system, and we'll never get to this point. case $basic_machine in *-acorn) os=-riscix1.2 ;; pdp11-*) os=-none ;; *-dec | vax-*) os=-ultrix4.2 ;; i386-sun) os=-sunos4.0.2 ;; m68000-sun) os=-sunos3 # This also exists in the configure program, but was not the # default. # os=-sunos4 ;; *-tti) # must be before sparc entry or we get the wrong os. os=-sysv3 ;; sparc-* | *-sun) os=-sunos4.1.1 ;; *-ibm) os=-aix ;; *-hp) os=-hpux ;; *-hitachi) os=-hiux ;; i860-* | *-att | *-ncr | *-altos | *-motorola | *-convergent) os=-sysv ;; *-cbm) os=-amigados ;; *-dg) os=-dgux ;; *-dolphin) os=-sysv3 ;; m68k-ccur) os=-rtu ;; m88k-omron*) os=-luna ;; *-sequent) os=-ptx ;; *-crds) os=-unos ;; *-ns) os=-genix ;; i370-*) os=-mvs ;; *-next) os=-nextstep3 ;; *-gould) os=-sysv ;; *-highlevel) os=-bsd ;; *-encore) os=-bsd ;; *-sgi) os=-irix ;; *-masscomp) os=-rtu ;; *) os=-none ;; esac fi # Here we handle the case where we know the os, and the CPU type, but not the # manufacturer. We pick the logical manufacturer. vendor=unknown case $basic_machine in *-unknown) case $os in -riscix*) vendor=acorn ;; -sunos*) vendor=sun ;; -lynxos*) vendor=lynx ;; -aix*) vendor=ibm ;; -hpux*) vendor=hp ;; -hiux*) vendor=hitachi ;; -unos*) vendor=crds ;; -dgux*) vendor=dg ;; -luna*) vendor=omron ;; -genix*) vendor=ns ;; -mvs*) vendor=ibm ;; -ptx*) vendor=sequent ;; esac basic_machine=`echo $basic_machine | sed "s/unknown/$vendor/"` ;; esac echo $basic_machine$os itcl2.2/config/install-sh100777 1751 0 4212 6423554633 14316 0ustar kunkeewheel#!/bin/sh # # install - install a program, script, or datafile # This comes from X11R5; it is not part of GNU. # # $XConsortium: install.sh,v 1.2 89/12/18 14:47:22 jim Exp $ # # This script is compatible with the BSD install script, but was written # from scratch. # # set DOITPROG to echo to test this script # Don't use :- since 4.3BSD and earlier shells don't like it. doit="${DOITPROG-}" # put in absolute paths if you don't have them in your path; or use env. vars. mvprog="${MVPROG-mv}" cpprog="${CPPROG-cp}" chmodprog="${CHMODPROG-chmod}" chownprog="${CHOWNPROG-chown}" chgrpprog="${CHGRPPROG-chgrp}" stripprog="${STRIPPROG-strip}" rmprog="${RMPROG-rm}" instcmd="$mvprog" chmodcmd="" chowncmd="" chgrpcmd="" stripcmd="" rmcmd="$rmprog -f" mvcmd="$mvprog" src="" dst="" while [ x"$1" != x ]; do case $1 in -c) instcmd="$cpprog" shift continue;; -m) chmodcmd="$chmodprog $2" shift shift continue;; -o) chowncmd="$chownprog $2" shift shift continue;; -g) chgrpcmd="$chgrpprog $2" shift shift continue;; -s) stripcmd="$stripprog" shift continue;; *) if [ x"$src" = x ] then src=$1 else dst=$1 fi shift continue;; esac done if [ x"$src" = x ] then echo "install: no input file specified" exit 1 fi if [ x"$dst" = x ] then echo "install: no destination specified" exit 1 fi # If destination is a directory, append the input filename; if your system # does not like double slashes in filenames, you may need to add some logic if [ -d $dst ] then dst="$dst"/`basename $src` fi # Make a temp file name in the proper directory. dstdir=`dirname $dst` dsttmp=$dstdir/#inst.$$# # Move or copy the file name to the temp name $doit $instcmd $src $dsttmp # and set any options; do chmod last to preserve setuid bits if [ x"$chowncmd" != x ]; then $doit $chowncmd $dsttmp; fi if [ x"$chgrpcmd" != x ]; then $doit $chgrpcmd $dsttmp; fi if [ x"$stripcmd" != x ]; then $doit $stripcmd $dsttmp; fi if [ x"$chmodcmd" != x ]; then $doit $chmodcmd $dsttmp; fi # Now rename the file to the real destination. $doit $rmcmd $dst $doit $mvcmd $dsttmp $dst exit 0 itcl2.2/config/mkinstalldirs100777 1751 0 1212 6423554633 15115 0ustar kunkeewheel#! /bin/sh # mkinstalldirs --- make directory hierarchy # Author: Noah Friedman # Created: 1993-05-16 # Last modified: 1994-03-25 # Public domain errstatus=0 for file in ${1+"$@"} ; do set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'` shift pathcomp= for d in ${1+"$@"} ; do pathcomp="$pathcomp$d" case "$pathcomp" in -* ) pathcomp=./$pathcomp ;; esac if test ! -d "$pathcomp"; then echo "mkdir $pathcomp" 1>&2 mkdir "$pathcomp" || errstatus=$? fi pathcomp="$pathcomp/" done done exit $errstatus # mkinstalldirs ends here itcl2.2/INSTALL100666 1751 0 13230 6423554630 12113 0ustar kunkeewheel INSTALLATION: We have not changed the native Itcl2.2 installation, simply extended it, and integrated other packages. To build, type: configure --enable-shared --enable-gcc --prefix=/usr/neotcl7.6 then type make then type make install If you run into trouble, checkout the suggestions at the end of this section. See the README about potential DB file incompatability. We encourage the use of the following options: --prefix= --enable-shared --enable-gcc (if you want are using gcc) Neo7.6.0 contains several additonal options which are: --without-db disable db command --with-db[=dir-of-libdb.a] enable db (default) via neoXdb.c --without-encryption disable NeoSoft Encryption commands --without-cute do not include CUTE If you `--enable-shared', neo7.6.0 will also build db.1.85 as a shared library. If the db library linked against is not a shared library. "package require Neo" won't work. If you don't care about the `db' command, build using `--without-db'. libraries. If your o/s comes with a shared library version already (eg. some Linux systems I know of) you may use `--with-db=system' to indicate to use the system db libraries. Future releases will generate a shared library automatically. It is safe to use these options in the toplevel configure script and let it call the other packages with them. CUTE is a utility to talk to a tty device. It was written before Expect existed and is not as full-featured, but is included for backwards compatability with some of our software. We discourage the use of --with-arch (a TclX option), and we don't guarantee that --exec-prefix will work for all packages. The 7.6 integration implements the following --with options. Use them if we have a package you don't care about or don't need that's giving you trouble: --without-tk do not build the Tk toolkit --without-itcl do not build Itcl --without-itk do not build Itk --without-iwidgets do not build Iwidgets --without-tclx do not build Extended Tcl (TclX) --without-neo do not build the NeoSoft (Neo) package --without-expect do not build Expect --without-dp do not build Dp --without-gd do not build Gd --without-x do not build Tk nor packages that use Tk --with-nws build only the minimum required by NeoWebScript* * NeoWebScript is a module extension to the Apache webserver that allows for server-side includes that execute Tcl code without spawning a separate process. See http://www.neowebscript.com. We have seen the following build problems which are easily resolved: - If you get a syntax error in a configure script, you are probably running an old Bourne shell with half a brain. The native /bin/sh on BSDI1.1 and FreeBSD are like this. Use "bash" instead by setting the environment variable "CONFIG_SHELL" to the path of your bash. If you don't want to bother with bash, try ksh if your system has it. VERY IMPORTANT: Make sure that CONFIG_SHELL and SHELL contain absolute pathnames, eg. `/bin/bash' not just `bash'. - We have seen configure produce strange results due to bad versions of sed (ie. that come with early FreeBSD). In particular, configure did not parse command line options correctly (saying they weren't valid). If you have this problem, try GNU sed. - If you get syntax errors from "make", then try using GNU make. - Especially if you have other versions of Tcl on your system already, for this build it is probably best to not have it in your PATH or to have anything in LD_LIBRARY_PATH (or equivalent) that points to the other Tcl stuff. - Configure loops forever: you are missing a subdirectory that configure expects to be there. Install the directory or modify configure.in and run autoconf. * Bash and GNU make may be obtained from prep.ai.mit.edu or a mirror of same. RUNTIME: Okay, you now have a zillion commands in your $prefix/bin directory. On some systems that support shared libraries, you may have to set LD_LIBRARY_PATH (or your equivalent) to point to the directory containing the shared libraries. We have modified the install scripts to install an entry into pkgIndex.tcl for each shared library in the system. Once you have set LD_LIBRARY_PATH (if needed), you should be able to run any of the basic interpreters, such as "ish", and type "package require Neo" for example. Here is a list of all of the package names that can be given to "package require" as built within this distribution: Dp Itcl Itk Iwidgets Expect Neo Gd Tkx Tk Tclx Tcl For scripts, there are several approaches to take to get an interpreter with suitable capabilities: 1. Choose the nearest binary: dpwish expect expectk ish itclsh itkwish neotcl tcl wishx and point your script's #! line to it. Then do "package require" commands for the rest of the features you need. 2. Choose a single binary to use and "package require" everything you need. More and more you will probably see packages that do not install their own binary, but just a shared library. 3. We note that some DES encryption libraries are not distributed as a shared library. Nor at this time do we build a shared DB library (the changes to do this will appear in a future release). If you need these, you may best start with "neotcl" binary, and "package require" from there. 4. It is possible to modify the main init.tcl script to detect the executable's name ([info nameofexecutable]) and perform various package require commands based on this. Thus, wishx should be replaced with a symbolic link to neotcl, and then init.tcl could make it appear the same by doing if [cequal [info nameofexecutable] wishx] {package require Tkx} Randy Kunkee NeoSoft, Inc. Houston, TX USA itcl2.2/ITCL.CHANGES100666 1751 0 221205 6423554631 12633 0ustar kunkeewheel [incr Tcl] - CHANGE LOG ========================================================================== ----------------------- CHANGES FROM itcl-1.5 -------------------------- ========================================================================== Release itcl-2.0 provides a new syntax for defining classes. The new syntax is accessed using the new "itcl::class" command. For the time being, the old syntax will be supported via the old "itcl_class" command, but support for this will be phased out over time. Because both syntaxes are supported, the new version is "backward compatible" with the previous itcl-1.5 release. However, there are some semantic changes that may break existing scripts. These are listed in detail in the section "INCOMPATIBLE CHANGES". CATALOG OF NEW COMMANDS -------------------------------------------------------------------------- Following is a brief catalog of new commands available in this release. == Tcl with Namespaces ================================================= delete namespace name ?name...? Deletes one or more namespaces, destroying all commands, variables, and child namespaces within it. ensemble name { option optName arglist body option optName arglist body ... ensemble optName { option subOptName arglist body option subOptName arglist body ... } } Adds options to an ensemble called "name". If the ensemble does not already exist, it is created automatically. An "ensemble" is a toplevel command that groups a collection of sub-commands. For example, the usual Tcl "info" command is an ensemble with options like "globals", "level", "tclversion", etc. Ensembles are good for two reasons. First, new options can be integrated in without modifying any source code or "switch" statements. For example, [incr Tcl] adds the "info classes" and "info objects" commands simply by adding options to the "info" ensemble. Second, error messages are generated automatically by the ensemble mechanism. Try invoking "info" with no options and see the result. Each option declaration is just like a Tcl proc declaration, with an option name, arglist and body. Ensembles can also contain sub-ensembles with more options. import add name ?name...? ?-where pos...? import all ?name? import list ?importList? import remove name ?name...? Used to manipulate the "import" list for the current namespace. When one namespace imports another, it gains access to all of its public commands/variables as if they were part of the same namespace. In other words, one namespace can be integrated seamlessly into another by adding it to the import list of the other namespace. By default, each namespace imports its parent, so most namespaces import the global scope in some fashion. The form "import list" is used to query or set the import list for the current namespace. The form "import all" returns the namespace search path that is consulted when commands/variables are accessed. info context Returns the current namespace context. The global namespace context is reported here as "", so it is easy to build namespace paths like this: set path "[info context]::name" info namespace all ?pattern? Returns a list of namespaces found in the current namespace context, whose names match an optional string pattern. This includes children of the current namespace, and children of all imported namespaces. info namespace children ?name? Returns a list of child namespaces for namespace "name", or for the current namespace if "name" is not specified. info namespace parent ?name? Returns the parent namespace for namespace "name", or for the current namespace if "name" is not specified. info namespace qualifiers string Parses a string of the form "namesp::namesp::name", and returns the leading "namesp::namesp" scope qualifiers. info namespace tail string Parses a string of the form "namesp::namesp::name", and returns the trailing "name" element. info protection ?-command? ?-variable? name Returns the protection level for an element. By default, "name" is treated as a command name, but the "-command" or "-variable" flags can be used to request a specific treatment. info which ?-command? ?-variable? ?-namespace? name Reports the full namespace path (e.g., "::namesp::namesp::name") for an element. By default, "name" is treated as a command name, but the "-command", "-variable" and "-namespace" flags can be used to request a specific treatment. namespace name ?-local? ?-enforced val? ?--? ?commands? This is the usual mechanism for creating a namespace and defining elements within it. If namespace "name" does not exist, it is created automatically. The namespace name may include a full namespace path (e.g., "namesp::namesp::namesp"). During the search for this namespace, all imported namespaces are consulted. If the "-local" flag is specified, then the search is restricted to the local namespace; this prevents against accidentally importing a namespace if the intent is to create a child namespace. If the "-enforced" flag is specified, then "val" is treated as a boolean value; if true, then command/variable enforcement is turned on for this namespace. Each time a new command is referenced within the namespace, Tcl automatically calls a procedure: enforce_cmd with the of the command that is about to be executed. The "enforce_cmd" proc can return an error, and access to that command will be denied. It can return another command name, or a more specific namespace path, and that command will be used instead. Or it can return "", and command lookup will continue via the normal namespace rules (i.e., in local scope, imported namespaces, etc.). Each time a new variable is referenced within an enforced namespace, Tcl automatically calls a procedure: enforce_var with the of a global variable that is being referenced. The "enforce_var" proc can return an error, and access to that variable will be denied. It can return another variable name, or a more specific namespace path, and that variable will be used instead. Or it can return "", and variable lookup will continue via the normal namespace rules (i.e., in local scope, imported namespaces, etc.). Note that command/variable enforcement done at the Tcl language level can be slow. There is also a C language interface for the same functionality, which offers much better performance. The namespace is first found and updated with whatever flags were specified. After that, if a "commands" string was specified, it is executed in the context of the namespace. public command ?arg arg...? protected command ?arg arg...? private command ?arg arg...? These commands attach a particular protection level to whatever commands or variables are created while executing the specified command. They are used in conjunction with commands like "proc" and "variable" to create public/protected/private elements. scope string code ?-namespace name? command ?arg arg ...? @scope namespace value The "scope" command takes a string and encodes it into an "@scope" declaration. The "code" command performs a similar function, but accepts multiple arguments and is usually used to wrap up code fragments. The "@scope" declaration keeps a value (like a variable name or code fragment) together with its context namespace. It can be executed like an ordinary command: set cmd {@scope :: puts} $cmd "hello world!" or used as an ordinary variable name: set var {@scope :: auto_path} lappend $var /usr/local/mylib The difference, however, is that an "@scope" value bypasses the usual access protections and guarantees that values have the proper scope. Ordinary variable names refer to variables in the global namespace. Ordinary code fragments are usually interpreted by extensions like Tk in the global namespace. The "scope" and "code" commands are used to wrap up variable names and code fragments to preserve the namespace context. For example: namespace foo { private variable state 0 private proc show_state {mesg} { global state puts "$mesg: $state" } checkbutton .cb -text "Toggle" \ -variable [scope state] \ -command [code show_state "current state"] pack .cb } In this example, the checkbutton is tied to the variable "foo::state" and executes the command "foo::show_state" whenever it is pressed. When a Tk widget uses commands and variables within a namespace, these names should be wrapped up as scoped values, as shown above. variable name ?value? Creates a variable called "name" and initializes it to an optional value. This is normally used in conjunction with public, protected and private commands to declare variables within a namespace: namespace foo { public variable x 0 private variable y 1 } If the variable "name" already exists, it updated to have the protection level that is currently active. == Tk with Namespaces ================================================== bind... Recognizes and expands the following fields within command strings: %q => Replaced with the fully-qualified access command for the widget receiving the event. For example, namespace foo { namespace bar { button .b -text "Hello World!" } } The fully-qualified access command for this widget is "::foo::bar::.b". The "%q" field should be used instead of "%W" as the widget access command: bind Button "%q flash; %q invoke" %M => Replaced with the window path name of the mega-widget containing the window receiving the event. For example, if an "entryfield" mega-widget ".x" contains an entry widget ".x.entry", bindings added to ".x.entry" will replace "%M" with ".x". This allows generic bindings to be added to component widgets which affect the mega-widget as a whole. For this to work properly, mega-widget packages must register their component widgets using Itk_SetMegaWidget(). winfo command window Returns the fully-qualified access command for the widget "window". This is equivalent to the "%q" field in bindings, and is useful in procedures where the only the window name is known: foreach kid [winfo children $win] { [winfo command $kid] configure -bg blue } winfo megawidget window Returns the window path name of the mega-widget containing "window" as a component. This is equivalent to the "%M" field in bindings, and is useful in procedures where only the component window name is known. For this to work properly, mega-widget packages must register their component widgets using Itk_SetMegaWidget(). == [incr Tcl] ========================================================== delete class name ?name...? Deletes one or more object classes. Deleting a class also causes all derived classes, and all objects belonging to the class, to be deleted as well. delete object name ?name...? Deletes one or more objects. If the access command for an object resides in another namespace, then the full namespace path should be used: delete object foo::bar::x info classes ?pattern? Returns a list of all classes in the current namespace whose names match an optional string pattern. info objects ?-class className? ?-isa className? ?pattern? Returns a list of all objects whose names match an optional string pattern. If the "-class" option is specified, then the list is further restricted to those objects whose most-specific class is "className". If the "-isa" option is specified, then the list is further restricted to those objects who belong to class "className". itcl::class name { definition } Used to create define a new class "name". The "definition" commands include: inherit baseClass ?baseClass...? constructor arglist ?init? body destructor body method name ?arglist? ?body? proc name ?arglist? ?body? variable name ?init? ?config? common name ?init? public command ?arg arg...? protected command ?arg arg...? private command ?arg arg...? Note that the constructor statement has changed to include an optional "init" argument. This is an initialization statement that can be used to call out base class constructors. If it is not included, base classes are constructors are invoked automatically without any arguments. The "variable" statement is now used to create object-specific data members. The "common" statement is used to create "common" variables, which are global within the class namespace. Both types of variables can be designated public, protected or private. itcl::body class::func arglist body Used to define the body of a class member function outside of the class definition. If "body" declarations are kept in a separate file, they can be sourced again and again to test changes as bugs are fixed. If an "arglist" is specified in the class definition, then the "arglist" for the body definition must have the same meaning. itcl::configbody class::option body Similar to the "body" command, but used to define the configuration code for a public variable. itcl_class name { old-style-definition } \__ backward compatibility itcl_info option ?arg arg...? / == [incr Tk] =========================================================== itcl::class name { ... itk_option define -switch resName resClass initVal ?configCode? } The "itk_option define" command is recognized at the level of the class definition. It defines a new mega-widget option with the given switch name and X11 resource database names. The "initVal" is used as a last resort to initialize the option if no other value can be queried from the X11 resource database. If "configCode" is specified, it is executed whenever the option is modified via the "configure" method. The "configCode" can also be specified outside of the class definition via the "itcl::configbody" command. Methods provided by itk::Archetype base class: component component name component name command ?arg arg...? Used to query or access components within a mega-widget. With no arguments, this returns a list of component widgets that are accessible in the current scope. Note that component widgets obey any public/protected/private access restriction that is in force when the component is created. With one argument, this returns the window path name for a component with the symbolic name "name". In any other case, the remaining arguments are invoked as a method on the component with the symbolic name "name". configure configure option configure option value ?-switch value...? Works just like the usual Tk configure method, but for mega-widgets. Here options are really composite widget options. When set, they trigger changes to many different internal components, and may invoke many bits of "configCode" for options defined by "itk_option define". However, there is only one value for the composite option. cget option Works just like the usual Tk cget method, but for mega-widgets. Returns the current value for a composite widget option. itk_component add name {create-commands} ?{option-commands}? Adds a new mega-widget component with the symbolic name "name". Invokes the "create-commands" to create the component, and invokes "option-commands" to integrate its options into the composite list. By default, no options are integrated. Options may be added using the following commands: keep option ?option...? ignore option ?option...? rename oldswitch newswitch resname resclass usual ?tag? itk_component delete name ?name...? Deletes an existing mega-widget component with the symbolic name "name". The component will still exist as a widget, but it will no longer be accessible as a component for this mega-widget. Any options associated with the component are removed from the composite list. Note that you can destroy a component like any ordinary widget: destroy .foo.bar.b Components automatically detach themselves from their mega-widget parent when destroyed, so "itk_component delete" is not used very often. itk_option add option ?option...? \__ class::option itk_option remove option ?option...? / component.option Adds or removes an option from the composite option list for a mega-widget. These commands cannot be used at the level of the class definition; they must be invoked for a particular mega-widget. They usually appear in the constructor for a mega-widget class, to add or redefine options in components created by a base class. For example, the base classes itk::Toplevel and itk::Widget keep only the bare minimum options for their "hull" component: -background and -cursor. If you want your mega-widget to have a border around it, you can add the hull options back in: itcl::class MyWidget { inherit itk::Widget constructor {args} { itk_option add hull.borderwidth hull.relief } } itk_initialize ?option value option value...? Initializes the composite option list for a mega-widget. This method should be invoked within the constructor for each mega-widget class. It is usually included the end of the constructor, below the component creation code. It integrates all "itk_option" options defined in the current class into the composite configuration list, and includes "-option value" settings usually received as arguments to the constructor. When this is executed in the most-specific class, it scans through the composite option list and makes sure that all options have been properly initialized. itk::usual tag ?commands? Used outside of a mega-widget class definition to declare the "usual" option-handling commands for the mega-widget. These commands suggest how the configuration options should be handled if the mega-widget becomes a component of an even larger mega-widget. They include commands like "keep" and "rename". INCOMPATIBLE CHANGES -------------------------------------------------------------------------- >> Object construction/destruction now follows C++ model. In the previous release, object construction started at the most-specific constructor. Base class constructors could be called out explicitly within the body of a constructor. If they were not, they were invoked implicitly when the constructor finished executing. This led to a construction model that was backward from C++, and contrary to what most people expected. Destructors were backwards in a similar manner. In the current release, object construction starts at the least-specific class in the hierarchy, and proceeds to the most-specific class. Therefore, each base class is fully constructed before the derived class constructor is executed. Arguments are now passed to base class constructors through an optional "initialization" statement. This statement is included between the argument list and the body of the constructor, so the syntax is reminiscent of C++: class Base { constructor {x y} { ...constructor body... } } class Derived { inherit Base constructor {x y z} { Base::constructor $x $y << "initialization" } { ...constructor body... } } Note that variables from the argument list (e.g., $x and $y) can be referenced within the initialization statement. With multiple inheritance, each of the base class constructors can be called out individually. Object destruction is the exact opposite of construction. It proceeds from most-specific to least-specific class. >> All class methods are now implicitly virtual In the previous release, all method names were interpreted with respect to the current class scope and its base classes. If you wanted a method to act virtual, you had to explicitly preface it with the "virtual" command each time you used it. This proved to be error prone. In the new release, all methods are virtual by default. If you invoke a method with a simple name, the most-specific method with that name will be invoked, regardless of your class scope: class Base { constructor {} {show} method show {} {puts "Base::show"} } class Derived { inherit Base constructor {} {show} method show {} {puts "Derived::show"} } The method "show" called out in the constructors for both of these classes is virtual. When Base::constructor is executed it finds the most-specific "show" method and prints "Derived::show". When Derived::constructor is executed, it finds the most-specific "show" method and prints "Derived::show" again. If you want to invoke a particular method, you have to scope it explicity: class Base { constructor {} {Base::show} method show {} {puts "Base::show"} } class Derived { inherit Base constructor {} {Derived::show} method show {} {puts "Derived::show"} } >> Within class methods/procs the "global" command now refers to variables within the class namespace. In the previous release, the "global" command was used to access variables at the global scope. The "global" command now refers to variables that are "global" within the current namespace context. Within the scope of a class, this refers to "global" class variables. Note that common data members are global variables, but they can be accessed transparently, without any special "global" declaration. You can also create ordinary global variables within a class, but you will have to declare them each time they are used with a "global" statement. The new scheme will allow classes to have their own private global variables (e.g., for interacting with widgets) without flooding the global namespace. If you really want to access a variable at the "::" global scope, use its complete path name: itcl::class Foo { method getenv {name} { global ::env return $env($name) } } >> "this" variable used to be included in every class scope In the previous release, each class scope included a separate "this" variable containing the object name. There is now only one "this" variable, kept in the most-specific class scope. It can still be referenced as if it belongs to all classes, e.g., "Base::this", "Derived::this". This change is probably not important to most applications. But it did break my test suite, which expected to find many different "this" variables coming back from the "info" command. >> "this" variable now contains complete namespace path for the object access command This change will break many scripts written for mega-widgets. In the previous release, mega-widgets had a window name and an access command name that were interchangeable. For example, you would create a widget ".dialog" and configure it using the ".dialog" command. Inside of this widget there was a "this" variable containing the name ".dialog". In the current release, an object can exist in any namespace, so the complete namespace path is a part of the object's identity. Instead of just ".dialog", the "this" variable will now contain a name like "::.dialog" or "::foo::.dialog". But the window name is still just ".dialog". Scripts that used to use "$this" as a window name: wm title $this "Dialog" must now use the [incr Tk] "hull" component instead: wm title $itk_component(hull) "Dialog" If for some other reason you need the simple object name at the end of the namespace path, you can get at it using the "info namespace tail" command: set oldthis [info namespace tail $this] >> "#auto" generated names now start with lower-case letter In the previous release, "#auto" could be used in place of an object name to produce an automatically generated name: Toaster #auto -heat light The names were generated by adding a unique number onto the class name: "Toaster0", "Toaster1", etc. The current release supports the same functionality, except that the names generated are guaranteed to start with a lowercase letter: "toaster0", "toaster1", etc. This helps out in the mega-widget arena, where window names must start with lowercase letters. >> "config" argument used to allow multiple default values The magic "config" argument used to allow multiple default values, which were simply concatenated into a single value before processing. For example, in the previous release you could say: itcl_class Foo { method test {x y {config -foo 0 -bar 0}} { ... } } and if the "test" method was used without extra configuration arguments, they would default to "-foo 0 -bar 0". In the current release, you must make the default value for a "config" argument a single string: itcl::class Foo { method test {x y {config "-foo 0 -bar 0"}} { ... } } >> "info class" now acts "virtual" In the previous release, the "info class" command would report the current class context. In a base class method, it would report the base class name, and in a derived class method, it would report the derived class name. If you wanted to know the most-specific class for an object, you would have to use the "virtual" command explicitly: itcl_class Base { method whatAmI {} { return [virtual info class] } } The "info" command is now virtual by default, as long as an object context is present. This means that you can drop the "virtual" command: itcl::class Base { method whatAmI {} { return [info class] } } If you really want to know the current class scope, use the "info context" command instead to query the current namespace context. If an object context is not present (i.e., in the body of a common class "proc"), the "info class" command reverts to the current class context, the same as the "info context" command. >> Library procedures "itcl_unload" and "itcl_reload" have been removed In the previous release, the library procedure "itcl_unload" provided a way of deleting a class. You can now do the same thing using the "delete class" command: delete class Toaster This deletes the specified class, all derived classes, and all objects belonging to this class. If autoloading is set up, you can reload a deleted class just by invoking its name. The old "itcl_reload" function is now trivial: proc itcl_reload {class} { delete class $class $class } >> Class definition no longer recognizes ordinary Tcl commands. As an undocumented "feature" of the previous release, you could include ordinary Tcl commands in the body of your class definition. For example: itcl_class Foo { ... if {$somevar} { public foo } } In the new release, only class definition commands are allowed within the body of a class definition. You can, however, use Tcl commands outside of the class definition to modify the class definition as a string, and then define the class: set defn { method test {} {return "test"} } if {$somevar} { append defn "public variable foo" } class Foo $defn IMPROVEMENTS -------------------------------------------------------------------------- >> an object can be renamed by renaming its access command In the previous release, an object's identity was fixed when it was created. In the new release, the object is tied directly to its access command. If you rename the access command, you have renamed the object. The "this" variable automatically keeps in sync with name changes. If you delete the access command, you automatically delete the object. Toaster new -heat light rename new fred << rename Toaster fred toast 2 fred toast 1 rename fred "" << delete Toaster >> Bodies of methods, procs and public variables can be defined outside of the class definition, and can be redefined on the fly. In the previous release, all of the code related to a class was defined within the class definition. This kept everything together in one place, but it made it difficult to get an overview of the class interface. In the new release, bodies can be defined outside of the class definition, perhaps in a separate file. When debugging, the implementations can be fixed and sourced again and again, without having to delete existing objects and classes. Use the "itcl::body" command to redefine the body of a class method or proc. Use "itcl::configbody" to redefine the configuration code associated with a public variable. For example: itcl::class Toaster { constructor {args} { eval configure $args } destructor { if {$crumbs > 0} { error "cannot destroy dirty toaster: clean first" } } method toast {nslices} method clean {} public variable heat 3 protected variable crumbs 0 } itcl::body Toaster::toast {nslices} { if {$nslices < 1 || $nslices > 2} { error "bad number of slices: should be 1 or 2" } set crumbs [expr $crumbs+$heat*$nslices] if {$crumbs >= 50} { puts stderr "== FIRE! FIRE! ==" } } itcl::body Toaster::clean {} { set crumbs 0 } itcl::configbody Toaster::heat { if {$heat < 1 || $heat > 5} { error "invalid setting \"$heat\": should be 1-5" } } If an argument list is specified in the class definition, then the same argument list must be used when the implementation is redefined. The variable names can change, but the meaning of the arguments must be the same. If you leave the argument list out of the class definition, or if you include the "args" argument, the argument list can change. >> C procedures can be integrated into class definitions Any method body that is specified as "@symbol" is treated as a reference to a C procedure with the symbolic name "symbol". Symbolic names are established by registering C procedures via the Itcl_RegisterC() procedure. This is usually done when the interpreter starts up in the Tcl_AppInit() procedure: if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) { return TCL_ERROR; } This registers a procedure My_FooCmd() with the symbolic name "foo". It can be used as the implementation for a class method, proc, or bit of configuration code simply by specifying "@foo" in place of the Tcl code body. These C procedures are just like ordinary Tcl command handlers. They take the usual arguments: int My_FooCmd(ClientData cdata, Tcl_Interp *interp, int argc, char** argv) { ... return TCL_OK; } including the (argc,argv) arguments from the command line. But before these procedures are invoked, the proper class scope is established so that object data members can be accessed as if they were ordinary variables via Tcl_GetVar() and Tcl_SetVar(). Look at the [incr Tk] base class itk::Archetype as an example for integrating C code. >> "#auto" can be buried within an object name: ".x.y.z.#auto" In the previous release, "#auto" was a keyword that could be used in place of an object name. It can now be used as a part of the object name, making it easier to generate automatic names for mega-widgets. >> Every object now has built-in "configure" and "cget" methods that follow the Tk paradigm. For [incr Tk] widgets, they follow the paradigm exactly. The ordinary [incr Tcl] objects, the X11 resource values are missing. >> There is no longer a built-in "delete" method, so classes can define their own "delete" operations. Instead of "objName delete", use the new "delete object" command: Toaster fred -heat dark delete object fred >> All data members can be declared public, protected or private. Private data members can only be accessed in the class where they are defined. Protected data members can be accessed in the defining class and all derived classes. Public data members can be accessed like protected data members, but are also recognized as configuration options by the built-in "configure" and "cget" methods. >> In [incr Tk], options are now defined outside of the constructor, at the level of the class definition. >> In [incr Tk], configuration options belonging to components created in a base class can be added or removed in derived classes. The base classes "itk::Toplevel" and "itk::Widget" are now stripped down to the bare minimum options. For example, if you want to add "-width" and "-height" options for the hull component, do this using the "itk_option" command in the body of the constructor: class MyWidget { inherit itk::Widget constructor {args} { itk_option add hull.widget hull.height ... } } Options can be added and removed on-the-fly during normal operation, but this is not recommended, since it could lead to a confusing interface. >> In [incr Tk], components can now be added or removed on-the-fly. The "itk_component" method now supports "add" and "delete" operations that are used to add/delete components. >> All [incr Tk] widgets can be destroyed like normal Tk widgets. If you destroy a component widget, for example, it will automatically remove itself from its parent via "itk_component delete". Likewise, when a parent widget is destroyed, it will automatically destroy all component widgets. >> In [incr Tk], the "itk::Archetype::component" method now provides access to mega-widget components. In the previous [incr Tk] prototype, the "component" method had a different syntax and only supported query operations. You can now access an internal component via the "component" method using its symbolic name: .dialog component hull configure -width 450 -height 500 This example accesses the "hull" component of the ".dialog" mega-widget, and sets the width and height options. ========================================================================== ---------------------- RELEASE 2.0beta - 9/6/95 ------------------------ ========================================================================== 9/8/95 (bug fix) Fixed menus to work properly within namespaces. Menu library code now recognizes the proper namespace context for all "-menu" options. 9/8/95 (new feature) Added "winfo command name" option to report the scoped access command for a given window. 9/8/95 (configuration changes) - fixed "sed" invocation in iwidgets Makefile - added configuration guesses for Tadpole Sparcbook - added George Howlett's test for "gcc", so that "-fwritable-strings" is added even if gcc is masquerading as "cc" - fixed tcl/tk configure scripts to have default prefix "/usr/local/itcl" or wherever itclsh/itkwish is installed - fixed makefiles to use $(MAKE) instead of "make" 9/9/95 (bug fix) Protected references to obj->accessCmd to avoid seg faults when an object is being destroyed. 9/9/95 (new features) Changed the syntax of the "namespace" command: namespace name ?-local? ?-hidden val? ?-enforced val? ?--? ?commands? Flags now follow the namespace name, and the "commands" body is optional. The "-hidden" option allows a namespace to be hidden during "info namespace all" queries. The "-enforced" option turns command/variable enforcement on or off. Update "info namespaces all" command to allow for display of hidden namespaces: info namespaces all ?-hidden? ?pattern? 9/10/95 (bug fix) Fixed "auto_mkindex" to work properly for procs defined within namespaces. Added support for itcl::class, itcl::body and itcl::configbody as well. Added tests for tclIndex file generation. 9/11/95 (configuration changes) Fixed makefiles to reference sources and libraries properly, so it should be possible to build different object trees for different platforms with "gmake". 9/13/95 (configuration changes) Added "AC_C_CROSS" to configure files, so configuration should work properly on Solaris 2.4. 9/13/95 (bug fix) Changed option configuration to work synchronously, and added "itk_initialize" command to initialize the configuration options for each mega-widget class. The original behavior of handling option changes via "do-when-idle" has been removed. 9/13/95 (bug fix) Changed all structure members called "namespace" to "namesp". This allows the code to compile correctly under C++. 9/13/95 (configuration changes) - added support for "i[34]86:BSD/OS" in "config/config.guess" - fixed "test" target for iwidgets 9/13/95 (bug fix) Fixed "global" command and other places where namespace paths are parsed to allow for a single ":" in command/variable names. 9/13/95 (bug fix) Fixed a problem which caused class-based options to be lost when a widget class was defined within a proc. 9/14/95 (bug fix) Fixed class access command so that when it is deleted, it automatically destroys the class. This also fixed a seg fault that occurred when an object's access command stomped on the class access command. 9/14/95 (enhancement) Fixed "scope" command and the @scope facility so that null strings can be passed around without all of the extra scoping info. ========================================================================== ----------------------- RELEASE 2.0b2 - 9/14/95 ------------------------ ========================================================================== 9/15/95 (enhancement) Changed error messages reported when a class method/proc gets the wrong number of arguments to report the usage information, like: {wrong # args: should be "obj foo x y ?arg arg...?"} 9/18/95 (bug fix) Fixed a seg fault that occurred when the "cget" method was called with no args. 9/18/95 (bug fix) Fixed a bug that caused private variables in a base class to be uninitialized, even if an initial value was specified in the class definition. 9/22/95 (configuration changes) Added the "SHELL=/bin/sh" statement to the main makefile. This fixes build problems on SGI machines. 10/9/95 (paradigm shift) Removed the implicit scoping from any facility that takes a command or variable name. Implicit scoping made it difficult to pass a command string or variable name into a wrapper proc and yet preserve the scope that it came from. All scoping is now explicit. All commands and variables are interpreted in the global "::" scope unless they are wrapped in an "@scope" declaration. Commands can be wrapped up like this: button .b -text "Push Me" -command [code .b configure -bg red] Variable names can be wrapped up like this: radiobutton .rb1 -text "Choice #1" -variable [scope mode] -value 1 The "code" and "scope" commands wrap up strings with an "@scope" specification which preserves the namespace context. 10/17/95 (paradigm shift) Changed the "%C" option of the "bind" command to return a scoped command of the form "@scope namespace widget" that can be used to access the widget. "%C" should be used instead of the usual "%W" window name when attempting to access the widget. Bindings should be written like this: bind Entry {%C configure -bg white} bind Entry {%C configure -bg gray} The command "%C" can be used to access the widget regardless which namespace it belongs to. 10/31/95 (enhancement) Fixed "unknown" command to support a general facility for adding unknown command handlers. The "unknown_handler" proc is used to register new handlers. Each time an unknown command is encountered, each of the handlers is invoked to attempt to handle the command. If a handler returns "-code continue", control passes to the next handler on the list. Handlers are invoked in the order opposite to the way they were registered. Extensions can use this facility to add their own handlers into the "unknown" scheme. 11/7/95 (enhancement) Added a "backward-compatibility" mode to [incr Tcl]. By default, widget names can now be used as access commands in any namespace, even if the widget access command exists in another namespace. This emulates the normal Tk behavior that widgets are global resources in the application that can be accessed anywhere. This behavior can be disabled by setting the global variable "itcl_purist" to "1". When this variable is set non-zero, care must be used to use "%C" or "[winfo command %W]" as an access command when the widget is used outside of the namespace that contains it. From the standpoint of the object-oriented paradigm, the "purist" mode is better since it supports encapsulation. The "backward-compatible" mode, however, allows [incr Tcl] to work better with existing Tk applications and extensions. 11/22/95 (bug fix and enhancement) Fixed the built-in "info" command for classes to include the "info classes" and "info objects" queries. These were initially overlooked in a hard-wired list of "info" queries. Fixed the ensemble facility in general to support unknown options via an "@error" handler. Any option registered with the name "@error" is treated as an error handler for the ensemble. Arguments passed to the option include the ensemble name, the unknown option, and all remaining arguments. For the built-in "info" command, the "@error" handler passes any unknown options to the usual Tcl "info" command, so all of the standard options are automatically available. 11/23/95 (bug fix) Fixed usual tkerror dialog to truncate error messages at 5 lines. The usage information returned by an ensemble or itcl object can be much longer, causing the "Stack Trace" button to get lost in many cases. 11/27/95 (bug fix) Removed the constructor/destructor from the list of public methods returned as usage information when an unknown method is encountered on an object. 12/2/95 (bug fix) Fixed error reporting for object construction. Used to say something like "object constructor x y z" which made it look like a method invocation. Now says "class object x y z" which looks more like the call that the user made to trigger the error. 12/4/95 (bug fix) Fixed class creation and object creation to avoid clobbering existing commands with new class/object access commands. This prevents all hell from breaking loose when a command like "class set {...}" is invoked. 12/6/95 (configuration changes) Fixed parsing of namespace paths to use local storage instead of assuming that strings are writable. This means that the "-fwritable-strings" option is no longer necessary for GCC and other compilers that store static strings in the program text segment. This option has been removed from all "configure.in" files. Linux users will no longer see core dumps on start-up. 12/8/95 (bug fix) Fixed "upvar" so that class data members can be accessed from another calling procedure. This fixed a problem with using "parray" from within class methods. 12/9/95 (bug fix) Fixed "@scope" variable references so that variables can be created using "@scope" in any context and referenced later. 12/9/95 (feature change) Removed "-hidden" option from namespaces. It seemed to complicated and quirky to explain on the man page. Instead, all parser namespaces like "scope-parser" and "mkindex-parser" are grouped into a "::tcl" namespace. This keeps them somewhat hidden even without any special treatment. 12/9/95 (minor enhancement) Added "array" command to class definition parser, so it can be used along with "set" to initialize common arrays. 12/10/95 (paradigm shift) Removed the "%C" pattern from the expansions recognized by the "bind" command, in favor of the following scheme: %W ........ name of widget receiving event %M ........ name of mega-widget containing widget receiving event %q ........ fully-qualified command name of widget receiving event %Q ........ fully-qualified command name of mega-widget receiving event Fixed "winfo command" to return the fully-qualified command name of a widget (instead of a scoped access command) to be consistent with the "%q" bind pattern. 12/10/95 (bug fix) Fixed Tk library code to use "%q" and "winfo command", so that the default widget behaviors will work even in "itcl_purist" mode. 12/11/95 (minor enhancement) Added "winfo megawidget" query, which will return the name of the mega-widget containing a specified component widget. In order for this to work, a mega-widget package must use the procedure Itcl_SetMegaWidget() to register each component as it is added to a mega-widget. 12/12/95 (bug fix) Fixed Archetype base class to keep all options sorted in alphabetical order. This way they can be reported back by the "configure" method in alphabetical order. Options are now initialized by "itk_initialize" in alphabetical order as well. 12/12/95 (bug fix) Fixed the Archetype base class to register each component widget with Tk via Itk_SetMegaWidget(). This means that "winfo megawidget" and "%Q" can be used to reference the containing mega-widget for any component. 12/12/95 (bug fix) Fixed the "configure" method in the Archetype base class so that when an error is encountered while setting a configuration option, the option is set back to its previous value. 12/12/95 (bug fix) Fixed the "itk_component add" method to find access commands for components even if they are created in the global scope. Components that are meant to be shared can be created using "uplevel #0". The access command for this component will be installed in the global scope, and therefore available to all other namespaces. Syntactic sugar like a "-global" option would be nice, but references like $itk_component(...) must be substituted in the calling scope, and it is not possible to get these properly substituted and still maintain the boundaries around arguments. 12/12/95 (bug fix) Fixed Archetype base class to handle public/protected/private components properly. The usual public/protected/private commands can be used in conjunction with "itk_component add" to set the protection level of a component. The protection level affects the action of the "component" method. Public components are reported in any namespace, and are accessible from any namespace. Protected components are accessible within a base class and derived classes. Private components are accessible only within the class where they are defined. This feature can be used to keep unimportant components (such as frames) off of the component list that a client would see. 12/13/95 (enhancement) Added "usual" and "ignore" commands for processing component widget configuration options. The "usual" command finds the usual code fragment for the widget class of the component, and executes it. The command "itk::usual" can be used to register option code for new widget classes. The "ignore" command can be used to override previous "keep" and "rename" commands. This is useful for removing options that the "usual" code keeps or renames. Fixed the "itk_component add" command so that if the option handling code is not specified, the "usual" command is invoked automatically. 12/13/95 (bug fix) Fixed the Archetype base class to handle the immutable Tk options properly. Options like -class, -colormap, -screen and -visual can only be set at creation time. The itk_option array is now properly initialized to report their creation value. 12/14/95 (bug fix) Fixed "itk_option add" command to report errors properly for unknown options. 12/14/95 (bug fix) Fixed "body" command to report errors properly for unknown functions. 12/14/95 (bug fix) Fixed a bug in the handling of TCL_GLOBAL_ONLY flag when looking up class variables. Previously, this was ignored, so object-specific variables could be accessed in a "global" context by Tk widgets. This caused some strange behavior when object-specific variables were used in conjunction with widget options like "-textvariable". Tk widgets now properly interact with classes via global variables. 12/14/95 (bug fix) Fixed "auto_mkindex" to recognize procs within class definitions and add them to the "tclIndex" file. 12/15/95 (bug fix) Fixed "body" command to find functions only in the specified class. The bug caused a base class method to be redefined whenever a "body" command was issued for a derived class if the method was not declared in the derived class. Made a corresponding fix to the "configbody" command for public variables. 12/15/95 (enhancement) Added the following commands to the class definition parser: bind, scope and code. This allows generic class bindings to be included in the body of a class definition. 12/15/95 (enhancement) Added "-clientdata" option in itk::Archetype base class so that all widgets will have an extra field for client data. For application developers, this may come in handy. 12/16/95 (bug fix) Fixed the itk::Archetype base class so that if "itk_option add" or "itk_option remove" is called for ordinary class-based options before "itk_initialize" (which normally integrates them in) it does not cause a problem. 12/17/95 (bug fix) Fixed namespace resolution so that a command/variable with a specific path like "itk::body" will not be found in another imported namespace. For the import list to be followed, the command name must be generic like "body". 12/19/95 (configuration changes) Changed from generic directories like "tcl" and "tk" to directory names with version numbers like "tcl7.4" and "tk4.0". 12/19/95 (bug fix) Changed names like "itcl_library" and "itcl_purist" to "itcl::library" and "itcl::purist". This makes more sense in the documentation, since the underbar stuff is no longer needed with namespaces, and extension writers are discouraged from using it. 12/21/95 (bug fix) Changed handling of argument lists for functions with Tcl or C implementations. All argument lists are now treated as Tcl argument specifications. For Tcl implementations, this determines what arguments are available in the body of the procedure; for C implementations, this merely gives the intended usage information for the function (the C implementation may choose to ignore this and do something else). This fix makes it easier to override C implementations with Tcl procedure bodies. 12/25/95 (bug fix) Split the usual TCL_GLOBAL_ONLY flag into two meanings: TCL_GLOBAL_ONLY now means "a global variable in the global namespace", and ITCL_GLOBAL_VAR means "a global variable in the current namespace". This enhancement fixes Tk (and many other extensions) which request global variables. A plain variable name together with TCL_GLOBAL_ONLY is now interpreted as an ordinary Tcl global variable, so the behavior is backward-compatible. A scoped variable reference will work properly with namespaces. If extension writers get more ambitious, they can start using the ITCL_GLOBAL_VAR flag, which will make their extensions namespace-friendly. 12/26/95 (bug fix) Fixed "@scope" command so that extra arguments added at the end are kept as proper list elements when added to the command string. This makes sure that boundaries around Tcl words are not lost when the scoped command is interpreted. 12/28/95 (minor enhancement) Added "config" method to the Archetype base class as an alias for the usual "configure" method. Many Tk applications use "config" as an abbreviation for "configure", so this fix improves compatibility with other packages. 12/28/95 (bug fix) Fixed Itcl_SaveInterpState() and Itcl_RestoreInterpState() to properly save/restore the interp state even for commands like Tcl_SetCmd(), which are sloppy about setting the interpreter result. This fixed bad memory references that were encountered in enforced namespaces. 12/28/95 (bug fix) Fixed Itcl_DeleteNamesp() to allow variable traces to be fired off properly when a namespace is destroyed. 12/30/95 (bug fix) Fixed the Archetype base class to do the "ignore" operation properly for mega-widget options. A bug was causing a single "ignore" request not only to eliminate the desired option, but to eliminate options that were renamed to the "ignore" name as well. ========================================================================== ------------------------ RELEASE 2.0 - 12/31/95 ------------------------ ========================================================================== 1/2/96 (cleanup) Fixed some compiler warnings reported by Christopher Hylands (cxh@EECS.Berkeley.EDU) 1/4/96 (cleanup) Fixed the description of the last test in itk/tests/option.test. 1/4/96 (cleanup) Fixed code examples in man pages. Lines starting with "." now start with the null character "\&", to avoid errors with troff. 1/5/96 (bug fix) Fixed a bug in tkMenuUnpost. Popup menus associated with something other than a menubutton can now be unposted properly. 1/10/96 (bug fix) If an error occurs during construction, all destructors are now invoked--even if an error is encountered. All destructor errors are completely ignored. This fixed a core dump reported by Christopher Hylands (cxh@EECS.Berkeley.EDU). 2/5/96 (cleanup) Fixed memory leaks reported by Forest Rouse (rouse@flash.icemcfd.com). Also fixed a problem in Itcl_DeleteNamesp() with the way that the variable cache was destroyed. This caused a core dump on Solaris systems when a namespace was deleted. 2/8/96 (cleanup) Fixed itk tests to ignore any resources that the user might have on the desktop (e.g., *background: red) 2/11/96 (bug fix) Fixed auto_mkindex so that the "proc" command accepts arglist and body as optional arguments. Within class definitions, these parameters may not be specified. Also, fixed the "source" command so that it is ignored within the file being indexed. Otherwise, it brought in program elements that confused the index. 2/15/96 (bug fix) Fixed the unknown command to save errorInfo and restore it before invoking each handler. This fixed an irritating bug that caused the first error message to be lost as "tkerror" was autoloaded. 2/20/96 (bug fix) Fixed a bug in variable lookup that allowed private/protected variables to be set from outside the normal context. On initial lookup variables were being passed over, but since they did not appear to exist, they were being created. Variables are now protected from being set or redeclared from an improper context. 3/1/96 (enhancement) Changed namespaces to import from their parent in "protected" mode instead of "public" mode. This is a better default, since it emphasizes the strong relationship between a parent and a child. They can share variables that are hidden from anyone else. 3/5/96 (bug fix) Fixed the "info objects" to autoload any classes referenced by "-isa" or "-class" that are not yet defined. 3/12/96 (enhancement) Fixed class parser to recognize commands at the global scope. This makes it possible to embed normal Tcl commands like an "if" statement within a class definition. It also makes it easy to extend the class parser by defining procs in the ::itcl::parser namespace. 3/17/96 (enhancement) Fixed "usual" command so that with no arguments, it returns a list of all known tags. Each tag name can be used to query its associated code. 3/19/96 (enhancement) Fixed the "configure" method for mega-widgets to include public variables as configuration options. Normally, mega-widget classes use "itk_option define" to define configuration options. However, if a mega-widget includes an ordinary itcl class as a base class, it should provide access to the base class options. Public variables are now integrated into the composite option list by "itk_initialize". 4/2/96 (enhancement) Added a "chain" command to the built-ins available in each class. A command like "chain 1 2 3" invokes the next implementation of the current method/proc found looking up the inheritance hierarchy toward base classes. This can be used to invoke a base class method in a generic way, without hard-coding the base class name. 4/10/96 (bug fix) Fixed "configure" operation for mega-widgets. Previously, if an error was encountered during configuration, the value in itk_option was set back to the previous value, but some parts of the mega-widget might be left in a partially configured state. Now, if an error is encountered and the option is set back to its previous value, the change is propagated down to all parts, so the widget remains in a consistent state. 4/15/96 (bug fix) Fixed a bug reported by Karel Zuiderveld (karel.zuiderveld@cv.ruu.nl) related to virtual method selection in "itcl_methods.c". If for some reason a method name was not found in the virtual table, the table access caused a core dump. This is now fixed. 5/13/96 (bug fix) Fixed "itk_initialize" to recognize errors when executing the "config" code associated with configuration options. Any error immediately causes itk_initialize to abort, which usually aborts construction. 5/13/96 (bug fix) Fixed a bug in Itcl_SaveInterpState() and Itcl_RestoreInterpState() which caused error information to get lost during object construction when errors were encountered. The new iPtr->appendResult buffer was being ignored, and results in this buffer were getting lost. 6/1/96 (bug fix) Changed the internal Interp and TkWindow data structures so that all of the extra [incr Tcl] data members are at the bottom of the structure. This should prevent errors when modules that have been compiled against vanilla Tcl/Tk are dynamically loaded into [incr Tcl]. 6/12/96 (enhancement) Integrated changes for "itcl2.0+3" release by Karel Zuiderveld, Jan Nijtmans and Vince Darley. This added support for tcl7.5/tk4.1, dynamic loading, canvas improvements, and support for Macintosh environments. Many thanks to these guys for all of their hard work! 6/22/96 (installation) Changed the way things are installed: - the startup file "init.itcl" is now called "itcl.tcl" - the startup file "init.itk" is now called "itk.tcl" - libraries, include files and man pages are now installed under a special "itcl" directory to avoid conflicts with a vanilla Tcl/Tk installation. For example, if your --prefix is set to /usr/local, things would be installed as follows: /usr/local/bin ............ executables: ish = tclsh with namespaces iwish = wish with namespaces itclwish = tclsh with namespaces and classes itkwish = wish with namespaces and classes /usr/local/include/itcl ... include files /usr/local/lib/itcl ....... libraries /usr/local/man/itcl ....... manual pages 6/24/96 (bug fix) Fixed "itkwish" so that it requires the Iwidgets package automatically during initialization. For all other shells, you must specifically request Iwidgets with a statement like "package require Iwidgets" 6/26/96 (bug fix) Fixed Tk_CanvasTagsParseProc to avoid dumping core when an item is configured with a null tag string. 6/26/96 (bug fix) Fixed PolygonToPoint() in tkCanvPoly.c so that invisible polygons (with no outline and no fill) are still considered when picking the closest item. Without this fix, programs like the "floor plan" in the Tk widget demo will not work. 6/26/96 (bug fix) Fixed the [incr Widgets] "feedback" widget to do a full update on each step. Without this, changes appear from time to time, but the bar does not grow smoothly. 6/26/96 (bug fix) Fixed fileselectiondialog and fileselectionbox to update directory list properly when "-directory" option is configured. 6/28/96 (bug fix) Fixed "itk_option define" to properly preserve a "config" code body so that it can be released if it is redefined later. ========================================================================== ------------------------ RELEASE 2.1 - 6/28/96 ------------------------- ========================================================================== 7/22/96 (bug fix) Fixed C-level variable access so flags like ITCL_FIND_LOCAL_ONLY can be passed into Tcl_GetVar() and Tcl_SetVar(). 7/25/96 (bug fix) Fixed the "notebook" widget in the [incr Widgets] set. The "index" method now supports pattern matching and index names with spaces in them. 8/1/96 (bug fix) Fixed destructor invocation so that if an object is being destructed and you try to delete it again, it will report an error. 8/7/96 (bug fix) Fixed the "inherit" command to make sure all names are really valid classes. Previously, trying to inherit from a proc would dump core. 8/29/96 (enhancement) Integrated with itcl2.1+2 (tcl7.5p1/tk4.1p1). 9/1/96 (bug fix) Fixed the Itcl_RegisterC() procedure so that the same name can be registered more than once, as long as it has the same function pointer. 9/7/96 (bug fix) Fixed a bug in method access for protected methods. There was a problem when a base class defined a method, and a derived class overloaded the method, and the method was accessed from the base class namespace. Added function Itcl_CanAccessMethod() to check for overloaded methods and allow access accordingly. 9/13/96 (bug fix) Fixed the Itcl_RestoreInterpState() procedure so that the "errorCode" variable is restored properly. There was a problem when the error code contained a list of elements. 9/20/96 (bug fix) Fixed a bug in the way namespaces were deleted. The hash table of child namespaces was being traversed while elements within it were being deleted. This caused a core dump when you tried to exit the application with a command like "destroy .". 9/28/96 (bug fix) Fixed the way that errors are reported when a base class is constructed with the wrong arguments. Previously, the error message showed the object creation command like "wrong # args: should be Foo name val1 val2". Now, it shows the base class constructor name, so it is more obvious where the error is coming from. 10/5/96 (bug fix) Fixed a bug in constructor invocations. All base class constructors are now invoked properly, even if a derived class does not have a constructor. 10/9/96 (enhancement) Added proper support for safe interpreters. You can now use namespace commands in a safe interpreter, and you can load Itcl as a safe package. 10/11/96 (bug fix) Fixed a core dump with "namespace foo {info locals}". The namespace call frame was not being set up properly, so the local variable table was garbage. Normally, you don't access local variables at the namespace level. But now it is fixed. 10/14/96 (bug fix) Fixed the Itcl_RegisterC() procedure so that each interpreter has its own list of symbolic function names. This avoids global data and makes more sense for people using multiple interpreters. 10/20/96 (bug fix) Fixed variable lookup so that when you try to access a variable like "::foo::x" inside of a procedure, you get an error instead of a local variable named "::foo::x". Variables like this need to be declared global. 10/22/96 (enhancement) Fixed the built-in "isa" method to autoload class definitions as needed for each "isa" test. If a class is not defined and cannot be autoloaded, it is an error. 10/26/96 (enhancement) Fixed "delete object" command so that objects can be deleted using scoped values for the object name. 10/29/96 (enhancement) Integrated with itcl2.1+5 (tcl7.6/tk4.2). 11/1/96 (porting) Removed "plus" and "dash" patches to allow for porting to Windows95 and Macintosh platforms. Simplified configuration and makefiles for Unix platforms. 11/4/96 (installation) Fixed configuration and makefiles to support building in a separate directory. There is a bug in "autoconf" which prevents this from going smoothly. You have to copy all of the configure scripts to a separate tree (e.g., using a tar file), and then build. 11/5/96 (bug fix) Fixed a bug in the way variables were reported by the built-in "info" command for classes and objects. Private variables in a base class were incorrectly reported as "". They are now reported properly. 11/10/96 (bug fix) Fixed the "this" variable so that if an object is deleted while it is still in use, its name is properly reported as the null string. 11/10/96 (bug fix) Fixed the way namespaces are deleted so that the "::errorInfo" and "::errorCode" variables remain intact until everything else has been destroyed. These variables are needed if any errors are encountered as an interpreter is being destroyed. 11/11/96 (installation) Split the "itclConfig.sh" file into separate "itclConfig.sh" and "itkConfig.sh" files. 11/11/96 (installation) Fixed the package installation to conform to tcl7.6/tk4.2. The pkgIndex.tcl files are now stored in the library directory for each package. 11/13/96 (enhancement) Overhauled the scrolledcanvas widget. It is now about an order of magnitude faster. 11/14/96 (enhancement) Overhauled the [incr Widgets] "catalog" demo. When you pick any mega-widget class, the demo displays an example widget, the code used to build it, the class hierarchy, and the man page. 11/23/96 (bug fix) Fixed the way the "inherit" command autoloads class definitions. Previously, it invoked the class name as a command. Now, it uses the "auto_load" command. 11/23/96 (installation) Fixed the "configure" files to use "mkinstalldirs" instead of "mkdir" so that the entire distribution can be built in a separate directory starting with a single "configure" file. Fixed the way the distribution is created to make this patch for each new distribution. 11/23/96 (installation) Fixed the iwidgets installation so that the installed files (instead of the source files) are chmod'd to have the proper permissions. 11/29/96 (installation) Fixed iwidgets (combobox, optionmenu, shell) so that they don't rely on "tkwait visibility" before doing a grab. On the Macintosh, this only works the first time a window is mapped. After that, this command does not return control, even when a window is remapped. 11/30/96 (bug fix) Fixed "tk4.2/library/menu.tcl", moving a comment in a switch statement above the default case into the default case. When the comment is above the case, it is treated as a list element and a parsing error occurs. You can trigger the error with a command like "tkMenuFind . x". When the comment is inside the case, everything works fine. 11/30/96 (bug fix) Fixed a memory error that occured when an interpreter was destroyed. One namespace (e.g., base class) caused another (e.g., derived class) to be destroyed. Then the namespace was destroyed again later on. Now, as we iteration through the safeCopy list, we check to make sure the namespace still exists. 11/30/96 (bug fix) Fixed entryfield mega-widget to avoid using the "%s" state field for key presses. It was using it to find out whether or not Control, Shift, or Alt keys were being held down during a key press. But this field confuses Alt with NumLock when you go between Unix and Windows platforms. The entryfield appeared to be broken when NumLock was turned on. Nothing is lost if we simply ignore it and let all keypresses through. 12/1/96 (installation) Fixed the way that "pkgIndex.tcl" files are built for Itcl/Itk. When you build with "--enable-shared", the package files load the shared library, but when you build without, the package files use {load "" Itcl} to get the static package. This lets you do "package require" commands in slave interpreters, even if things were built with static packages. 12/1/96 (bug fix) Fixed how namespaces are deleted when an interpreter is deleted. Previously, namespaces were deleted after the assocData for the interp. If any background errors occurred while the namespace was being deleted, they caused seg faults later on. Now, the global namespace is cleared (but not deleted) *before* deleting the assocData. Any background errors are deleted, and the global namespace is finally deleted at that point. 12/2/96 (enhancement) JCI Defined "tkOpenDocument" in tk.tcl so that Macintosh users can double-click on an [incr Tcl] source file, and itkwish will be invoked to execute it. 12/2/96 (bug fix) Fixed the entryfield widget so that characters like: " [ ] { } \ & are substituted properly into the "%c" field when doing character validation. 12/2/96 (enhancement) **POTENTIAL INCOMPATIBILITY** Changed the HTML parsing in the scrolledhtml widget to speed it up. Also, changed the "-feedback" option so that it appends two numbers on the end of the feedback command: the current position and the maximum position. This frees the caller from having to figure out the maximum position. 12/2/96 (enhancement) Added "-borderwidth", "-relief" and "-elementborderwidth" options to the feedback widget, so you can control its appearance a little better. ========================================================================== ------------------------ RELEASE 2.2 - 12/3/96 ------------------------- ========================================================================== 12/12/96 (installation) Fixed "iwidgets.tcl" initialization file to rely on the environment variable IWIDGETS_LIBRARY (if it exists), and use the compiled-in path as a last resort. That way, the user can override the iwidgets library with an environment variable setting. 12/12/96 (installation) Fixed the "catalog" demo for [incr Widgets] to help support Windows3.1. The code is now arranged to make it easy to translate between the real demo names and DOS 8.3 file names. 12/13/96 (bug fix) Added a "usual" test for all of the [incr Widgets]. This checks to make sure that there is a bit of "usual" code for each widget, that the options in the "usual" code are valid, and that all of the widgets mix together without errors. 4/11/97 (enhancement) Merged in patches for tcl7.6p2/tk4.2p2 (jingham) 5/17/97 (bug fix) Fixed itk::Toplevel to have the hull keep the -takefocus option. This fixed a problem with the tab ring in iwidget dialogs. itcl2.2/ITCL.README100666 1751 0 45463 6423554631 12512 0ustar kunkeewheel------------------------------------------------------------------------ [incr Tcl] - version 2.2p2 ------------------------------------------------------------------------ This version includes tcl7.6p2 / tk4.2p2 upgraded to support namespaces, along with [incr Tk] and [incr Widgets]. Binary distributions for Windows95 and Macintosh platforms are available on our web site: http://www.tcltk.com/itcl/ Many different people have contributed code for this release, and I thank them for their contributions. Please read the acknowledgements section below. Send comments or suggestions to the [incr Tcl] mailing list (itcl@tcltk.com) or directly to me (mmclennan@lucent.com). If you want to subscribe to the mailing list, send a message with the subject "subscribe" to "itcl-request@tcltk.com". ======================================================================== Copyright (c) 1993-1997 Lucent Technologies, Inc. ======================================================================== OVERVIEW ------------------------------------------------------------------------ - What is [incr Tcl]? - Getting started - Installation - Integrating [incr Tcl] with other extensions - Acknowledgements ------------------------------------------------------------------------ What is [incr Tcl]? ------------------------------------------------------------------------ [incr Tcl] is an object-oriented extension of the Tcl language. It was created to support more structured programming in Tcl. Tcl scripts that grow beyond a few thousand lines become extremely difficult to maintain. This is because the building blocks of vanilla Tcl are procedures and global variables, and all of these building blocks must reside in a single global namespace. There is no support for protection or encapsulation. [incr Tcl] introduces the notion of objects. Each object is a bag of data with a set of procedures or "methods" that are used to manipulate it. Objects are organized into "classes" with identical characteristics, and classes can inherit functionality from one another. This object-oriented paradigm adds another level of organization on top of the basic variable/procedure elements, and the resulting code is easier to understand and maintain. Among other things, [incr Tcl] can be used to create new widgets that look and work like the usual Tk widgets, but are written entirely at the Tcl language level (C code is optional). These "mega-widgets" can be created using [incr Tk], a set of base classes which provide the core mega-widget functionality. [incr Widgets] is a set of high-level mega-widgets built using [incr Tk]. It has more than 35 widget classes, and can be used right out of the box to create: - fileselectiondialog - tabnotebook - panedwindow - scrolledhtml - combobox - optionmenu - scrolledlistbox - scrolledframe - messagedialog - and many others... Classes and/or related procedures can also be encapsulated in their own "namespace". A namespace is a collection of commands, variables, classes and other namespaces that is set apart from the usual global scope. Elements within a namespace can be "private" or "protected", so that access to them is restricted. An "import" command allows all of the elements from one namespace to be integrated into another. Extension writers will immediately see the benefit of namespaces. With vanilla Tcl, each extension must add its commands and variables at the global scope. Extension writers are encouraged to add a unique prefix to all of the names in their package, to avoid naming collisions. Extensions can now sit in their own namespace of commands and variables, and sensitive elements can be protected from accidental access. For example, the current release of [incr Tcl] has a namespace "itcl" for object-oriented support, a namespace "itk" for mega-widget support, and a namespace "iwidgets" for the [incr Widgets] package. Each of these namespaces has its own collection of commands and variables. Developers can then pick and choose among the extensions, and integrate the parts that they need for their application by importing various namespaces at the global scope. Getting started ------------------------------------------------------------------------ Read the first part of the CHANGES file for a brief overview of new commands, and a summary of important changes. Consult the man pages for detailed information on particular commands. Check out our web site on WebNet for the latest news: http://www.tcltk.com/itcl/ >> NOTE <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< >> << >> If you are just getting started with [incr Tcl], be sure << >> to download the TUTORIAL on our web site. This has over << >> 100 pages of introductory text and code examples. << >> << >> Also, run the "catalog" demo to get an overview of the << >> [incr Widgets] package. On Windows and Macintosh << >> systems, this is installed as one of the executables. << >> On Unix systems, this is installed in the << >> "lib/itcl/iwidgets2.2.0" library directory. << >> << >><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< The file "iwidgets2.2.0/doc/iwidgets.ps" contains a tutorial introduction to the [incr Widgets] package. The mega-widget classes in this package show off most of the functionality in this release. You can use them as a pattern to create your own widget classes. Installation on Unix Systems ------------------------------------------------------------------------ 1) Obtain this distribution from an archive site like this: ftp ftp.tcltk.com cd pub/itcl binary get itcl2.2p2.tar.gz quit 2) Uncompress and untar the distribution: gunzip itcl2.2p2.tar.gz tar xvf itcl2.2p2.tar 3) Run the configuration script: cd itcl2.2p2 ./configure or, for systems that don't recognize "#!" in shell scripts: cd itcl2.2p2 /bin/sh ./configure The "configure" script finds the appropriate compiler flags and generates new Makefiles from template files (Makefile.in). By default, the configuration script will set things up so that everything is installed in "/usr/local". You can change this by specifying a different "prefix" in the "configure" command: ./configure --prefix=/your/install/path By default, everything will be build with non-shared libraries. You can request shared libraries and dynamic loading like this: ./configure --enable-shared 4) Build the libraries and the executables. From the toplevel directory type: make all 5) Install the libraries, executables, man pages and script files. From the toplevel directory type: make install 6) Use the final product. This distribution creates and installs four executables: ish7.6 ........... [incr Tcl] sh (tclsh + namespaces) iwish4.2 ......... [incr Tcl] wish (wish + namespaces) itclsh2.2 ........ tclsh + namespaces + classes itkwish2.2 ....... wish + namespaces + classes + megawidgets If you configured this distribution with "--enabled-shared" to request dynamic loading, you can use "ish" or "iwish" as the core program and load everything else as needed. For example, you can start up "iwish" and load the [incr Widgets] package like this: unix$ iwish4.2 % package require Iwidgets This single command is enough to load Itcl2.2, Itk2.2 and Iwidgets2.2.0 dynamically. The interpreter will have all the commands needed to use the [incr Widgets] package. On some systems, you may get an error like: iwish4.2: can't load library 'libtcl7.6i.so' If you get this, it means that you need to include the "lib" directory containing the [incr Tcl] libraries in your LD_LIBRARY_PATH environment variable. You might add some lines like this to your ".cshrc" or ".profile" file: csh users: add something this to .cshrc setenv LD_LIBRARY_PATH "/usr/local/lib/itcl:$LD_LIBRARY_PATH" ksh users: add something this to .profile LD_LIBRARY_PATH="/usr/local/lib/itcl:$LD_LIBRARY_PATH" export LD_LIBRARY_PATH This assumes that the libraries were installed in the directory "/usr/local/lib/itcl". If you did not configure for dynamic loading, you will probably want to use the "itkwish2.2" program instead. This includes everything you need to use [incr Widgets], and you won't have to worry about LD_LIBRARY_PATH at all. Installation on Macintosh Systems ------------------------------------------------------------------------ The easiest way to use [incr Tcl] for Macintosh is to obtain the binary distribution at our website: http://www.tcltk.com/itcl or ftp://ftp.tcltk.com/pub/itcl/itcl2.2p2-68k.sit.hqx (68000 series) ftp://ftp.tcltk.com/pub/itcl/itcl2.2p2-ppc.sit.hqx (PowerPC) This solution will save you from having to compile [incr Tcl] and is recommended unless you need to alter the source code. But if you must build [incr Tcl] under MacOS, you can do so as follows. First, download the project files from our web site: http://www.tcltk.com/itcl or ftp://ftp.tcltk.com/pub/itcl/itcl2.2p2-macProjects.sit.hqx Store this file in the "itcl2.2p2" folder that contains the entire source distribution, at the same level as the "README" and "CHANGES" files. Then use the Stuffit expander to unpack it. Look for a folder called "Mac Projects", find the file called "README" within it, and follow the instructions in that file. Please report questions or problems you may have with the Macintosh version to: Michael McLennan Bell Labs Innovations for Lucent Technologies Installation on Windows 95, NT, and 3.1.x ------------------------------------------------------------------------ The easiest way to use [incr Tcl] for Windows is to obtain a binary distribution at our website: http://www.tcltk.com/itcl or ftp://ftp.tcltk.com/pub/itcl Windows95/NT: itcl2295.exe Windows3.1.x: itcl22w3.exe and w32s130.exe (Win32s) Windows 95/NT users should download the file itcl2295.exe. To install on Windows3.1.x machines, use the file itcl22w3.exe These files are self-extracting archives that will install the components necessary to run [incr Tcl] scripts. This solution will save you from having to compile [incr Tcl] and is recommended unless you need to alter the source code. To install [incr Tcl] on Windows3.1.x, you will need to first install Win32s on your machine. Win32s is a set of DLLs and a virtual device driver (VxD) that allows Win32-based applications to run on top of Windows or Windows for Workgroups. If you do not already have Win32s installed, you can obtain it from: ftp://ftp.tcltk.com/pub/itcl/w32s130.exe This file is a self-extracting archive. Run it in a convenient directory; it will decompress a number of files, including setup.exe. Run setup to finish installing Win32s. Compiling [incr Tcl] on Windows Machines ------------------------------------------------------------------------ If you must build [incr Tcl] under Windows, you can do so as follows. First, you will need one of the following compilers: Borland C++ 4.52 or later or Microsoft Visual C++ 4.0 or later (and Visual C++ 1.5.2 for Windows 3.1 support) Makefiles are provided for either of these compilers. Other compilers may work, but these are tested. 1) Obtain this distribution from an archive site like this: ftp ftp.tcltk.com cd pub/itcl binary get itcl2.2p2.tar.gz quit 2) Uncompress and untar the distribution: gzip -d itcl2.2p2.tar.gz tar xvf itcl2.2p2.tar 3) Set the Source and Target directories in the Makefile Makefiles are available for both the Borland and Microsoft compilers: makefile.bc -- Borland C++ makefile makefile.vc -- Microsoft Visual C++ makefile Edit the corresponding makefile in this directory to set these variables to their appropriate paths: e.g.: TARGET_ROOT = c:\Program Files\Itcl SOURCE_ROOT = c:\itcl2.2p2 TARGET_ROOT is the pathname to the directory where you would like the distribution installed. Several directories will be created here. SOURCE_ROOT is the absolute pathname of this directory. 3) Build the distribution The target 'dist' will build the entire distribution. In this directory, or one of the 'win' directories, type: Borland: make -fmakefile.bc dist Microsoft: nmake -fmakefile.vc dist 5) Install the distribution The target 'dist-all' will install the distribution to the TARGET_ROOT directory set in #2 above. In this directory, or one of the 'win' directories, type: Borland: make -fmakefile.bc dist-install Microsoft: nmake -fmakefile.vc dist-install 6) Use the final product. This distribution creates and installs four executables: ish.exe ........... [incr Tcl] sh (tclsh + namespaces) iwish.exe ......... [incr Tcl] wish (wish + namespaces) itclsh.exe ........ tclsh + namespaces + classes itkwish.exe ....... wish + namespaces + classes + megawidgets Please report questions or problems you may have with the Windows version to: Lee Bernhard Bell Labs Innovations for Lucent Technologies Integrating [incr Tcl] with other extensions ------------------------------------------------------------------------ [incr Tcl] now requires its own version of Tcl/Tk with support for namespaces. Therefore, you must use the version of Tcl/Tk that comes in this distribution as a basis for other applications. Hopefully, the namespace support will become a part of the standard distribution some day. You can add other extensions into the [incr Tcl] package by following the usual instructions for Tcl/Tk: 1) Put the source code for the extension in the directory "itcl2.2p2", at the same level as the directories "tcl7.6" and "tk4.2". 2) Copy "tclAppInit.c" or "tkAppInit.c" from the standard distribution. Choose the appropriate version according to your needs: tcl7.6/tclAppInit.c .... Tcl with namespaces tk4.2/tkAppInit.c ...... Tcl/Tk with namespaces itcl/tclAppInit.c ...... Tcl with namespaces and [incr Tcl] itk/tkAppInit.c ........ Tcl/Tk with namespaces and [incr Tcl]/[incr Tk] 3) Each extension should have an initialization function with a name like "XXX_Init()". The BLT package, for example, has a function "Blt_Init()". a) Include the declarations for any initialization routines at the top of the tclAppInit.c or tkAppInit.c file. b) Within the body of Tcl_AppInit(), add a call to the initialization routine. It should look something like this: if (Itcl_Init(interp) == TCL_ERROR) { return TCL_ERROR; } if (Itk_Init(interp) == TCL_ERROR) { return TCL_ERROR; } if (Blt_Init(interp) == TCL_ERROR) { return TCL_ERROR; } In this example we have integrated BLT in with [incr Tcl] and [incr Tk]. 4) Link your application with the appropriate libraries. For example, with non-shared libraries, you would link against: libtcl7.6i.a ............ Tcl with namespaces libtk4.2i.a ............. Tk with namespaces libitcl2.2.a ............ [incr Tcl] libitk2.2.a ............. [incr Tk] and on Unix systems, you will also need: -lX11 ................... X11 library Acknowledgements ------------------------------------------------------------------------ Thanks to Jim Ingham for integrating the patches for tcl7.6p2 and tk4.2p2, and for handling the Macintosh ports. Thanks to Lee Bernhard for handling the Windows 95/NT/3.1 ports. Thanks to Christopher Hylands and Steve Johnson for helping to test this release. Thanks to Karel Zuiderveld, Jan Nijtmans and Vince Darley for helping to keep up with Tcl/Tk releases, and for supporting the "plus" and "dash" patches under [incr Tcl]. Thanks to Mark Ulferts, Sue Yockey, John Sigler, Bill Scott, Alfredo Jahn, Tako Schotanus and Kris Raney for building the [incr Widgets] package. With a sketchy overview and a crappy prototype of [incr Tk], they managed to build a nice set of mega-widgets. Their initial designs helped me smooth out the rough spots in [incr Tk]. Thanks to Forest Rouse and ICEM CFD Engineering for integrating [incr Tcl] into their Tcl/Tk compiler. This is a large undertaking, and they have done an excellent job. Thanks to Alfredo Jahn and Bret Schuhmacher at WebNet for helping to create the [incr Tcl] web site, and for maintaining the [incr Tcl] mailing list. Thanks to extension writers like Mark Diekhans (tclX) and Ioi Lam (Tix) for making their packages compatible with [incr Tcl]. Thanks to George Howlett for teaching me how namespaces should really work. He has been a constant source of inspiration, and has kept a careful watch against many bad ideas. Jim Ingham fleshed out the notion of explicit scoping, and added many nice features to [incr Tk]. Bill Scott, with a steady stream of bug reports, helped me understand the questions that a typical user might have. He forced me to reinvent the paradigm on more than one occasion. Thanks to more than 100 beta-testers that helped me polish the itcl2.0 release. Thanks to Mark Harrison for his enthusiasm and support. Due in large part to his evangelism, I have been able to make [incr Tcl] development a mainstream activity. And many thanks to my wife Maria and my son Maxwell for putting up with all of this. --Michael ... --------------------------------------------------------- ':'...''. --- Michael J. McLennan 2C-226 mmclennan@lucent.com '::.''''':;: Lucent Technologies '::; ;;: 1247 S Cedar Crest Blvd :::,, :;; Allentown, PA 18103 Lucent Technologies ;:;' ;:; phone: 610-712-2842 Bell Labs Innovations ;;: .;: fax: 610-712-2773 :;:, ,:;: ':;;;:;:' itcl2.2/ITCL.TODO100666 1751 0 13711 6423554631 12311 0ustar kunkeewheel======================================================================= Following is a list of notes describing things which might be fixed or changed in a future release of [incr Tcl] ======================================================================= itcl "wish" list ------------------------------------------------------------------ - add virtual inheritance - add "border" type to canvas widget - add "validate" and "valid" commands for type validation - add "unknownvar" and provide access to object data members: "obj.var" - check namespace [info class] {...} as a replacement for "virtual" - fix "auto_load_all" problem in Tcl-DP (Their implementation uses "info commands" to verify that a command has been successfully autoloaded, but absolute command names like "::iwidgets::fileselectiondialog" don't show up.) - fix "auto_load" mechanism to be extensible like "unknown" - fix Itcl_RegisterC() to support ClientData - core dump with "cmdtrace" (tclX thing?) - ideas from Nelson Macy: - add "delegate" keyword for inheritance via composition? - add "forward" keyword for implementing error handlers - add "get" code to public variables for "cget" access - equivalent of constructor/destructor for classes - protected/private recognized for constructor/destructor - add something like Tk_CreateWidgetCommand() for widget developers itcl documentation cleanup ------------------------------------------------------------------ - add "Finance: Trading Systems" to commercial uses of Itcl (Deshaw) - update doc: "config" code also gets invoked on startup for itk widgets - update doc: add to FAQ: class with common array interacts with Tk widget itcl "to do" list ------------------------------------------------------------------ - write "auto_load_all" proc for Tcl-DP - bad errorInfo: > More specifically, the constructor for the class did the following: > > set hull [info namespace tail $this] > ::frame $hull > > One of the class variables had a configuration script: > > public variable textvariable "" { > if { $textvariable != "" } { > regsub "\\(.*\\)" $textvariable "" global > global ::$global > trace variable $textvariable w "$hull adjust" > } > } - add "@body" in as many places as possible to support Tcl compiler - check out itcl with Tix: lappend auto_path $env(TIX_LIBRARY) source "$env(IWIDGETS_LIBRARY)/init.iwidgets" iwidgets::Dialog ._Arcattributes -title "Code: Arc Annotations" -modality application set attrframe [._Arcattributes childsite] tixScrolledHList $attrframe.ports [$attrframe.ports subwidget hlist] configure -selectmode browse pack $attrframe.ports -expand yes -fill both -padx 10 -pady 10 ._Arcattributes activate ------------------------------------------------------------------ To: ig4!att!cas.org!lvirden (Larry W. Virden) (lvirden@cas.org) cc: michael.mclennan@att.com Subject: Re: Question concerning the Japanese patches for Tcl 7.4 In-reply-to: Your message of "Fri, 05 Jan 1996 06:43:46 EST." <9601051143.AA15368@cas.org> -------- Your message dated: Fri, 05 Jan 1996 06:43:46 EST > > The following instructions refer to the software which enables one to > build a KANJI supporting version of Tcl/Tk. Perhaps a note in the itcl > instructions letting folk know this package is also compatible would be > useful. > > > ----- Begin Included Message ----- > > >From nisinaka@sra.co.jp Thu Jan 4 00:09:52 1996 > Received: from srv07s4m by srv99dr.cas.org (5.65/CAS-1.23) > id AA29886; Thu, 4 Jan 1996 00:09:52 -0500 > Received: from srv01s4.cas.org by srv07s4m.cas.org (5.0/CAS-1.23) > id AA11865; Thu, 4 Jan 1996 00:09:50 +0500 > Received: from sraigw.sra.co.jp by srv01s4.cas.org (4.1/CAS-1.23) > id AA25691; Thu, 4 Jan 96 00:09:39 EST > Received: from sranhe.sra.co.jp by sraigw.sra.co.jp > (8.6.12+2.4W3/3.4W-2.1) > id OAA06131; Thu, 4 Jan 1996 14:09:32 +0900 > Received: from srashc.sra.co.jp (srashc [133.137.44.5]) by > sranhe.sra.co.jp (8.6.12+2.4W3/3.4W-srambox) with ESMTP id OAA00935; > Thu, 4 Jan 1996 14:06:26 +0900 > Received: from srashc.sra.co.jp (localhost [127.0.0.1]) by > srashc.sra.co.jp (8.6.12+2.4W3/3.4W-sra) with ESMTP id OAA25546; Thu, 4 > Jan 1996 14:09:30 +0900 > To: lvirden (Larry W. Virden, x2487) > Cc: tcl-jp-bugs@sra.co.jp > Reply-To: nisinaka@sra.co.jp > Subject: Re: Question concerning the Japanese patches for Tcl 7.4 > In-Reply-To: Your message of Tue, 02 Jan 1996 10:32:32 EST. > <9601021032.AA2226@cas.org> > Date: Thu, 04 Jan 1996 14:09:29 +0900 > Message-Id: <25544.820732169@srashc.sra.co.jp> > From: NISHINAKA Yoshiyuki > Status: RO > X-Lines: 31 > > > I notice that incr tcl 2.0 has been released with it's own, > customized, > > version of Tcl 7.4/Tk 4.0. Do any of you use itcl? If so, I > wondered if you > > had thought of constructing a specialized set of patches which could > be > > used with itcl. > > I have just got itcl2.0 and tried it with our Japanization > patches. Seems it works fine. > > What I really did was as follows: > > (1) Unpack itcl2.0.tar.gz. > > (2) Run `configure' at the directory `itcl2.0'. > > (3) Apply `tcl7.4p3jp-patch' at the directory `itcl2.0/tcl7.4'. > `Makefile.in.rej' was the only rejected file, so apply it > manually. > > (4) Apply `tk4.0p3jp-patch' at the directory `itcl2.0/tk4.0'. > There was no rejected file. > > (5) Make symbolic link from `tcl7.4' to `tcl7.4jp'. > > (6) Make all. > > > I haven't seriously tested yet though, `make test' was passed > and the Japanese translation of `demos/widgets' works fine. > > > Yosh Nishinaka (nisinaka@sra.co.jp) > > > ----- End Included Message ----- > > > -- > :s Larry W. Virden INET: lvirden@cas.org > :s <*> > :s Unless explicitly stated to the contrary, nothing in this posting should > :s be construed as representing my employer's opinions. itcl2.2/Makefile.in100666 1751 0 3747 6423554632 13125 0ustar kunkeewheel# # This file is the toplevel Makefile for [incr Tcl]. If it has the # name "Makefile.in" then it is a template for a Makefile; to generate # the actual Makefile, run "./configure", which is a configuration # script generated by the "autoconf" program (constructs like # "@foo@" will get replaced in the actual Makefile. # # RCS: $Id: Makefile.in,v 1.2 1997/10/20 08:56:59 kunkee Exp $ # Default top-level directories in which to install architecture- # specific files (exec_prefix) and machine-independent files such # as scripts (prefix). The values specified here may be overridden # at configure-time with the --exec-prefix and --prefix options # to the "configure" script. prefix = @prefix@ exec_prefix = @exec_prefix@ subdirs = @subdirs@ # Some versions of make, like SGI's, use the following variable to # determine which shell to use for executing commands: SHELL = /bin/sh all: for dir in $(subdirs) ; do \ (cd $$dir; $(MAKE) $@) \ done; test: for dir in $(subdirs) ; do \ (cd $$dir; $(MAKE) $@) \ done; static: for dir in $(subdirs) ; do \ (cd $$dir; $(MAKE) $@) \ done; standalone: for dir in $(subdirs) ; do \ (cd $$dir; $(MAKE) $@) \ done; plusplus: for dir in $(subdirs) ; do \ (cd $$dir; $(MAKE) $@) \ done; install: for dir in $(subdirs) ; do \ (cd $$dir; $(MAKE) $@) \ done; install-binaries: for dir in $(subdirs) ; do \ (cd $$dir; $(MAKE) $@) \ done; install-libraries: for dir in $(subdirs) ; do \ (cd $$dir; $(MAKE) $@) \ done; clean: for dir in $(subdirs) ; do \ (cd $$dir; $(MAKE) $@) \ done; distclean: rm -f Makefile config.log config.status config.cache for dir in $(subdirs) ; do \ (cd $$dir; $(MAKE) $@) \ done; # # Target to create a proper Tcl distribution from information in the # master source directory. DISTDIR must be defined to indicate where # to put the distribution. # configure: configure.in autoconf for dir in $(subdirs) ; do \ (cd $$dir; autoconf) \ done; # DO NOT DELETE THIS LINE -- make depend depends on it. itcl2.2/README100666 1751 0 12071 6423673002 11737 0ustar kunkeewheelNeoSoft Tcl Package Integration 1997 This is the NeoSoft (Houston, TX, USA) release of tcl7.6-based software. That last year alone has seen an incredible explosion of activity within the Tcl universe. NeoSoft has traditionally packaged Tcl with several extensions to produce a customized Tcl which it distributes and for which it sells commercial support. It is available from ftp://ftp.neosoft.com/pub/tcl/neosoft/neotcl/. It consists of the following packages integrated together: itcl2.2p2 (incl. tcl7.6, tk4.2, iwidgets2.2.0) tclX7.6.0 expect-5.25 dp4.0b1 gd1.2 (a graphics drawing library) neo7.6.0 (neosoft-authored tcl Extensions, also includes db.1.85) For more information on changes for this release, see the file RELEASE_NOTES in this directory. From the toplevel (itcl2.2) directory, it configures, builds and installs all of the above packages. We have tested the build on the following systems: Sparc Solaris 2.5 X86 Solaris 2.5 Linux-1.2.13 Adding other packages should be a relatively simple matter. Note the following general characteristics of NeoSoft integrated Tcl vs. Standard (I)Tcl: 1. Removed the "itcl" subdir that itcl2.2 installs itself into. While this might be strictly correct to do, it makes it necessary to integrate all other packages in the same manner. We choose instead to remove this feature. It makes adding other packages much simpler. 2. Written or extended configure scripts for tclX, expect, dp, and gd, including appropriate adjustments in Makefiles, adding or modifying install scripts, etc. You will find a new script in various places, called 'install-pkgindex', which will correctly slice out old information from the main pkgIndex.tcl file and replace it with the new pkgindex information. Also, while Dp's attempt at a graphical configuration and installtion interface is a noble (and interesting) attempt, we added in the stuff to allow an installation to be done normally (and thus be integrated with our release). 3. With help from Keith Bostic, created a configure script for db.1.85. This cleans up our installation a lot, since the Neo package supports Tcl extensions for talking to db file, and not all systems supply a useful db library. If you want to use your system-supplied libdb.a (or libdb.so) you may use the configure option --with-db=system. If your system has a libdb* file, it will use it (but no guarantees that yours is good). We have only had a chance to test the db libraries on a few systems: Solaris (x86 and sparc), SGI, and Alpha/Digital Unix. Of these systems, the Alpha was the only one to have problems. IMPORTANT NOTE: Autoconf for db detects BYTE_ORDER. Previous systems we have shipped with DB libraries did not configure the byte order explicitly, which means it defaulted to BIG_ENDIAN. If BYTE_ORDER == LITTLE_ENDIAN, DB swaps bytes around. This makes it slower, and possibly incompatable. I can think of no reason to do this other than to support access from heterogeneous systems via NFS. If this turns out to be a problem for you, go to the auto directory (listed below) and modify the include/compat.h there manually to set the BYTE_ORDER. This release does not install the db.1.85 library. If you want to install it, go to the directory neo7.5.1/tools/db.1.85/PORT/auto and type 'make install' after everything else is done. DB has gone through a flurry of activity in the last year. Keith Bostic has released several new versions of the db library. They have a compatability mode that can be used with the Neo package. However, this has not been integrated into the release yet. (Look for it in Neotcl8.0.) 4. See our Tcl web page at http://www.neosoft.com/tcl for information about NeoSoft commercial support and testing metrics. 5. See the individual packages' README, CHANGES (etc.) files for more information on restrictions, enhancements, etc. 6. In most cases, this should just configure and build. If you have any problems, please let us know at tcl-project@neosoft.com. ACKNOWLEDGMENTS Many thanks to the Tcl community, without which Tcl would not exist. Especially: John Ousterhout and the many - Tcl and Tk Sun Microsystems for their continuing support Mark Diekhans and Karl Lehenbauer - Extended Tcl (more and more of which keeps getting subsumed into core Tcl!) Michael McClennan - [incr tcl] Brian C. Smith/Cornell University and Lawrence A. Rowe/University of California at Berkeley Distributed Processing extensions Don Libes/NIST - Expect Tom Boutell and the Quest Center At Cold Spring Harbor Labs Graphics Drawing library (gd) Mark L. Ulferts/DSC Communications Corp and others - [incr Widgets] Again, NeoSoft has provided the funding for me to do this release. Many thanks to Karl Lehenbauer and NeoSoft for doing so. Why do a tcl7.6-based release: Even though Tcl8 is already out, there are probably many folks out there who will not to move to Tcl8 for various reasons, most notably that Itcl is not yet out for Tcl8. Also, several people asked Karl about it at the Tcl conference in Boston last summer. Hopefully they will still find it useful. Randy Kunkee NeoSoft, Inc. Houston, TX itcl2.2/RELEASE_NOTES100666 1751 0 7744 6423672114 13030 0ustar kunkeewheel--------------------------------------------------------------------- Oct 20, 1997: Final release of NeoTcl7.6.1997Q4 1. Upgrades to newer packages: itcl2.2p2 tcl7.6 tk4.2 itcl2.2 (with itcl subdirs removed, includes iwidgets) tclX7.6.0 expect-5.25 dp4.0b1 gd1.2 (a graphics drawing library) neo7.6.0 (neosoft-authored tcl Extensions, also includes db.1.85) 2. Added --without-pkg commands to allow individual Tcl packages to be elided from the build from the configure command. 3. Now when --enable-shared is used, the DB package is also built as a shared library. 4. Added some self-defense into configure script so that certain wrong things (eg. $SHELL not an absolute path) are pointed out. 5. Added back in "make install" rules to Dp4.0b1, as well as fixed "package require Dp". 6. Modified Neo package to build a "neowish" executable (unless --without-x or --without-tk is given to its configure). Needed because Neo tends to use libraries which on some systems are only in static version (eg. libcrypt.a on Solaris 2.5.1), and besides, Tk isn't designed to load dynamically. --------------------------------------------------------------------- Oct 20, 1996: Final release of NeoTcl7.5.1996Q4 Changes in configure for tcl7.5 and tk4.1 to assist the correct config of Expect. (Needed changes that weren't in the Itcl2.1 versions). Modify 'make clean' of Expect to remove new file generated (pkgIndex.tcl). --------------------------------------------------------------------- Oct 13, 1996: NeoTcl7.5 Beta 2 release Move the Neo7.5.1 package to patch level 1. --------------------------------------------------------------------- Sep 27, 1996: NeoTcl7.5 Beta 1 release --------------------------------------------------------------------- CHANGES SINCE NeoSoft Tcl7.3e release of October 23, 1995 (there have been minor release changes since 10/23/95, but all features remain the same). This is a major release. In particular, it is based on [Incr Tcl] 2.1, Tcl7.5, Tk3.6, and tclX7.5.*. Our previous release was based on Tcl7.3, Tk3.6, [incr Tcl] 1.5, and tclX7.3b. Tcl7.3/Tk3.6 were for a long time the standard core upon which all other Tcl packages were based. The last two years have seen a flurry of activity which continues at breakneck pace. We will continue to track Tcl and the latest upgrades as they come out. One should examine the manual pages for Tcl and Tk to get an idea of how things have changed. To highlight a few changes and give anyone who hasn't been following them an idea of how different they are, some examples: Some new features of the core Tcl7.5/Tk4.1 vs Tcl7.3/Tk3.6: - The event loop has been moved from Tk to Tcl - The "fileevent" command for setting event triggers on files - The "load" and "package" commands for dynamically loading packages - Support for shared libraries. - Tk Bindings behave differently and sometimes incompatably. - The "socket" command has been added to core Tcl, subsuming some of the TclX "server*" commands. Incr Tcl 2.1 adds an entire namespace facility to the core Tcl. This feature is always present regardless of which interpreter you run. In addition, Incr Tcl builds Itcl, Itk, and Iwidgets which are all loadable packages. This is an incredibly brief list, so it cannot be understated that if you are porting Tcl7.3/Tk3.6/etc. to the new release, there are portability issues as well as new ways to use Tcl which can shorten the length of your existing code, and do things which you couldn't before. See the README and CHANGES files in the individual package distributions. NEOSOFT TCL CHANGES This is a final release, and has the following missing features: - Tcl Source Code Encryption subsystem You should contact neosoft at info@neosoft.com should you require this feature. It is also worth re-stating that the Berkeley DB library build may possibly build with a different byte order due to autoconf detecting the correct ENDIAN'ness of your machine, causing it to be unable to open db files written by previous versions. Randy Kunkee NeoSoft, Inc. itcl2.2/checkout.sh100666 1751 0 131 6423575346 13166 0ustar kunkeewheel: # for pkg in tclX7.6.0 dp4.0b1 expect-5.25 neo7.6.0 gd1.2 do cvs checkout $pkg done itcl2.2/configure100777 1751 0 106303 6423575667 13032 0ustar kunkeewheel#! /bin/sh # Guess values for system-dependent variables and create Makefiles. # Generated automatically using autoconf version 2.12 # Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc. # # This configure script is free software; the Free Software Foundation # gives unlimited permission to copy, distribute and modify it. # Defaults: ac_help= ac_default_prefix=/usr/local # Any additions from configure.in: ac_default_prefix=/usr/local ac_help="$ac_help --without-tk do not build the Tk toolkit" ac_help="$ac_help --without-itcl do not build Itcl" ac_help="$ac_help --without-itk do not build Itk" ac_help="$ac_help --without-iwidgets do not build Iwidgets" ac_help="$ac_help --without-tclx do not build Extended Tcl (TclX)" ac_help="$ac_help --without-neo do not build the NeoSoft (Neo) package" ac_help="$ac_help --without-expect do not build Expect" ac_help="$ac_help --without-dp do not build Dp" ac_help="$ac_help --without-gd do not build Gd" ac_help="$ac_help --without-x do not build Tk nor packages that use Tk" ac_help="$ac_help --with-nws build only the minimum required by NeoWebScript" # Initialize some variables set by options. # The variables have the same names as the options, with # dashes changed to underlines. build=NONE cache_file=./config.cache exec_prefix=NONE host=NONE no_create= nonopt=NONE no_recursion= prefix=NONE program_prefix=NONE program_suffix=NONE program_transform_name=s,x,x, silent= site= srcdir= target=NONE verbose= x_includes=NONE x_libraries=NONE bindir='${exec_prefix}/bin' sbindir='${exec_prefix}/sbin' libexecdir='${exec_prefix}/libexec' datadir='${prefix}/share' sysconfdir='${prefix}/etc' sharedstatedir='${prefix}/com' localstatedir='${prefix}/var' libdir='${exec_prefix}/lib' includedir='${prefix}/include' oldincludedir='/usr/include' infodir='${prefix}/info' mandir='${prefix}/man' # Initialize some other variables. subdirs= MFLAGS= MAKEFLAGS= # Maximum number of lines to put in a shell here document. ac_max_here_lines=12 ac_prev= for ac_option do # If the previous option needs an argument, assign it. if test -n "$ac_prev"; then eval "$ac_prev=\$ac_option" ac_prev= continue fi case "$ac_option" in -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;; *) ac_optarg= ;; esac # Accept the important Cygnus configure options, so we can diagnose typos. case "$ac_option" in -bindir | --bindir | --bindi | --bind | --bin | --bi) ac_prev=bindir ;; -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*) bindir="$ac_optarg" ;; -build | --build | --buil | --bui | --bu) ac_prev=build ;; -build=* | --build=* | --buil=* | --bui=* | --bu=*) build="$ac_optarg" ;; -cache-file | --cache-file | --cache-fil | --cache-fi \ | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c) ac_prev=cache_file ;; -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \ | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) cache_file="$ac_optarg" ;; -datadir | --datadir | --datadi | --datad | --data | --dat | --da) ac_prev=datadir ;; -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \ | --da=*) datadir="$ac_optarg" ;; -disable-* | --disable-*) ac_feature=`echo $ac_option|sed -e 's/-*disable-//'` # Reject names that are not valid shell variable names. if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } fi ac_feature=`echo $ac_feature| sed 's/-/_/g'` eval "enable_${ac_feature}=no" ;; -enable-* | --enable-*) ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'` # Reject names that are not valid shell variable names. if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } fi ac_feature=`echo $ac_feature| sed 's/-/_/g'` case "$ac_option" in *=*) ;; *) ac_optarg=yes ;; esac eval "enable_${ac_feature}='$ac_optarg'" ;; -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ | --exec | --exe | --ex) ac_prev=exec_prefix ;; -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \ | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \ | --exec=* | --exe=* | --ex=*) exec_prefix="$ac_optarg" ;; -gas | --gas | --ga | --g) # Obsolete; use --with-gas. with_gas=yes ;; -help | --help | --hel | --he) # Omit some internal or obsolete options to make the list less imposing. # This message is too long to be a string in the A/UX 3.1 sh. cat << EOF Usage: configure [options] [host] Options: [defaults in brackets after descriptions] Configuration: --cache-file=FILE cache test results in FILE --help print this message --no-create do not create output files --quiet, --silent do not print \`checking...' messages --version print the version of autoconf that created configure Directory and file names: --prefix=PREFIX install architecture-independent files in PREFIX [$ac_default_prefix] --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX [same as prefix] --bindir=DIR user executables in DIR [EPREFIX/bin] --sbindir=DIR system admin executables in DIR [EPREFIX/sbin] --libexecdir=DIR program executables in DIR [EPREFIX/libexec] --datadir=DIR read-only architecture-independent data in DIR [PREFIX/share] --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc] --sharedstatedir=DIR modifiable architecture-independent data in DIR [PREFIX/com] --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var] --libdir=DIR object code libraries in DIR [EPREFIX/lib] --includedir=DIR C header files in DIR [PREFIX/include] --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include] --infodir=DIR info documentation in DIR [PREFIX/info] --mandir=DIR man documentation in DIR [PREFIX/man] --srcdir=DIR find the sources in DIR [configure dir or ..] --program-prefix=PREFIX prepend PREFIX to installed program names --program-suffix=SUFFIX append SUFFIX to installed program names --program-transform-name=PROGRAM run sed PROGRAM on installed program names EOF cat << EOF Host type: --build=BUILD configure for building on BUILD [BUILD=HOST] --host=HOST configure for HOST [guessed] --target=TARGET configure for TARGET [TARGET=HOST] Features and packages: --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) --enable-FEATURE[=ARG] include FEATURE [ARG=yes] --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) --x-includes=DIR X include files are in DIR --x-libraries=DIR X library files are in DIR EOF if test -n "$ac_help"; then echo "--enable and --with options recognized:$ac_help" fi exit 0 ;; -host | --host | --hos | --ho) ac_prev=host ;; -host=* | --host=* | --hos=* | --ho=*) host="$ac_optarg" ;; -includedir | --includedir | --includedi | --included | --include \ | --includ | --inclu | --incl | --inc) ac_prev=includedir ;; -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \ | --includ=* | --inclu=* | --incl=* | --inc=*) includedir="$ac_optarg" ;; -infodir | --infodir | --infodi | --infod | --info | --inf) ac_prev=infodir ;; -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*) infodir="$ac_optarg" ;; -libdir | --libdir | --libdi | --libd) ac_prev=libdir ;; -libdir=* | --libdir=* | --libdi=* | --libd=*) libdir="$ac_optarg" ;; -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \ | --libexe | --libex | --libe) ac_prev=libexecdir ;; -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \ | --libexe=* | --libex=* | --libe=*) libexecdir="$ac_optarg" ;; -localstatedir | --localstatedir | --localstatedi | --localstated \ | --localstate | --localstat | --localsta | --localst \ | --locals | --local | --loca | --loc | --lo) ac_prev=localstatedir ;; -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \ | --localstate=* | --localstat=* | --localsta=* | --localst=* \ | --locals=* | --local=* | --loca=* | --loc=* | --lo=*) localstatedir="$ac_optarg" ;; -mandir | --mandir | --mandi | --mand | --man | --ma | --m) ac_prev=mandir ;; -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*) mandir="$ac_optarg" ;; -nfp | --nfp | --nf) # Obsolete; use --without-fp. with_fp=no ;; -no-create | --no-create | --no-creat | --no-crea | --no-cre \ | --no-cr | --no-c) no_create=yes ;; -no-recursion | --no-recursion | --no-recursio | --no-recursi \ | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) no_recursion=yes ;; -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \ | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \ | --oldin | --oldi | --old | --ol | --o) ac_prev=oldincludedir ;; -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \ | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \ | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*) oldincludedir="$ac_optarg" ;; -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) ac_prev=prefix ;; -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) prefix="$ac_optarg" ;; -program-prefix | --program-prefix | --program-prefi | --program-pref \ | --program-pre | --program-pr | --program-p) ac_prev=program_prefix ;; -program-prefix=* | --program-prefix=* | --program-prefi=* \ | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*) program_prefix="$ac_optarg" ;; -program-suffix | --program-suffix | --program-suffi | --program-suff \ | --program-suf | --program-su | --program-s) ac_prev=program_suffix ;; -program-suffix=* | --program-suffix=* | --program-suffi=* \ | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*) program_suffix="$ac_optarg" ;; -program-transform-name | --program-transform-name \ | --program-transform-nam | --program-transform-na \ | --program-transform-n | --program-transform- \ | --program-transform | --program-transfor \ | --program-transfo | --program-transf \ | --program-trans | --program-tran \ | --progr-tra | --program-tr | --program-t) ac_prev=program_transform_name ;; -program-transform-name=* | --program-transform-name=* \ | --program-transform-nam=* | --program-transform-na=* \ | --program-transform-n=* | --program-transform-=* \ | --program-transform=* | --program-transfor=* \ | --program-transfo=* | --program-transf=* \ | --program-trans=* | --program-tran=* \ | --progr-tra=* | --program-tr=* | --program-t=*) program_transform_name="$ac_optarg" ;; -q | -quiet | --quiet | --quie | --qui | --qu | --q \ | -silent | --silent | --silen | --sile | --sil) silent=yes ;; -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb) ac_prev=sbindir ;; -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \ | --sbi=* | --sb=*) sbindir="$ac_optarg" ;; -sharedstatedir | --sharedstatedir | --sharedstatedi \ | --sharedstated | --sharedstate | --sharedstat | --sharedsta \ | --sharedst | --shareds | --shared | --share | --shar \ | --sha | --sh) ac_prev=sharedstatedir ;; -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \ | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \ | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \ | --sha=* | --sh=*) sharedstatedir="$ac_optarg" ;; -site | --site | --sit) ac_prev=site ;; -site=* | --site=* | --sit=*) site="$ac_optarg" ;; -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) ac_prev=srcdir ;; -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) srcdir="$ac_optarg" ;; -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \ | --syscon | --sysco | --sysc | --sys | --sy) ac_prev=sysconfdir ;; -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \ | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*) sysconfdir="$ac_optarg" ;; -target | --target | --targe | --targ | --tar | --ta | --t) ac_prev=target ;; -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) target="$ac_optarg" ;; -v | -verbose | --verbose | --verbos | --verbo | --verb) verbose=yes ;; -version | --version | --versio | --versi | --vers) echo "configure generated by autoconf version 2.12" exit 0 ;; -with-* | --with-*) ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'` # Reject names that are not valid shell variable names. if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } fi ac_package=`echo $ac_package| sed 's/-/_/g'` case "$ac_option" in *=*) ;; *) ac_optarg=yes ;; esac eval "with_${ac_package}='$ac_optarg'" ;; -without-* | --without-*) ac_package=`echo $ac_option|sed -e 's/-*without-//'` # Reject names that are not valid shell variable names. if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } fi ac_package=`echo $ac_package| sed 's/-/_/g'` eval "with_${ac_package}=no" ;; --x) # Obsolete; use --with-x. with_x=yes ;; -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \ | --x-incl | --x-inc | --x-in | --x-i) ac_prev=x_includes ;; -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \ | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*) x_includes="$ac_optarg" ;; -x-libraries | --x-libraries | --x-librarie | --x-librari \ | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l) ac_prev=x_libraries ;; -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \ | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) x_libraries="$ac_optarg" ;; -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; } ;; *) if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then echo "configure: warning: $ac_option: invalid host type" 1>&2 fi if test "x$nonopt" != xNONE; then { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; } fi nonopt="$ac_option" ;; esac done if test -n "$ac_prev"; then { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; } fi trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 # File descriptor usage: # 0 standard input # 1 file creation # 2 errors and warnings # 3 some systems may open it to /dev/tty # 4 used on the Kubota Titan # 6 checking for... messages and results # 5 compiler messages saved in config.log if test "$silent" = yes; then exec 6>/dev/null else exec 6>&1 fi exec 5>./config.log echo "\ This file contains any messages produced by compilers while running configure, to aid debugging if configure makes a mistake. " 1>&5 # Strip out --no-create and --no-recursion so they do not pile up. # Also quote any args containing shell metacharacters. ac_configure_args= for ac_arg do case "$ac_arg" in -no-create | --no-create | --no-creat | --no-crea | --no-cre \ | --no-cr | --no-c) ;; -no-recursion | --no-recursion | --no-recursio | --no-recursi \ | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;; *" "*|*" "*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*) ac_configure_args="$ac_configure_args '$ac_arg'" ;; *) ac_configure_args="$ac_configure_args $ac_arg" ;; esac done # NLS nuisances. # Only set these to C if already set. These must not be set unconditionally # because not all systems understand e.g. LANG=C (notably SCO). # Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'! # Non-C LC_CTYPE values break the ctype check. if test "${LANG+set}" = set; then LANG=C; export LANG; fi if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi # confdefs.h avoids OS command line length limits that DEFS can exceed. rm -rf conftest* confdefs.h # AIX cpp loses on an empty file, so make sure it contains at least a newline. echo > confdefs.h # A filename unique to this package, relative to the directory that # configure is in, which we can look for to find out if srcdir is correct. ac_unique_file=itcl/generic/itcl.h # Find the source files, if location was not specified. if test -z "$srcdir"; then ac_srcdir_defaulted=yes # Try the directory containing this script, then its parent. ac_prog=$0 ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'` test "x$ac_confdir" = "x$ac_prog" && ac_confdir=. srcdir=$ac_confdir if test ! -r $srcdir/$ac_unique_file; then srcdir=.. fi else ac_srcdir_defaulted=no fi if test ! -r $srcdir/$ac_unique_file; then if test "$ac_srcdir_defaulted" = yes; then { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; } else { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; } fi fi srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'` # Prefer explicitly selected file to automatically selected ones. if test -z "$CONFIG_SITE"; then if test "x$prefix" != xNONE; then CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site" else CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site" fi fi for ac_site_file in $CONFIG_SITE; do if test -r "$ac_site_file"; then echo "loading site script $ac_site_file" . "$ac_site_file" fi done if test -r "$cache_file"; then echo "loading cache $cache_file" . $cache_file else echo "creating cache $cache_file" > $cache_file fi ac_ext=c # CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. ac_cpp='$CPP $CPPFLAGS' ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5' ac_link='${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5' cross_compiling=$ac_cv_prog_cc_cross if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu. if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then ac_n= ac_c=' ' ac_t=' ' else ac_n=-n ac_c= ac_t= fi else ac_n= ac_c='\c' ac_t= fi # RCS: $Id: configure,v 1.2 1997/10/23 07:23:29 kunkee Exp $ ac_aux_dir= for ac_dir in config $srcdir/config; do if test -f $ac_dir/install-sh; then ac_aux_dir=$ac_dir ac_install_sh="$ac_aux_dir/install-sh -c" break elif test -f $ac_dir/install.sh; then ac_aux_dir=$ac_dir ac_install_sh="$ac_aux_dir/install.sh -c" break fi done if test -z "$ac_aux_dir"; then { echo "configure: error: can not find install-sh or install.sh in config $srcdir/config" 1>&2; exit 1; } fi ac_config_guess=$ac_aux_dir/config.guess ac_config_sub=$ac_aux_dir/config.sub ac_configure=$ac_aux_dir/configure # This should be Cygnus configure. case "$SHELL" in bash) echo "It's good you're using BASH for a shell, but you must" echo "export SHELL=/bin/bash, not just $SHELL" ;; */sh) echo "Looks like you're using an old Bourne shell. You are" echo "likely headed for trouble. If the build fails, get BASH" echo "from ftp://prep.ai.mit.edu/pub/gnu, build it and use it" echo "for your shell. You'll should also make sure to export" echo "CONFIG_SHELL=/bin/bash (or /usr/local/bin/bash)." echo "Ksh should work too." ;; */ksh) ;; */csh) echo "Running from the C-Shell, eh? I like your style, but" echo "you are about for sure headed for disaster. Use another" echo "shell (bash or ksh) to configure and build Neotcl7.6." exit 1 ;; esac cat << EOF ***Warning***" Some configure scripts included in these packages stretch the limits of stock tools delivered with many Unix vendors' systems. The tools that are taken to their limits are (in the order in which they should be prime suspects): the Bourne shell (/bin/sh), sed, and make. EOF # ----------------------------------------------------------------------- # # Set up a new default --prefix. If a previous installation of # [incr Tcl] can be found searching $PATH use that directory. # # ----------------------------------------------------------------------- if test "x$prefix" = xNONE; then echo $ac_n "checking for prefix by $ac_c" 1>&6 # Extract the first word of "itclsh", so it can be a program name with args. set dummy itclsh; ac_word=$2 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 echo "configure:612: checking for $ac_word" >&5 if eval "test \"`echo '$''{'ac_cv_path_ITCLSH'+set}'`\" = set"; then echo $ac_n "(cached) $ac_c" 1>&6 else case "$ITCLSH" in /*) ac_cv_path_ITCLSH="$ITCLSH" # Let the user override the test with a path. ;; *) IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS="${IFS}:" for ac_dir in $PATH; do test -z "$ac_dir" && ac_dir=. if test -f $ac_dir/$ac_word; then ac_cv_path_ITCLSH="$ac_dir/$ac_word" break fi done IFS="$ac_save_ifs" ;; esac fi ITCLSH="$ac_cv_path_ITCLSH" if test -n "$ITCLSH"; then echo "$ac_t""$ITCLSH" 1>&6 else echo "$ac_t""no" 1>&6 fi if test -n "$ac_cv_path_ITCLSH"; then prefix=`echo $ac_cv_path_ITCLSH|sed 's%/[^/][^/]*//*[^/][^/]*$%%'` fi fi # Check whether --with-tk or --without-tk was given. if test "${with_tk+set}" = set; then withval="$with_tk" : fi # Check whether --with-itcl or --without-itcl was given. if test "${with_itcl+set}" = set; then withval="$with_itcl" : fi # Check whether --with-itk or --without-itk was given. if test "${with_itk+set}" = set; then withval="$with_itk" : fi # Check whether --with-iwidgets or --without-iwidgets was given. if test "${with_iwidgets+set}" = set; then withval="$with_iwidgets" : fi # Check whether --with-tclx or --without-tclx was given. if test "${with_tclx+set}" = set; then withval="$with_tclx" : fi # Check whether --with-neo or --without-neo was given. if test "${with_neo+set}" = set; then withval="$with_neo" : fi # Check whether --with-expect or --without-expect was given. if test "${with_expect+set}" = set; then withval="$with_expect" : fi # Check whether --with-dp or --without-dp was given. if test "${with_dp+set}" = set; then withval="$with_dp" : fi # Check whether --with-gd or --without-gd was given. if test "${with_gd+set}" = set; then withval="$with_gd" : fi pkg_list="itcl tk itk iwidgets tclx neo expect dp gd" pkg_itcl=itcl/unix pkg_tk=tk4.2/unix pkg_itk=itk/unix pkg_iwidgets=iwidgets2.2.0/unix pkg_tclx=tclX7.6.0/unix pkg_neo=neo7.6.0/generic pkg_expect=expect-5.25 pkg_dp=dp4.0b1/unix pkg_gd=gd1.2 # Check whether --with-x or --without-x was given. if test "${with_x+set}" = set; then withval="$with_x" use_x=$withval else use_x=yes fi if test "$use_x" = "no" then with_tk=no with_itk=no with_iwidgets=no fi # Request to build only the minimum for NWS. This is really just a # shortcut for NeoSoft, and not a recommendation, except to say that this # is all you need for NeoWebScript and if the other packages are failing # to build for any reason and all you want this for is to support # NeoWebScript, then here's a possible way to do it. # Check whether --with-nws or --without-nws was given. if test "${with_nws+set}" = set; then withval="$with_nws" build_for_nws=$withval else build_for_nws=no fi if test "$build_for_nws" = "yes" then with_tk=no with_itcl=no with_itk=no with_iwidgets=no with_expect=no with_dp=no fi # Don't try to build if the directory is not there. dirlist=tcl7.6/unix for pkg in $pkg_list do eval withval=\$with_$pkg if test "$withval" != no then eval dir=\$pkg_$pkg if test -d $dir then dirlist="$dirlist $dir" else echo WARNING: $pkg cannot be built: $dir is missing fi fi done echo Building $dirlist subdirs="$dirlist" trap '' 1 2 15 cat > confcache <<\EOF # This file is a shell script that caches the results of configure # tests run on this system so they can be shared between configure # scripts and configure runs. It is not useful on other systems. # If it contains results you don't want to keep, you may remove or edit it. # # By default, configure uses ./config.cache as the cache file, # creating it if it does not exist already. You can give configure # the --cache-file=FILE option to use a different cache file; that is # what configure does when it calls configure scripts in # subdirectories, so they share the cache. # Giving --cache-file=/dev/null disables caching, for debugging configure. # config.status only pays attention to the cache file if you give it the # --recheck option to rerun configure. # EOF # The following way of writing the cache mishandles newlines in values, # but we know of no workaround that is simple, portable, and efficient. # So, don't put newlines in cache variables' values. # Ultrix sh set writes to stderr and can't be redirected directly, # and sets the high bit in the cache file unless we assign to the vars. (set) 2>&1 | case `(ac_space=' '; set) 2>&1` in *ac_space=\ *) # `set' does not quote correctly, so add quotes (double-quote substitution # turns \\\\ into \\, and sed turns \\ into \). sed -n \ -e "s/'/'\\\\''/g" \ -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p" ;; *) # `set' quotes correctly as required by POSIX, so do not add quotes. sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p' ;; esac >> confcache if cmp -s $cache_file confcache; then : else if test -w $cache_file; then echo "updating cache $cache_file" cat confcache > $cache_file else echo "not updating unwritable cache $cache_file" fi fi rm -f confcache trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 test "x$prefix" = xNONE && prefix=$ac_default_prefix # Let make expand exec_prefix. test "x$exec_prefix" = xNONE && exec_prefix='${prefix}' # Any assignment to VPATH causes Sun make to only execute # the first set of double-colon rules, so remove it if not needed. # If there is a colon in the path, we need to keep it. if test "x$srcdir" = x.; then ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d' fi trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15 # Transform confdefs.h into DEFS. # Protect against shell expansion while executing Makefile rules. # Protect against Makefile macro expansion. cat > conftest.defs <<\EOF s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g s%\[%\\&%g s%\]%\\&%g s%\$%$$%g EOF DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '` rm -f conftest.defs # Without the "./", some shells look in PATH for config.status. : ${CONFIG_STATUS=./config.status} echo creating $CONFIG_STATUS rm -f $CONFIG_STATUS cat > $CONFIG_STATUS </dev/null | sed 1q`: # # $0 $ac_configure_args # # Compiler output produced by configure, useful for debugging # configure, is in ./config.log if it exists. ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]" for ac_option do case "\$ac_option" in -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion" exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;; -version | --version | --versio | --versi | --vers | --ver | --ve | --v) echo "$CONFIG_STATUS generated by autoconf version 2.12" exit 0 ;; -help | --help | --hel | --he | --h) echo "\$ac_cs_usage"; exit 0 ;; *) echo "\$ac_cs_usage"; exit 1 ;; esac done ac_given_srcdir=$srcdir trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15 EOF cat >> $CONFIG_STATUS < conftest.subs <<\\CEOF $ac_vpsub $extrasub s%@CFLAGS@%$CFLAGS%g s%@CPPFLAGS@%$CPPFLAGS%g s%@CXXFLAGS@%$CXXFLAGS%g s%@DEFS@%$DEFS%g s%@LDFLAGS@%$LDFLAGS%g s%@LIBS@%$LIBS%g s%@exec_prefix@%$exec_prefix%g s%@prefix@%$prefix%g s%@program_transform_name@%$program_transform_name%g s%@bindir@%$bindir%g s%@sbindir@%$sbindir%g s%@libexecdir@%$libexecdir%g s%@datadir@%$datadir%g s%@sysconfdir@%$sysconfdir%g s%@sharedstatedir@%$sharedstatedir%g s%@localstatedir@%$localstatedir%g s%@libdir@%$libdir%g s%@includedir@%$includedir%g s%@oldincludedir@%$oldincludedir%g s%@infodir@%$infodir%g s%@mandir@%$mandir%g s%@ITCLSH@%$ITCLSH%g s%@subdirs@%$subdirs%g CEOF EOF cat >> $CONFIG_STATUS <<\EOF # Split the substitutions into bite-sized pieces for seds with # small command number limits, like on Digital OSF/1 and HP-UX. ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script. ac_file=1 # Number of current file. ac_beg=1 # First line for current file. ac_end=$ac_max_sed_cmds # Line after last line for current file. ac_more_lines=: ac_sed_cmds="" while $ac_more_lines; do if test $ac_beg -gt 1; then sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file else sed "${ac_end}q" conftest.subs > conftest.s$ac_file fi if test ! -s conftest.s$ac_file; then ac_more_lines=false rm -f conftest.s$ac_file else if test -z "$ac_sed_cmds"; then ac_sed_cmds="sed -f conftest.s$ac_file" else ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file" fi ac_file=`expr $ac_file + 1` ac_beg=$ac_end ac_end=`expr $ac_end + $ac_max_sed_cmds` fi done if test -z "$ac_sed_cmds"; then ac_sed_cmds=cat fi EOF cat >> $CONFIG_STATUS <> $CONFIG_STATUS <<\EOF for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in". case "$ac_file" in *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'` ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;; *) ac_file_in="${ac_file}.in" ;; esac # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories. # Remove last slash and all that follows it. Not all systems have dirname. ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'` if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then # The file is in a subdirectory. test ! -d "$ac_dir" && mkdir "$ac_dir" ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`" # A "../" for each directory in $ac_dir_suffix. ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'` else ac_dir_suffix= ac_dots= fi case "$ac_given_srcdir" in .) srcdir=. if test -z "$ac_dots"; then top_srcdir=. else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;; /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;; *) # Relative path. srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix" top_srcdir="$ac_dots$ac_given_srcdir" ;; esac echo creating "$ac_file" rm -f "$ac_file" configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure." case "$ac_file" in *Makefile*) ac_comsub="1i\\ # $configure_input" ;; *) ac_comsub= ;; esac ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"` sed -e "$ac_comsub s%@configure_input@%$configure_input%g s%@srcdir@%$srcdir%g s%@top_srcdir@%$top_srcdir%g " $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file fi; done rm -f conftest.s* EOF cat >> $CONFIG_STATUS <> $CONFIG_STATUS <<\EOF exit 0 EOF chmod +x $CONFIG_STATUS rm -fr confdefs* $ac_clean_files test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1 if test "$no_recursion" != yes; then # Remove --cache-file and --srcdir arguments so they do not pile up. ac_sub_configure_args= ac_prev= for ac_arg in $ac_configure_args; do if test -n "$ac_prev"; then ac_prev= continue fi case "$ac_arg" in -cache-file | --cache-file | --cache-fil | --cache-fi \ | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c) ac_prev=cache_file ;; -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \ | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) ;; -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) ac_prev=srcdir ;; -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) ;; *) ac_sub_configure_args="$ac_sub_configure_args $ac_arg" ;; esac done for ac_config_dir in $dirlist; do # Do not complain, so a configure script can configure whichever # parts of a large source tree are present. if test ! -d $srcdir/$ac_config_dir; then continue fi echo configuring in $ac_config_dir case "$srcdir" in .) ;; *) if test -d ./$ac_config_dir || mkdir ./$ac_config_dir; then :; else { echo "configure: error: can not create `pwd`/$ac_config_dir" 1>&2; exit 1; } fi ;; esac ac_popdir=`pwd` cd $ac_config_dir # A "../" for each directory in /$ac_config_dir. ac_dots=`echo $ac_config_dir|sed -e 's%^\./%%' -e 's%[^/]$%&/%' -e 's%[^/]*/%../%g'` case "$srcdir" in .) # No --srcdir option. We are building in place. ac_sub_srcdir=$srcdir ;; /*) # Absolute path. ac_sub_srcdir=$srcdir/$ac_config_dir ;; *) # Relative path. ac_sub_srcdir=$ac_dots$srcdir/$ac_config_dir ;; esac # Check for guested configure; otherwise get Cygnus style configure. if test -f $ac_sub_srcdir/configure; then ac_sub_configure=$ac_sub_srcdir/configure elif test -f $ac_sub_srcdir/configure.in; then ac_sub_configure=$ac_configure else echo "configure: warning: no configuration information is in $ac_config_dir" 1>&2 ac_sub_configure= fi # The recursion is here. if test -n "$ac_sub_configure"; then # Make the cache file name correct relative to the subdirectory. case "$cache_file" in /*) ac_sub_cache_file=$cache_file ;; *) # Relative path. ac_sub_cache_file="$ac_dots$cache_file" ;; esac echo "running ${CONFIG_SHELL-/bin/sh} $ac_sub_configure $ac_sub_configure_args --cache-file=$ac_sub_cache_file --srcdir=$ac_sub_srcdir" # The eval makes quoting arguments work. if eval ${CONFIG_SHELL-/bin/sh} $ac_sub_configure $ac_sub_configure_args --cache-file=$ac_sub_cache_file --srcdir=$ac_sub_srcdir then : else { echo "configure: error: $ac_sub_configure failed for $ac_config_dir" 1>&2; exit 1; } fi fi cd $ac_popdir done fi itcl2.2/configure.in100777 1751 0 7234 6423575667 13402 0ustar kunkeewheeldnl This file is an input file used by the GNU "autoconf" program to dnl generate the file "configure", which is run during [incr Tcl] dnl installation to configure the system for the local environment. AC_INIT(itcl/generic/itcl.h) # RCS: $Id: configure.in,v 1.2 1997/10/23 07:23:29 kunkee Exp $ AC_CONFIG_AUX_DIR(config) AC_PREREQ(2.0) case "$SHELL" in bash) echo "It's good you're using BASH for a shell, but you must" echo "export SHELL=/bin/bash, not just $SHELL" ;; */sh) echo "Looks like you're using an old Bourne shell. You are" echo "likely headed for trouble. If the build fails, get BASH" echo "from ftp://prep.ai.mit.edu/pub/gnu, build it and use it" echo "for your shell. You'll should also make sure to export" echo "CONFIG_SHELL=/bin/bash (or /usr/local/bin/bash)." echo "Ksh should work too." ;; */ksh) ;; */csh) echo "Running from the C-Shell, eh? I like your style, but" echo "you are about for sure headed for disaster. Use another" echo "shell (bash or ksh) to configure and build Neotcl7.6." exit 1 ;; esac cat << EOF ***Warning***" Some configure scripts included in these packages stretch the limits of stock tools delivered with many Unix vendors' systems. The tools that are taken to their limits are (in the order in which they should be prime suspects): the Bourne shell (/bin/sh), sed, and make. EOF # ----------------------------------------------------------------------- # # Set up a new default --prefix. If a previous installation of # [incr Tcl] can be found searching $PATH use that directory. # # ----------------------------------------------------------------------- AC_PREFIX_DEFAULT(/usr/local) AC_PREFIX_PROGRAM(itclsh) AC_ARG_WITH(tk, [ --without-tk do not build the Tk toolkit]) AC_ARG_WITH(itcl, [ --without-itcl do not build Itcl]) AC_ARG_WITH(itk, [ --without-itk do not build Itk]) AC_ARG_WITH(iwidgets, [ --without-iwidgets do not build Iwidgets]) AC_ARG_WITH(tclx, [ --without-tclx do not build Extended Tcl (TclX)]) AC_ARG_WITH(neo, [ --without-neo do not build the NeoSoft (Neo) package]) AC_ARG_WITH(expect, [ --without-expect do not build Expect]) AC_ARG_WITH(dp, [ --without-dp do not build Dp]) AC_ARG_WITH(gd, [ --without-gd do not build Gd]) pkg_list="itcl tk itk iwidgets tclx neo expect dp gd" pkg_itcl=itcl/unix pkg_tk=tk4.2/unix pkg_itk=itk/unix pkg_iwidgets=iwidgets2.2.0/unix pkg_tclx=tclX7.6.0/unix pkg_neo=neo7.6.0/generic pkg_expect=expect-5.25 pkg_dp=dp4.0b1/unix pkg_gd=gd1.2 AC_ARG_WITH(x, [ --without-x do not build Tk nor packages that use Tk], use_x=$withval, use_x=yes) if test "$use_x" = "no" then with_tk=no with_itk=no with_iwidgets=no fi # Request to build only the minimum for NWS. This is really just a # shortcut for NeoSoft, and not a recommendation, except to say that this # is all you need for NeoWebScript and if the other packages are failing # to build for any reason and all you want this for is to support # NeoWebScript, then here's a possible way to do it. AC_ARG_WITH(nws, [ --with-nws build only the minimum required by NeoWebScript], build_for_nws=$withval, build_for_nws=no) if test "$build_for_nws" = "yes" then with_tk=no with_itcl=no with_itk=no with_iwidgets=no with_expect=no with_dp=no fi # Don't try to build if the directory is not there. dirlist=tcl7.6/unix for pkg in $pkg_list do eval withval=\$with_$pkg if test "$withval" != no then eval dir=\$pkg_$pkg if test -d $dir then dirlist="$dirlist $dir" else echo WARNING: $pkg cannot be built: $dir is missing fi fi done echo Building $dirlist AC_CONFIG_SUBDIRS($dirlist) AC_OUTPUT(Makefile) itcl2.2/license.terms100666 1751 0 11001 6423554632 13554 0ustar kunkeewheelThis software is copyrighted by Lucent Technologies, Inc., and other parties. The following terms apply to all files associated with the software unless explicitly disclaimed in individual files. The authors hereby grant permission to use, copy, modify, distribute, and license this software and its documentation for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions. No written agreement, license, or royalty fee is required for any of the authorized uses. Modifications to this software may be copyrighted by their authors and need not follow the licensing terms described here, provided that the new terms are clearly indicated on the first page of each file where they apply. IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. GOVERNMENT USE: If you are acquiring this software on behalf of the U.S. government, the Government shall have only "Restricted Rights" in the software and related documentation as defined in the Federal Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you are acquiring the software on behalf of the Department of Defense, the software shall be classified as "Commercial Computer Software" and the Government shall have only "Restricted Rights" as defined in Clause 252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the authors grant the U.S. Government and others acting in its behalf permission to use and distribute the software in accordance with the terms specified in this license. ----------------------------------------------------------------------- Following is the original agreement for the Tcl/Tk software from Sun Microsystems. ----------------------------------------------------------------------- This software is copyrighted by the Regents of the University of California, Sun Microsystems, Inc., and other parties. The following terms apply to all files associated with the software unless explicitly disclaimed in individual files. The authors hereby grant permission to use, copy, modify, distribute, and license this software and its documentation for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions. No written agreement, license, or royalty fee is required for any of the authorized uses. Modifications to this software may be copyrighted by their authors and need not follow the licensing terms described here, provided that the new terms are clearly indicated on the first page of each file where they apply. IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. GOVERNMENT USE: If you are acquiring this software on behalf of the U.S. government, the Government shall have only "Restricted Rights" in the software and related documentation as defined in the Federal Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you are acquiring the software on behalf of the Department of Defense, the software shall be classified as "Commercial Computer Software" and the Government shall have only "Restricted Rights" as defined in Clause 252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the authors grant the U.S. Government and others acting in its behalf permission to use and distribute the software in accordance with the terms specified in this license. itcl2.2/makefile.bc100666 1751 0 4047 6423554632 13135 0ustar kunkeewheel# Borland 5.01 Makefile for Itcl 2.2 Distribution # # This is the main Borland makefile for the Windows distribution # of [incr Tcl] version 2.2. # # TOOLS -- path to root of Borland Directory # TARGET_ROOT -- Target Directory for installation # SOURCE_ROOT -- Path to root of source tree TOOLS = c:\bc45 TARGET_ROOT = c:\Program files\Itcl2.2 SOURCE_ROOT = c:\Itcl2.2 # # You should not have to modify anything further in this makefile # # # Borland C++ tools # BORLAND = $(TOOLS) IMPLIB = $(BORLAND)\bin\Implib BCC32 = $(BORLAND)\bin\Bcc32 TLINK32 = $(BORLAND)\bin\tlink32 RC = $(BORLAND)\bin\brcc32 BCC = $(BORLAND)\bin\Bcc TLINK = $(BORLAND)\bin\tlink RC16 = $(BORLAND)\bin\brcc32 -31 MAKE = $(BORLAND)\bin\make -fmakefile.bc # # System calls # CP = copy RM = del MKDIR = -mkdir # # Source and Build Paths # TCLDIR = $(SOURCE_ROOT)\Tcl7.6 TKDIR = $(SOURCE_ROOT)\Tk4.2 ITCLDIR = $(SOURCE_ROOT)\Itcl ITKDIR = $(SOURCE_ROOT)\Itk IWIDGETSDIR = $(SOURCE_ROOT)\Iwidgets2.2.0 # # Target Paths # TARGET_BIN = $(TARGET_ROOT)\Bin TARGET_LIB_ROOT = $(TARGET_ROOT)\Lib TARGET_LIB = $(TARGET_LIB_ROOT)\Itcl TARGET_INCLUDE_ROOT = $(TARGET_ROOT)\Include TARGET_INCLUDE = $(TARGET_INCLUDE_ROOT)\Itcl TARGET_DOC = $(TARGET_ROOT)\Html # # Shared Target Files: # TCLLIB = Tcl76i.lib TCLDLL = Tcl76i.dll TKLIB = Tk42i.lib TKDLL = Tk42i.dll ITCLLIB = Itcl22.lib ITCLDLL = Itcl22.dll ITKLIB = Itk22.lib ITKDLL = Itk22.dll # # Paths to Build locations of libraries # TCLLIBDIR = $(TCLDIR)\Win TKLIBDIR = $(TKDIR)\Win ITCLLIBDIR = $(ITCLDIR)\Win ITKLIBDIR = $(ITKDIR)\Win dist: cd $(TCLDIR)\Win $(MAKE) all cd $(TKDIR)\Win $(MAKE) all cd $(ITCLDIR)\Win $(MAKE) all cd $(ITKDIR)\Win $(MAKE) all dist-install: cd $(TCLDIR)\Win $(MAKE) install cd $(TKDIR)\Win $(MAKE) install cd $(ITCLDIR)\Win $(MAKE) install cd $(ITKDIR)\Win $(MAKE) install cd $(IWIDGETSDIR)\Win $(MAKE) install dist-clean: cd $(TCLDIR)\Win $(MAKE) clean cd $(TKDIR)\Win $(MAKE) clean cd $(ITCLDIR)\Win $(MAKE) clean cd $(ITKDIR)\Win $(MAKE) clean itcl2.2/makefile.vc100666 1751 0 6455 6423554632 13166 0ustar kunkeewheel# # Visual C++ 4.1 makefile # # This is the main Visual C++ makefile for the Windows distribution # of [incr Tcl] version 2.2. To compile the distribution using Visual # C++, copy "makefile.vc" to "makefile". Then set the macros for the # location of the source tree, the target directory, and the Microsoft # Compilers. You may then "make dist" to build the distribution, and # "make dist-install" to install it to the target directory you specify # below. # # There are three primary targets for the distribution: # # dist: build the entire distribution: Tcl, Tk, Itcl, Itk # # dist-install: moves built files to target directory # # dist-clean: erases built files in source tree # # TOOLS32 = location of VC++ 32-bit development tools. Note that the # VC++ 2.0 header files are broken, so you need to use the # ones that come with the developer network CD's, or later # versions of VC++. # # TOOLS16 = location of VC++ 1.5 16-bit tools, needed to build thunking # library. This information is optional; if the 16-bit compiler # is not available, then the 16-bit code will not be built. # Tcl will still run without the 16-bit code, but... # A. Under Windows 3.X you will any calls to the exec command # will return an error. # B. A 16-bit program to test the behavior of the exec # command under NT and 95 will not be built. # # TARGET_ROOT -- Target Directory for installation # # SOURCE_ROOT -- Path to root of source tree # TOOLS32 = c:\msdev TOOLS16 = c:\msvc TARGET_ROOT = c:\Program files\Itcl2.2 SOURCE_ROOT = c:\itcl2.2 # # You should not have to modify anything further in this makefile # # # Borland C++ tools # cc32 = $(TOOLS32)\bin\cl.exe link32 = $(TOOLS32)\bin\link.exe rc32 = $(TOOLS32)\bin\rc.exe include32 = -I$(TOOLS32)\include cc16 = $(TOOLS16)\bin\cl.exe link16 = $(TOOLS16)\bin\link.exe rc16 = $(TOOLS16)\bin\rc.exe include16 = -I$(TOOLS16)\include MAKE = $(TOOLS32)\bin\nmake -fmakefile.vc # # System calls # CP = copy RM = del MKDIR = -mkdir # # Source and Build Paths # TCLDIR = $(SOURCE_ROOT)\Tcl7.6 TKDIR = $(SOURCE_ROOT)\Tk4.2 ITCLDIR = $(SOURCE_ROOT)\Itcl ITKDIR = $(SOURCE_ROOT)\Itk IWIDGETSDIR = $(SOURCE_ROOT)\Iwidgets2.2.0 # # Target Paths # TARGET_BIN = $(TARGET_ROOT)\Bin TARGET_LIB_ROOT = $(TARGET_ROOT)\Lib TARGET_LIB = $(TARGET_LIB_ROOT)\Itcl TARGET_INCLUDE_ROOT = $(TARGET_ROOT)\Include TARGET_INCLUDE = $(TARGET_INCLUDE_ROOT)\Itcl TARGET_DOC = $(TARGET_ROOT)\Html # # Shared Target Files: # TCLLIB = Tcl76i.lib TCLDLL = Tcl76i.dll TKLIB = Tk42i.lib TKDLL = Tk42i.dll ITCLLIB = Itcl22.lib ITCLDLL = Itcl22.dll ITKLIB = Itk22.lib ITKDLL = Itk22.dll # # Paths to Build locations of libraries # TCLLIBDIR = $(TCLDIR)\Win TKLIBDIR = $(TKDIR)\Win ITCLLIBDIR = $(ITCLDIR)\Win ITKLIBDIR = $(ITKDIR)\Win dist: cd $(TCLDIR)\Win $(MAKE) all cd $(TKDIR)\Win $(MAKE) all cd $(ITCLDIR)\Win $(MAKE) all cd $(ITKDIR)\Win $(MAKE) all dist-install: cd $(TCLDIR)\Win $(MAKE) install cd $(TKDIR)\Win $(MAKE) install cd $(ITCLDIR)\Win $(MAKE) install cd $(ITKDIR)\Win $(MAKE) install cd $(IWIDGETSDIR)\Win $(MAKE) install dist-clean: cd $(TCLDIR)\Win $(MAKE) clean cd $(TKDIR)\Win $(MAKE) clean cd $(ITCLDIR)\Win $(MAKE) clean cd $(ITKDIR)\Win $(MAKE) clean itcl2.2/doc/ 40755 1751 0 0 6423554633 11512 5ustar kunkeewheelitcl2.2/doc/CVS/ 40755 1751 0 0 6423570007 12136 5ustar kunkeewheelitcl2.2/doc/CVS/Root100644 1751 0 26 6423554633 13046 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/doc/CVS/Repository100644 1751 0 11 6423674263 14276 0ustar kunkeewheel/usr/cvs itcl2.2/doc/CVS/Entries100644 1751 0 53 6423570006 13524 0ustar kunkeewheel/README/1.1.1.1/Thu Oct 23 04:59:07 1997// itcl2.2/doc/README100666 1751 0 1036 6423554633 12473 0ustar kunkeewheel OVERVIEW ------------------------------------------------------------------------ If you are just getting started with [incr Tcl], download the "tutorial" from the itcl web site: http://www.tcltk.com/itcl/ This has over 100 pages of introductory text and code examples. I didn't include it here, since it adds another megabyte to the distribution, and long-time users won't need it. You can find the same tutorial in the book "Tcl/Tk Tools" published by O'Reilly and Associates. This book will be out by the middle of 1997. itcl2.2/html/ 40755 1751 0 0 6423554655 11715 5ustar kunkeewheelitcl2.2/html/CVS/ 40755 1751 0 0 6423570012 12331 5ustar kunkeewheelitcl2.2/html/CVS/Root100644 1751 0 26 6423554634 13246 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/html/CVS/Repository100644 1751 0 11 6423674263 14475 0ustar kunkeewheel/usr/cvs itcl2.2/html/CVS/Entries100644 1751 0 316 6423570012 13742 0ustar kunkeewheel/ListOCmds.html/1.1.1.1/Thu Oct 23 04:59:08 1997// /TclTkHeader.html/1.1.1.1/Thu Oct 23 04:59:08 1997// /TclTkMainList.html/1.1.1.1/Thu Oct 23 04:59:08 1997// /index.html/1.1.1.1/Thu Oct 23 04:59:08 1997// itcl2.2/html/itcl/ 40755 1751 0 0 6423554635 12646 5ustar kunkeewheelitcl2.2/html/itcl/CVS/ 40755 1751 0 0 6423570012 13264 5ustar kunkeewheelitcl2.2/html/itcl/CVS/Root100644 1751 0 26 6423554634 14201 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/html/itcl/CVS/Repository100644 1751 0 11 6423674263 15430 0ustar kunkeewheel/usr/cvs itcl2.2/html/itcl/CVS/Entries100644 1751 0 1057 6423570012 14720 0ustar kunkeewheel/body.n.html/1.1.1.1/Thu Oct 23 04:59:08 1997// /class.n.html/1.1.1.1/Thu Oct 23 04:59:08 1997// /configbody.n.html/1.1.1.1/Thu Oct 23 04:59:08 1997// /delete.n.html/1.1.1.1/Thu Oct 23 04:59:09 1997// /info.n.html/1.1.1.1/Thu Oct 23 04:59:09 1997// /itcl.n.html/1.1.1.1/Thu Oct 23 04:59:09 1997// /itclUserCmds.html/1.1.1.1/Thu Oct 23 04:59:09 1997// /itcl_class.n.html/1.1.1.1/Thu Oct 23 04:59:09 1997// /itcl_info.n.html/1.1.1.1/Thu Oct 23 04:59:09 1997// /itclvars.n.html/1.1.1.1/Thu Oct 23 04:59:09 1997// /local.n.html/1.1.1.1/Thu Oct 23 04:59:09 1997// itcl2.2/html/itcl/body.n.html100666 1751 0 11614 6423554634 15050 0ustar kunkeewheel itcl User Commands - body

itcl User Commands - body

NAME

     body - change the body for a class method/proc

SYNOPSIS

     body className::function args body

DESCRIPTION

     The body command is used  outside  of  an  [incr Tcl]  class
     definition  to define or redefine the body of a class method
     or proc.  This facility allows a class  definition  to  have
     separate   "interface"   and  "implementation"  parts.   The
     "interface" part is a class command  with  declarations  for
     methods,  procs,  instance  variables  and common variables.
     The "implementation" part is a series of body and configbody
     commands.   If  the  "implementation"  part  is  kept  in  a
     separate file, it can be sourced again and again as bugs are
     fixed,  to  support interactive development.  When using the
     "tcl" mode in the emacs editor, the "interface" and  "imple-
     mentation"  parts  can be kept in the same file; as bugs are
     fixed, individual bodies can be highlighted and sent to  the
     test application.

     The name "className::function"  identifies  the  method/proc
     being changed.

     If an args list was specified when the function was  defined
     in  the class definition, the args list for the body command
     must match in meaning.  Variable names can change,  but  the
     argument lists must have the same required arguments and the
     same default values for  optional  arguments.   The  special
     args  argument  acts as a wildcard when included in the args
     list in the class definition; it will  match  zero  or  more
     arguments of any type when the body is redefined.

     If the body string starts with "@", it  is  treated  as  the
     symbolic  name  for a C procedure.  The args list has little
     meaning for the C procedure, except to document the expected
     usage.   (The C procedure is not guaranteed to use arguments
     in this manner.)  If body does not start  with  "@",  it  is
     treated  as  a  Tcl  command  script.   When the function is
     invoked, command line arguments are matched against the args
     list,  and  local  variables  are  created to represent each
     argument.  This is the usual behavior for a Tcl-style proc.

     Symbolic names for C procedures are established by register-
     ing  procedures  via Itcl_RegisterC().  This is usually done
     in  the  Tcl_AppInit()  procedure,  which  is  automatically
     called  when  the  interpreter  starts up.  In the following
     example, the procedure My_FooCmd() is  registered  with  the
     symbolic  name  "foo".   This procedure can be referenced in
     the body command as "@foo".

         int
         Tcl_AppInit(interp)
             Tcl_Interp *interp;     /* Interpreter for application. */
         {
             if (Itcl_Init(interp) == TCL_ERROR) {
                 return TCL_ERROR;
             }

             if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
                 return TCL_ERROR;
             }
         }

EXAMPLE

     In the following example,  a  "File"  class  is  defined  to
     represent  open files.  The method bodies are included below
     the class definition via the body command.   Note  that  the
     bodies of the constructor/destructor must be included in the
     class definition, but they can be  redefined  via  the  body
     command as well.

         class File {
             private variable fid ""
             constructor {name access} {
                 set fid [open $name $access]
             }
             destructor {
                 close $fid
             }

             method get {}
             method put {line}
             method eof {}
         }

         body File::get {} {
             return [gets $fid]
         }
         body File::put {line} {
             puts $fid $line
         }
         body File::eof {} {
             return [::eof $fid]
         }

         #
         # See the File class in action:
         #
         File x /etc/passwd "r"
         while {![x eof]} {
             puts "=> [x get]"
         }
         delete object x

KEYWORDS

     class, object, procedure
itcl2.2/html/itcl/class.n.html100666 1751 0 74367 6423554634 15236 0ustar kunkeewheel itcl User Commands - class

itcl User Commands - class

NAME

     class - create a class of objects

SYNOPSIS

     class className {
         inherit baseClass ?baseClass...?
         constructor args ?init? body
         destructor body
         method name ?args? ?body?
         proc name ?args? ?body?
         variable varName ?init? ?config?
         common varName ?init?

         public command ?arg arg ...?
         protected command ?arg arg ...?
         private command ?arg arg ...?

         set varName ?value?
         array option ?arg arg ...?
     }

     className objName ?arg arg ...?

     objName method ?arg arg ...?

     className::proc ?arg arg ...?

DESCRIPTION

     The fundamental construct in [incr Tcl] is the class defini-
     tion.  Each class acts as a template for actual objects that
     can be created.  The class itself is a namespace which  con-
     tains things common to all objects.  Each object has its own
     unique bundle of data which contains instances of the "vari-
     ables"  defined  in  the class definition.  Each object also
     has a built-in variable named  "this",  which  contains  the
     name  of  the  object.   Classes can also have "common" data
     members that are shared by all objects in a class.

     Two types of functions can be included in the class  defini-
     tion.   "Methods"  are functions which operate on a specific
     object, and therefore have access to  both  "variables"  and
     "common"  data  members.  "Procs" are ordinary procedures in
     the class namespace, and only have access to  "common"  data
     members.

     If the body of any method or proc starts  with  "@",  it  is
     treated  as the symbolic name for a C procedure.  Otherwise,
     it is treated as a Tcl code script.  See below  for  details
     on registering and using C procedures.

     A class can only be defined once,  although  the  bodies  of
     class  methods  and procs can be defined again and again for
     interactive debugging.  See the body and configbody commands
     for details.

     Each namespace can have its own collection  of  objects  and
     classes.   The list of classes available in the current con-
     text can be queried using the "info  classes"  command,  and
     the list of objects, with the "info objects" command.

     A class can be deleted using  the  "delete  class"  command.
     Individual  objects can be deleted using the "delete object"
     command.

CLASS DEFINITIONS

     class className definition
          Provides the definition for a  class  named  className.
          If  the class className already exists, or if a command
          called className exists in the current  namespace  con-
          text,  this  command  returns  an  error.  If the class
          definition is successfully parsed, className becomes  a
          command  in  the current context, handling the creation
          of objects for this class.

     The class definition is evaluated as a series of Tcl  state-
     ments  that define elements within the class.  The following
     class definition commands are recognized:

          inherit baseClass ?baseClass...?
               Causes the current class to  inherit  characteris-
               tics  from one or more base classes.  Classes must
               have been defined by a previous class command,  or
               must  be  available  to  the auto-loading facility
               (see "AUTO-LOADING" below).  A single class defin-
               ition  can  contain  no more than one inherit com-
               mand.

               The order of baseClass names in the  inherit  list
               affects  the  name  resolution  for class members.
               When the same member name appears in two  or  more
               base classes, the base class that appears first in
               the inherit list takes precedence.   For  example,
               if classes "Foo" and "Bar" both contain the member
               "x", and if another class has the "inherit" state-
               ment:

                   inherit Foo Bar

               then the name "x" means "Foo::x".  Other inherited
               members  named  "x"  must be referenced with their
               explicit name, like "Bar::x".

          constructor args ?init? body
               Declares the args argument list and body used  for
               the  constructor,  which  is automatically invoked
               whenever an object is created.

               Before the body is  executed,  the  optional  init
               statement  is  used  to invoke any base class con-
               structors that require  arguments.   Variables  in
               the args specification can be accessed in the init
               code fragment, and passed to base class  construc-
               tors.   After  evaluating  the init statement, any
               base class constructors that have  not  been  exe-
               cuted are invoked automatically without arguments.
               This ensures that all base classes are fully  con-
               structed  before the constructor body is executed.
               By default, this scheme causes constructors to  be
               invoked  in  order  from  least- to most-specific.
               This is exactly the opposite  of  the  order  that
               classes are reported by the info heritage command.

               If construction  is  successful,  the  constructor
               always  returns  the object name-regardless of how
               the body is defined-and the object name becomes  a
               command in the current namespace context.  If con-
               struction fails, an error message is returned.

          destructor body
               Declares the body used for the  destructor,  which
               is   automatically   invoked  when  an  object  is
               deleted.  If the  destructor  is  successful,  the
               object  data  is  destroyed and the object name is
               removed as a command  from  the  interpreter.   If
               destruction  fails,  an  error message is returned
               and the object remains.

               When an object is destroyed,  all  destructors  in
               its  class  hierarchy  are  invoked  in order from
               most- to least-specific.  This is the  order  that
               the  classes  are  reported by the "info heritage"
               command, and it is exactly  the  opposite  of  the
               default constructor order.

          method name ?args? ?body?
               Declares a method called name.   When  the  method
               body is executed, it will have automatic access to
               object-specific variables and common data members.

               If the args list is specified, it establishes  the
               usage  information  for  this  method.   The  body
               command can be used to redefine the  method  body,
               but the args list must match this specification.

               Within the body of another class method, a  method
               can  be  invoked  like any other command-simply by
               using its name.  Outside of the class context, the
               method name must be prefaced an object name, which
               provides the context for the data that it  manipu-
               lates.  Methods in a base class that are redefined
               in the current class, or hidden  by  another  base
               class,     can     be    qualified    using    the
               "className::method" syntax.

          proc name ?args? ?body?
               Declares a proc called name.  A proc is  an  ordi-
               nary procedure within the class namespace.  Unlike
               a method, a proc is invoked without referring to a
               specific  object.  When the proc body is executed,
               it will have automatic access only to common  data
               members.

               If the args list is specified, it establishes  the
               usage information for this proc.  The body command
               can be used to redefine the  proc  body,  but  the
               args list must match this specification.

               Within the body of another class method or proc, a
               proc  can be invoked like any other command-simply
               by using its name.  In any  other  namespace  con-
               text,  the  proc is invoked using a qualified name
               like "className::proc".  Procs  in  a  base  class
               that are redefined in the current class, or hidden
               by another base class, can also  be  accessed  via
               their qualified name.

          variable varName ?init? ?config?
               Defines an object-specific variable named varName.
               All  object-specific  variables  are automatically
               available in class  methods.   They  need  not  be
               declared with anything like the global command.

               If the optional init string is  specified,  it  is
               used  as  the initial value of the variable when a
               new object is created.  Initialization forces  the
               variable  to  be a simple scalar value; uninitial-
               ized variables, on the  other  hand,  can  be  set
               within the constructor and used as arrays.

               The optional config script  is  only  allowed  for
               public  variables.   If specified, this code frag-
               ment is executed whenever  a  public  variable  is
               modified  by the built-in "configure" method.  The
               config script can also be specified outside of the
               class definition using the configbody command.

          common varName ?init?
               Declares a common variable named varName.   Common
               variables  reside  in  the class namespace and are
               shared by all  objects  belonging  to  the  class.
               They  are  just like global variables, except that
               they need not be declared with  the  usual  global
               command.   They  are  automatically visible in all
               class methods and procs.

               If the optional init string is  specified,  it  is
               used  as  the initial value of the variable.  Ini-
               tialization forces the variable  to  be  a  simple
               scalar  value;  uninitialized  variables,  on  the
               other hand, can be set  with  subsequent  set  and
               array commands and used as arrays.

               Once a common data member has been defined, it can
               be  set  using  set  and array commands within the
               class definition.  This allows common data members
               to be initialized as arrays.  For example:

                   class Foo {
                       common boolean
                       set boolean(true) 1
                       set boolean(false) 0
                   }

               Note that if common data members  are  initialized
               within the constructor, they get initialized again
               and again whenever new objects are created.

          public command ?arg arg ...?

          protected command ?arg arg ...?

          private command ?arg arg ...?
               These commands are  used  to  set  the  protection
               level for class members that are created when com-
               mand is evaluated.  The command is usually method,
               proc,  variable  orcommon, and the remaining arg's
               complete the member definition.  However,  command
               can  also  be  a  script containing many different
               member definitions, and the protection level  will
               apply to all of the members that are created.

CLASS USAGE

     Once a class has been defined, the class name can be used as
     a command to create new objects belonging to the class.
     className objName ?args...?
          Creates a new object in class className with  the  name
          objName.   Remaining  arguments  are passed to the con-
          structor of the  most-specific  class.   This  in  turn
          passes  arguments  to  base  class  constructors before
          invoking its own body of commands.  If construction  is
          successful,  a command called objName is created in the
          current namespace context, and objName is  returned  as
          the  result  of this operation.  If an error is encoun-
          tered during construction, the destructors are automat-
          ically  invoked  to  free  any resources that have been
          allocated, the object  is  deleted,  and  an  error  is
          returned.

          If objName contains the string "#auto", that string  is
          replaced  with  an automatically generated name.  Names
          have the form className<number>,  where  the  className
          part  is modified to start with a lowercase letter.  In
          class "Toaster", for example, the "#auto" specification
          would produce names like toaster0, toaster1, etc.  Note
          that "#auto" can be also be  buried  within  an  object
          name:

              fileselectiondialog .foo.bar.#auto -background red

          This     would     generate     an     object     named
          ".foo.bar.fileselectiondialog0".

OBJECT USAGE

     Once an object has been created, the object name can be used
     as a command to invoke methods that operate on the object.

     objName method ?args...?
          Invokes a  method  named  method  on  an  object  named
          objName.   Remaining  arguments are passed to the argu-
          ment list for the method.  The method name can be "con-
          structor",  "destructor",  any method name appearing in
          the class definition, or any of the following  built-in
          methods.

BUILT-IN METHODS

     objName cget option
          Provides access to public  variables  as  configuration
          options.   This mimics the behavior of the usual "cget"
          operation for Tk widgets.  The  option  argument  is  a
          string  of the form "-varName", and this method returns
          the current value of the public variable varName.

     objName configure ?option? ?value option value ...?
          Provides access to public  variables  as  configuration
          options.    This  mimics  the  behavior  of  the  usual
          "configure" operation for Tk widgets.   With  no  argu-
          ments,  this  method returns a list of lists describing
          all of the public variables.  Each list has three  ele-
          ments:   the  variable  name, its initial value and its
          current value.

          If a single option of the form "-varName" is specified,
          then  this  method returns the information for that one
          variable.

          Otherwise, the arguments are  treated  as  option/value
          pairs  assigning  new values to public variables.  Each
          variable is assigned its new value, and if it  has  any
          "config" code associated with it, it is executed in the
          context of the class where  it  was  defined.   If  the
          "config"  code  generates an error, the variable is set
          back to its previous value, and  the  configure  method
          returns an error.

     objName isa className
          Returns non-zero if the given className can be found in
          the object's heritage, and zero otherwise.

     objName info option ?args...?
          Returns information  related  to  a  particular  object
          named  objName, or to its class definition.  The option
          parameter includes the following things, as well as the
          options recognized by the usual Tcl "info" command:

          objName info class
               Returns the name of the  most-specific  class  for
               object objName.

          objName info inherit
               Returns the list of  base  classes  as  they  were
               defined  in  the  "inherit"  command,  or an empty
               string if this class has no base classes.

          objName info heritage
               Returns the current class name and the entire list
               of  base  classes  in  the  order  that  they  are
               traversed for member lookup  and  object  destruc-
               tion.

          name? ?-args? ?-body?
          objName info function  ?cmdName?  ?-protection?  ?-
               type?  ?-
               With no arguments, this command returns a list  of
               all class methods and procs.  If cmdName is speci-
               fied, it returns information for a specific method
               or  proc.  If no flags are specified, this command
               returns a list with the following  elements:   the
               protection  level,  the  type  (method/proc),  the
               qualified name, the argument list  and  the  body.
               Flags  can  be  used  to request specific elements
               from this list.

          name? ?-init? ?-value? ?-config?
          objName info variable  ?varName?  ?-protection?  ?-
               type?  ?-
               With no arguments, this command returns a list  of
               all  object-specific  variables  and  common  data
               members.  If  varName  is  specified,  it  returns
               information  for  a  specific  data member.  If no
               flags are specified, this command returns  a  list
               with   the  following  elements:   the  protection
               level, the type (variable/common),  the  qualified
               name,  the  initial  value, and the current value.
               If varName is a public variable, the "config" code
               is  included  on  this list.  Flags can be used to
               request specific elements from this list.

CHAINING METHODS/PROCS

     Sometimes a base class has a method or proc  that  is  rede-
     fined  with the same name in a derived class.  This is a way
     of making the derived class handle the  same  operations  as
     the  base class, but with its own specialized behavior.  For
     example, suppose we have a Toaster  class  that  looks  like
     this:

         class Toaster {
             variable crumbs 0
             method toast {nslices} {
                 if {$crumbs > 50} {
                     error "== FIRE! FIRE! =="
                 }
                 set crumbs [expr $crumbs+4*$nslices]
             }
             method clean {} {
                 set crumbs 0
             }
         }

     We might create another class like SmartToaster  that  rede-
     fines  the  "toast"  method.   If we want to access the base
     class method, we can qualify it with the base class name, to
     avoid ambiguity:

         class SmartToaster {
             inherit Toaster
             method toast {nslices} {
                 if {$crumbs > 40} {
                     clean

                 }
                 return [Toaster::toast $nslices]
             }
         }

     Instead of hard-coding the base class name, we can  use  the
     "chain" command like this:

         class SmartToaster {
             inherit Toaster
             method toast {nslices} {
                 if {$crumbs > 40} {
                     clean
                 }
                 return [chain $nslices]
             }
         }

     The chain command searches through the class hierarchy for a
     slightly  more  generic  (base  class)  implementation  of a
     method or proc, and invokes it with the specified arguments.
     It  starts at the current class context and searches through
     base classes in the order that  they  are  reported  by  the
     "info  heritage"  command.  If another implementation is not
     found, this  command  does  nothing  and  returns  the  null
     string.

AUTO-LOADING

     Class definitions need not be loaded explicitly; they can be
     loaded  as  needed  by  the usual Tcl auto-loading facility.
     Each directory containing class definition files should have
     an  accompanying  "tclIndex"  file.   Each line in this file
     identifies a Tcl procedure or  [incr Tcl]  class  definition
     and the file where the definition can be found.

     For example, suppose a directory  contains  the  definitions
     for  classes "Toaster" and "SmartToaster".  Then the "tclIn-
     dex" file for this directory would look like:

         # Tcl autoload index file, version 2.0 for [incr Tcl]
         # This file is generated by the "auto_mkindex" command
         # and sourced to set up indexing information for one or
         # more commands.  Typically each line is a command that
         # sets an element in the auto_index array, where the
         # element name is the name of a command and the value is
         # a script that loads the command.

         set auto_index(::Toaster) "source $dir/Toaster.itcl"
         set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"


     The auto_mkindex command is used to automatically
     generate "tclIndex" files.

 The auto-loader must be made aware of this directory by  append-
 ing  the  directory name to the "auto_path" variable.  When this
 is in place, classes will be auto-loaded as needed when used  in
 an application.

C PROCEDURES

     C procedures can be  integrated  into  an  [incr Tcl]  class
     definition  to  implement  methods,  procs, and the "config"
     code for public variables.  Any body that starts with "@" is
     treated as the symbolic name for a C procedure.

     Symbolic names are established by registering procedures via
     Itcl_RegisterC().  This is usually done in the Tcl_AppInit()
     procedure, which is automatically  called  when  the  inter-
     preter  starts  up.  In the following example, the procedure
     My_FooCmd() is registered  with  the  symbolic  name  "foo".
     This  procedure  can  be  referenced  in the body command as
     "@foo".

         int
         Tcl_AppInit(interp)
             Tcl_Interp *interp;     /* Interpreter for application. */
         {
             if (Itcl_Init(interp) == TCL_ERROR) {
                 return TCL_ERROR;
             }

             if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
                 return TCL_ERROR;
             }
         }

     C procedures are implemented just  like  ordinary  Tcl  com-
     mands.  See the CrtCommand man page for details.  Within the
     procedure, class data members can be accessed like  ordinary
     variables  using Tcl_SetVar(), Tcl_GetVar(), Tcl_TraceVar(),
     etc.  Class methods and procs can be executed like  ordinary
     commands  using  Tcl_Eval().  [incr Tcl] makes this possible
     by automatically setting up the context before executing the
     C procedure.

     This scheme provides  a  natural  migration  path  for  code
     development.   Classes  can  be  developed quickly using Tcl
     code to implement the bodies.  An entire application can  be
     built  and tested.  When necessary, individual bodies can be
     implemented with C code to improve performance.

KEYWORDS

     class, object, object-oriented
itcl2.2/html/itcl/configbody.n.html100666 1751 0 11234 6423554634 16234 0ustar kunkeewheel itcl User Commands - configbody

itcl User Commands - configbody

NAME

     configbody - change the "config" code for a public variable

SYNOPSIS

     configbody className::varName body

DESCRIPTION

     The configbody command is  used  outside  of  an  [incr Tcl]
     class  definition  to  define  or redefine the configuration
     code associated with a public  variable.   Public  variables
     act  like  configuration options for an object.  They can be
     modified outside the class scope using the built-in  config-
     ure  method.   Each variable can have a bit of "config" code
     associate with it that is automatically  executed  when  the
     variable  is configured.  The configbody command can be used
     to define or redefine this body of code.

     Like the body command, this facility allows a class  defini-
     tion  to  have  separate  "interface"  and  "implementation"
     parts.   The  "interface"  part  is  a  class  command  with
     declarations for methods, procs, instance variables and com-
     mon variables.  The "implementation" part  is  a  series  of
     body  and configbody commands.  If the "implementation" part
     is kept in a separate file, it  can  be  sourced  again  and
     again as bugs are fixed, to support interactive development.
     When using the "tcl" mode in the emacs editor,  the  "inter-
     face"  and  "implementation"  parts  can be kept in the same
     file;  as  bugs  are  fixed,  individual   bodies   can   be
     highlighted and sent to the test application.

     The name "className::varName" identifies the public variable
     being  updated.   If  the body string starts with "@", it is
     treated as the symbolic name for a C procedure.   Otherwise,
     it is treated as a Tcl command script.

     Symbolic names for C procedures are established by register-
     ing  procedures  via Itcl_RegisterC().  This is usually done
     in  the  Tcl_AppInit()  procedure,  which  is  automatically
     called  when  the  interpreter  starts up.  In the following
     example, the procedure My_FooCmd() is  registered  with  the
     symbolic  name  "foo".   This procedure can be referenced in
     the configbody command as "@foo".

         int
         Tcl_AppInit(interp)
             Tcl_Interp *interp;     /* Interpreter for application. */
         {
             if (Itcl_Init(interp) == TCL_ERROR) {
                 return TCL_ERROR;
             }

             if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
                 return TCL_ERROR;
             }
         }

EXAMPLE

     In the following example,  a  "File"  class  is  defined  to
     represent  open  files.  Whenever the "-name" option is con-
     figured, the existing file is closed,  and  a  new  file  is
     opened.   Note  that the "config" code for a public variable
     is optional.  The "-access" option, for  example,  does  not
     have it.

         class File {
             private variable fid ""

             public variable name ""
             public variable access "r"

             constructor {args} {
                 eval configure $args
             }
             destructor {
                 if {$fid != ""} {
                     close $fid
                 }
             }

             method get {}
             method put {line}
             method eof {}
         }

         body File::get {} {
             return [gets $fid]
         }
         body File::put {line} {
             puts $fid $line
         }
         body File::eof {} {
             return [::eof $fid]
         }

         configbody File::name {
             if {$fid != ""} {
                 close $fid
             }
             set fid [open $name $access]
         }

         #
         # See the File class in action:
         #
         File x

         x configure -name /etc/passwd
         while {![x eof]} {
             puts "=> [x get]"
         }
         delete object x

KEYWORDS

     class, object, variable, configure
itcl2.2/html/itcl/delete.n.html100666 1751 0 6146 6423554635 15342 0ustar kunkeewheel itcl User Commands - delete

itcl User Commands - delete

NAME

     delete - delete things in the interpreter

SYNOPSIS

     delete option ?arg arg ...?

DESCRIPTION

     The delete command is used to delete things  in  the  inter-
     preter.  It is implemented as an ensemble, so extensions can
     add their own options and extend the behavior of  this  com-
     mand.   By  default, the delete command handles the destruc-
     tion of namespaces.

     The option argument determines what action is carried out by
     the  command.   The legal options (which may be abbreviated)
     are:

     delete class name ?name...?
          Deletes one or more  [incr Tcl]  classes  called  name.
          This  deletes all objects in the class, and all derived
          classes as well.

          If an error is encountered while destructing an object,
          it  will  prevent  the destruction of the class and any
          remaining objects.  To destroy the entire class without
          regard for errors, use the "delete namespace" command.

     delete object name ?name...?
          Deletes one or more [incr Tcl] objects called name.  An
          object  is  deleted  by invoking all destructors in its
          class hierarchy, in order from most- to least-specific.
          If all destructors are successful, data associated with
          the object is deleted and the name is removed as a com-
          mand from the interpreter.

          If the access command for an object resides in  another
          namespace, then its qualified name can be used:

              delete object foo::bar::x

          If an error is encountered while destructing an object,
          the  delete  command  is aborted and the object remains
          alive.  To destroy an object without regard for errors,
          use  the  "rename" command to destroy the object access
          command.

     delete namespace name ?name...?
          Deletes one  or  more  namespaces  called  name.   This
          deletes  all  commands  and variables in the namespace,
          and deletes all  child  namespaces  as  well.   When  a
          namespace  is deleted, it is automatically removed from
          the import lists of all other namespaces.

KEYWORDS

     namespace, proc, variable, ensemble
itcl2.2/html/itcl/info.n.html100666 1751 0 33746 6423554635 15061 0ustar kunkeewheel itcl User Commands - info

itcl User Commands - info

NAME

     info - Return information about the state of the Tcl  inter-
     preter

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 classes ?pattern?
          Returns a list of  classes  available  in  the  current
          namespace  context.   If a class belongs to the current  |
          namespace context, its simple name is reported;  other-  |
          wise,  if  a  class is imported from another namespace,  |
          its fully-qualified name is reported.

          If the optional pattern is specified, then the reported
          names  are  compared  using  the  rules  of the "string
          match" command, and only matching names are reported.

     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 in the current namespace context,  |
          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 pat-
          tern  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 typi-
          cally 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 context
          Returns  the  fully-qualified  name  for  the   current  |
          namespace  context.   The  global  namespace  ("::") is  |
          represented as a null string, making it easy  to  build  |
          namespace names like "[info context]::foo".

     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 pro-
          cedure.  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  in the  |
          current namespace context.  If  pattern  is  specified,
          only those names matching pattern are returned.  Match-
          ing is determined using the same rules  as  for  string
          match.

     info level ?number?
          If number is not  specified,  this  command  returns  a
          number  giving  the  stack  level  of the invoking pro-
          cedure, or 0 if the command is  invoked  at  top-level.
          If  number is specified, then the result is a list con-
          sisting of the name and  arguments  for  the  procedure
          call  at level number on the stack.  If number is posi-
          tive 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 pro-
          cedure, -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 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 namespace option ?arg arg ...?
          A collection  of  queries  regarding  namespaces.   The  |
          option argument should be one of the following:

          info namespace all ?pattern?
               Returns a list of  all  child  namespaces  in  the  |
               current  namespace  context.   This  includes  the  |
               direct children of the current namespace and other  |
               children  that  are  visible  because their parent  |
               namespace was imported.  The direct children  have  |
               simple  names  and  appear  first on the list; the  |
               imported children have fully-qualified  names  and  |
               appear at the end of the list.

          info namespace children ?name?
               Returns a list of  all  child  namespaces  in  the  |
               namespace  name.   If  name is not specified, then  |
               children are reported  in  the  current  namespace  |
               context.  Unlike the "info namespace all" command,  |
               this command reports only  the  children  directly  |
               contained  within  the  namespace,  and it reports  |
               them with fully-qualified names.

          info namespace parent ?name?
               Returns the fully-qualified name of the parent for  |
               namespace  name.   If  name is not specified, then  |
               the parent of the  current  namespace  context  is  |
               reported.

          info namespace qualifiers string
               Returns the leading namespace qualifiers  for  the  |
               specified  string.  Qualifiers are namespace names  |
               separated by the  "::"  string.   For  the  string  |
               "::foo::bar::x",   this   command   would   return  |
               "::foo::bar".

          info namespace tail string
               Returns the simple name at the  end  of  qualified  |
               string.   Qualifiers are namespace names separated  |
               by   the   "::"   string.     For    the    string  |
               "::foo::bar::x", this command would return "x".

     info objects ?pattern? ?-class className? ?-isa className?
          Returns a list of  objects  available  in  the  current
          namespace context.  If an object belongs to the current  |
          namespace context, its simple name is reported;  other-  |
          wise,  if an object is imported from another namespace,  |
          its fully-qualified access command is reported.

          If the optional pattern is specified, then the reported
          names  are  compared  using  the  rules  of the "string
          match" command, and only matching names  are  reported.
          If  the  optional "-class" parameter is specified, this
          list is restricted to objects whose most-specific class
          is  className.   If  the  optional  "-isa" parameter is
          specified, this list is further restricted  to  objects
          having the given className anywhere in their heritage.

     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  in  the  current  |
          namespace context.  If pattern is specified, only those
          names  matching  pattern  are  returned.   Matching  is
          determined using the same rules as for string match.

     info protection ?-command? ?-variable? name
          Returns the current protection level (public, protected  |
          or  private)  for  the  specified name.  The protection  |
          level is set using the public,  protected  and  private  |
          commands  when  a  command or variable is created.  The  |
          protection level indicates whether or not a command  or  |
          variable can be accessed from other namespace contexts.  |
          See  the  documentation  on  namespace  for  the  rules  |
          regarding  command/variable access.  If no flags speci-  |
          fied, or if the -command  flag  is  included,  name  is  |
          treated  as  a  command name.  If the -variable flag is  |
          included, name is treated as a variable name.

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

     info which ?-command? ?-variable? ?-namespace? name
          Resolves the specified name in  the  current  namespace  |
          context   and  returns  a  fully-qualified  name  which  |
          uniquely  identifies  it.   See  the  documentation  on  |
          namespace  for the rules regarding name resolution.  If  |
          no  flags  specified,  or  if  the  -command  flag   is  |
          included,  name  is  treated as a command name.  If the  |
          -variable flag is included, name is treated as a  vari-  |
          able name.  If the -namespace flag is included, name is  |
          treated as a namespace name.

KEYWORDS

     command, information, interpreter, level,  procedure,  vari-
     able
itcl2.2/html/itcl/itcl.n.html100666 1751 0 20625 6423554635 15051 0ustar kunkeewheel itcl User Commands - itcl

itcl User Commands - itcl

NAME

     itcl - object-oriented extensions to Tcl

DESCRIPTION

     [incr Tcl] provides object-oriented extensions to Tcl,  much
     as  C++  provides  object-oriented  extensions  to  C.   The
     emphasis of this work, however, is not to create a whiz-bang
     object-oriented  programming  environment.  Rather, it is to
     support more structured programming practices in Tcl without
     changing  the  flavor  of  the language.  More than anything
     else, [incr Tcl] provides a means of  encapsulating  related
     procedures  together  with  their shared data in a namespace
     that is hidden from the outside world.  It encourages better
     programming   by  promoting  the  object-oriented  "library"
     mindset.  It also allows for  code  re-use  through  inheri-
     tance.

CLASSES

     The fundamental construct in [incr Tcl] is the class defini-
     tion.  Each class acts as a template for actual objects that
     can be created.  Each object has its own  unique  bundle  of
     data, which contains instances of the "variables" defined in
     the class.  Special procedures called "methods" are used  to
     manipulate  individual  objects.   Methods are just like the
     operations that are used  to  manipulate  Tk  widgets.   The
     "button"  widget,  for  example, has methods such as "flash"
     and "invoke" that cause a particular  button  to  blink  and
     invoke its command.

     Within the body of a method, the "variables" defined in  the
     class   are  automatically  available.   They  need  not  be
     declared with anything  like  the  global  command.   Within
     another class method, a method can be invoked like any other
     command-simply by using its name.  From any  other  context,
     the  method  name  must be prefaced by an object name, which
     provides a context for the data that the method can access.

     Each class has its own namespace containing things that  are
     common  to all objects which belong to the class.  For exam-
     ple, "common" data members are shared by all objects in  the
     class.   They  are  global variables that exist in the class
     namespace, but since they are included in the class  defini-
     tion,  they  need  not be declared using the global command;
     they are automatically available to any  code  executing  in
     the  class context.  A class can also create ordinary global
     variables, but these must be declared using the global  com-
     mand each time they are used.
     Classes  can  also  have  ordinary  procedures  declared  as
     "procs".  Within another class method or proc, a proc can be
     invoked like any other command-simply  by  using  its  name.
     From  any other context, the procedure name should be quali-
     fied with the class namespace like "className::proc".  Class
     procs  execute  in  the  class  context,  and therefore have
     automatic access to all  "common"  data  members.   However,
     they  cannot  access object-specific "variables", since they
     are invoked without reference to any specific object.   They
     are  usually used to perform generic operations which affect
     all objects belonging to the class.

     Each of the elements in a class can  be  declared  "public",
     "protected"  or  "private".  Public elements can be accessed
     by the class, by derived classes (other classes that inherit
     this  class),  and  by  external clients that use the class.
     Protected elements can be accessed  by  the  class,  and  by
     derived  classes.   Private  elements are only accessible in
     the class where they are defined.

     The "public" elements within a class define its interface to
     the  external  world.   Public methods define the operations
     that can be used to manipulate an object.  Public  variables
     are  recognized  as configuration options by the "configure"
     and "cget" methods that are built into each class.  The pub-
     lic  interface  says  what  an object will do but not how it
     will do it.  Protected and private members, along  with  the
     bodies  of  class methods and procs, provide the implementa-
     tion details.  Insulating  the  application  developer  from
     these  details leaves the class designer free to change them
     at any time, without warning, and without affecting programs
     that  rely on the class.  It is precisely this encapsulation
     that makes object-oriented programs easier to understand and
     maintain.

     The fact that [incr Tcl] objects look like Tk widgets is  no
     accident.  [incr Tcl] was designed this way, to blend natur-
     ally into a Tcl/Tk application.  But [incr Tcl] extends  the
     Tk  paradigm  from  being merely object-based to being fully
     object-oriented.  An object-oriented system supports inheri-
     tance,  allowing classes to share common behaviors by inher-
     iting them from an ancestor or base class.   Having  a  base
     class  as  a common abstraction allows a programmer to treat
     related classes in a similar manner.  For example, a toaster
     and a blender perform different (specialized) functions, but
     both  share  the  abstraction  of  being   appliances.    By
     abstracting  common behaviors into a base class, code can be
     shared rather than copied.   The  resulting  application  is
     easier  to  understand  and  maintain,  and  derived classes
     (e.g., specialized appliances) can be added or removed  more
     easily.

     This description was merely  a  brief  overview  of  object-
     oriented programming and [incr Tcl].  A more tutorial intro-
     duction is presented in the paper included with this distri-
     bution.   See the class command for more details on creating
     and using classes.

NAMESPACES

     [incr Tcl] now includes a complete  namespace  facility.   A
     namespace  is  a collection of commands and global variables
     that is kept apart from the usual global scope.  This allows
     Tcl  code libraries to be packaged in a well-defined manner,
     and prevents unwanted interactions with other libraries.   A
     namespace  can  also have child namespaces within it, so one
     library can contain its  own  private  copy  of  many  other
     libraries.   A namespace can also be used to wrap up a group
     of related classes.  The global scope (named  "::")  is  the
     root  namespace for an interpreter; all other namespaces are
     contained within it.

     See the namespace command for details on creating and  using
     namespaces.

MEGA-WIDGETS

     Mega-widgets are high-level  widgets  that  are  constructed
     using  Tk  widgets as component parts, usually without any C
     code.  A fileselectionbox, for example, may have a few list-
     boxes,  some  entry widgets and some control buttons.  These
     individual widgets are put together in a way that makes them
     act like one big widget.

     [incr Tk] is a framework for building mega-widgets.  It uses
     [incr Tcl]  to  support  the  object paradigm, and adds base
     classes which provide default widget behaviors.  See the itk
     man page for more details.

     [incr Widgets] is a  library  of  mega-widgets  built  using
     [incr Tk].   It  contains  more  than  30  different  widget
     classes that can be used right  out  of  the  box  to  build
     Tcl/Tk applications.  Each widget class has its own man page
     describing the features available.

KEYWORDS

     class, object, object-oriented, namespace, mega-widget
itcl2.2/html/itcl/itclUserCmds.html100666 1751 0 1433 6423554635 16237 0ustar kunkeewheel
itcl User Commands
itcl User Commands
itcl2.2/html/itcl/itcl_class.n.html100666 1751 0 61114 6423554635 16234 0ustar kunkeewheel itcl User Commands - itcl_class

itcl User Commands - itcl_class

NAME

     itcl_class - create a class of objects (obsolete)

SYNOPSIS

     itcl_class className {
         inherit baseClass ?baseClass...?
         constructor args ?init? body
         destructor body
         method name args body
         proc name args body
         public varName ?init? ?config?
         protected varName ?init?
         common varName ?init?
     }

     className objName ?args...?
     className #auto ?args...?
     className :: proc ?args...?

     objName method ?args...?

     Commands available within class methods/procs:
     global varName ?varName...?
     previous command ?args...?
     virtual command ?args...?

DESCRIPTION

     This command is considered obsolete,  but  is  retained  for
     backward-compatibility  with earlier versions of [incr Tcl].
     It has been replaced by the class command, which  should  be
     used for any new development.


     itcl_class className definition
          Provides the definition for a  class  named  className.
          If  className  is  already  defined,  then this command
          returns an error.  If the class definition is  success-
          fully  parsed,  className  becomes  a  command  in  the
          current namespace context,  handling  the  creation  of
          objects and providing access to class scope.  The class
          definition is evaluated as a series of  Tcl  statements
          that  define elements within the class.  In addition to
          the usual commands, the following class definition com-
          mands are recognized:

          inherit baseClass ?baseClass...?
               Declares one or more  base  classes,  causing  the
               current  class  to  inherit their characteristics.
               Classes must  have  been  defined  by  a  previous
               itcl_class  command,  or  must be available to the
               auto-loading facility (see "AUTO-LOADING"  below).
               A single class definition can contain no more than
               one inherit command.

               When the same member name appears in two  or  more
               base classes, the base class that appears first in
               the inherit list takes precedence.   For  example,
               if classes "Foo" and "Bar" both contain the member
               "x", then the "inherit" statement:

                   inherit Foo Bar

               allows "Foo::x" to be accessed simply as  "x"  but
               forces  "Bar::x"  (and all other inherited members
               named "x") to be referenced  with  their  explicit
               "class::member" name.

          constructor args ?init? body
               Declares the argument list and body used  for  the
               constructor,  which is automatically invoked when-
               ever an object is created.   Before  the  body  is  |
               executed,  the  optional init statement is used to  |
               invoke any base class  constructors  that  require  |
               arguments.   Variables  in  the args specification  |
               can be accessed in the  init  code  fragment,  and  |
               passed to base class constructors.  After evaluat-  |
               ing the init statement, any base  class  construc-  |
               tors  that  have  not  been  executed  are invoked  |
               without arguments.  This  ensures  that  all  base  |
               classes are fully constructed before the construc-  |
               tor body is executed.  If construction is success-
               ful,  the  constructor  always  returns the object
               name-regardless of how the body is defined-and the
               object  name  becomes  a  command  in  the current
               namespace  context.   If  construction  fails,  an
               error message is returned.

          destructor body
               Declares the body used for the  destructor,  which
               is  automatically  invoked  whenever  an object is
               deleted.  If the  destructor  is  successful,  the
               object  data  is  destroyed and the object name is
               removed as a command  from  the  interpreter.   If
               destruction  fails,  an  error message is returned
               and the object remains.

               When an object is destroyed, all destructors in  a  |
               class hierarchy are invoked in order from most- to  |
               least-specific.   This  is  the  order  that   the  |
               classes   are  reported  by  the  "info  heritage"  |
               command, and it is exactly  the  opposite  of  the  |
               default constructor order.

          method name args body
               Declares a method called  name  with  an  argument
               list  args and a body of Tcl statements.  A method
               is just like the usual Tcl "proc" except  that  it
               has  transparent  access  to object-specific vari-  |
               ables, as well as common  variables.   Within  the
               class  scope,  a  method  can  be invoked like any
               other command-simply by using its  name.   Outside
               of  the  class scope, the method name must be pre-
               faced by an object name.  Methods in a base  class
               that  are redefined in the current class or hidden
               by another base class  can  be  explicitly  scoped
               using the "class::method" syntax.

          proc name args body
               Declares a proc called name with an argument  list
               args  and  a  body  of  Tcl statements.  A proc is
               similar to a method, except that it can be invoked
               without referring to a specific object, and there-
               fore has access only to common variables - not  to  |
               object-specific variables declared with the public  |
               and protected commands.  Within the class scope, a
               proc  can be invoked like any other command-simply
               by using its name.  In any  other  namespace  con-
               text,  the  proc is invoked using a qualified name
               like "className::proc".  Procs  in  a  base  class
               that are redefined in the current class, or hidden
               by another base class, can also  be  accessed  via
               their qualified name.

          public varName ?init? ?config?
               Declares a public variable named varName.   Public
               variables  are visible in methods within the scope
               of their class and any derived  class.   In  addi-
               tion,  they  can  be modified outside of the class
               scope using the special "config"  formal  argument
               (see  "ARGUMENT  LISTS"  above).   If the optional
               init is specified, it is used as the initial value
               of  the variable when a new object is created.  If
               the optional config command is  specified,  it  is
               invoked whenever a public variable is modified via
               the "config" formal argument; if the  config  com-
               mand  returns  an  error,  the  public variable is
               reset to its value before configuration,  and  the
               method   handling  the  configuration  returns  an
               error.

          protected varName ?init?
               Declares  a  protected  variable  named   varName.
               Protected  variables are visible in methods within
               the scope of their class and  any  derived  class,
               but cannot be modified outside of the class scope.
               If the optional init is specified, it is  used  as
               the  initial  value  of  the  variable  when a new
               object  is  created.   Initialization  forces  the
               variable  to  be a simple scalar value; uninitial-
               ized variables, on the other hand, can be used  as
               arrays.   All  objects  have  a built-in protected
               variable named "this" which is initialized to  the
               instance name for the object.

          common varName ?init?
               Declares a common variable named varName.   Common
               variables are shared among all objects in a class.
               They are visible in methods and procs in the scope
               of  their  class and any derived class, but cannot
               be modified outside of the class  scope.   If  the
               optional init is specified, it is used as the ini-
               tial value of the variable.  Initialization forces
               the  variable  to be a simple scalar value; unini-
               tialized variables, on the other hand, can be used
               as arrays.

               Once a common variable has been declared,  it  can
               be  configured  using ordinary Tcl code within the
               class definition.  This facility  is  particularly
               useful  when the initialization of the variable is
               non-trivial-when the variable contains an array of
               values, for example:

                   itcl_class Foo {
                        .
                        .
                       common boolean
                       set boolean(true) 1
                       set boolean(false) 0
                   }

CLASS USAGE

     When a class definition has been loaded (or  made  available
     to  the  auto-loader),  the class name can be used as a com-
     mand.

     className objName ?args...?
          Creates a new object in class className with  the  name
          objName.   Remaining  arguments  are passed to the con-
          structor.  If construction is  successful,  the  object
          name is returned and this name becomes a command in the
          current namespace  context.   Otherwise,  an  error  is
          returned.

     className #auto ?args...?
          Creates  a  new  object  in  class  className  with  an
          automatically  generated  name.   Names are of the form
          className<number>, where the className part is modified  |
          to  start with a lowercase letter.  In class "Toaster",  |
          for example, the "#auto"  specification  would  produce  |
          names toaster0, toaster1, etc.  Remaining arguments are
          passed to the constructor.  If construction is success-
          ful,  the object name is returned and this name becomes
          a command in the current namespace context.  Otherwise,
          an error is returned.

     className  ::  proc ?args...?
          Used outside of the class scope to invoke a class  proc
          named  proc.   Class procs are like ordinary Tcl procs,
          except that they are executed in the scope of the class
          and  therefore  have  transparent access to common data
          members.

          Notice  that,  unlike  any  other  scope  qualifier  in  |
          [incr Tcl],  the  "::"   shown  above  is surrounded by  |
          spaces.  This is unnecessary  with  the  new  namespace  |
          facility,  and  is considered obsolete.  The capability  |
          is  still  supported,  however,  to  provide  backward-  |
          compatibility with earlier versions.

OBJECT USAGE

     objName method ?args...?
          Invokes a method named method to operate on the  speci-
          fied  object.   Remaining  arguments  are passed to the
          method.  The method name can  be  "constructor",  "des-
          tructor", any method name appearing in the class defin-
          ition, or any of the following built-in methods.

BUILT-IN METHODS

     objName isa className
          Returns non-zero if the given className can be found in
          the object's heritage, and zero otherwise.

     objName delete
          Invokes the destructor associated with an  object.   If
          the  destructor is successful, data associated with the
          object is deleted and objName is removed as  a  command
          from   the  interpreter.   Returns  the  empty  string,
          regardless of the destructor body.

          The built-in delete method has  been  replaced  by  the  |
          "delete object" command in the global namespace, and is  |
          considered   obsolete.    The   capability   is   still  |
          supported,  however,  to provide backward-compatibility  |
          with earlier versions.

     objName info option ?args...?
          Returns information related to the class definition  or
          to  a  particular  object  named  objName.   The option
          parameter includes the following things, as well as the
          options recognized by the usual Tcl "info" command:

          objName info class
               Returns the name of the  most-specific  class  for  |
               object objName.

          objName info inherit
               Returns the list of  base  classes  as  they  were
               defined  in  the  "inherit"  command,  or an empty
               string if this class has no base classes.

          objName info heritage
               Returns the current class name and the entire list
               of  base  classes  in  the  order  that  they  are
               traversed for member lookup  and  object  destruc-
               tion.

          objName info method ?methodName? ?-args? ?-body?
               With no arguments, this command returns a list  of
               all class methods.  If methodName is specified, it
               returns information for  a  specific  method.   If
               neither  of  the  optional -args or -body flags is
               specified,  a  complete   method   definition   is
               returned as a list of three elements including the
               method name, argument list and  body.   Otherwise,
               the  requested information is returned without the
               method name.  If the methodName is not recognized,
               an empty string is returned.

          objName info proc ?procName? ?-args? ?-body?
               With no arguments, this command returns a list  of
               all  class  procs.   If  procName is specified, it
               returns information for a specific proc.  If  nei-
               ther  of  the  optional  -args  or  -body flags is
               specified, a complete proc definition is  returned
               as  a  list  of  three elements including the proc
               name, argument  list  and  body.   Otherwise,  the
               requested information is returned without the proc
               name.  If the procName is not recognized, an empty
               string is returned.

          objName info public ?varName? ?-init? ?-value? ?-
               config?
               With no arguments, this command returns a list  of
               all public variables.  If varName is specified, it
               returns information for a  specific  public  vari-
               able.   If  none  of the optional -init, -value or
               -config flags are specified, all available  infor-
               mation  is  returned  as  a  list of four elements
               including  the  variable  name,   initial   value,
               current value, and configuration commands.  Other-
               wise,  the  requested  information   is   returned
               without  the variable name.  If the varName is not
               recognized, an empty string is returned.

          objName info protected ?varName? ?-init? ?-value?
               With no arguments, this command returns a list  of
               all protected variables.  If varName is specified,
               it returns information for  a  specific  protected
               variable.   If  neither  of  the optional -init or
               -value flags is specified, all available  informa-
               tion  is  returned  as  a  list  of three elements
               including the variable  name,  initial  value  and
               current  value.  Otherwise, the requested informa-
               tion is returned without the  variable  name.   If
               the  varName is not recognized, an empty string is
               returned.

          objName info common ?varName? ?-init? ?-value?
               With no arguments, this command returns a list  of
               all common variables.  If varName is specified, it
               returns information for a  specific  common  vari-
               able.   If neither of the optional -init or -value
               flags is specified, all available  information  is
               returned as a list of three elements including the
               variable name, initial value  and  current  value.
               Otherwise,  the  requested information is returned
               without the variable name.  If the varName is  not
               recognized, an empty string is returned.

OTHER BUILT-IN COMMANDS

     The following commands are also available within  the  scope
     of  each class.  They cannot be accessed from outside of the
     class as proper methods or procs; rather,  they  are  useful
     inside the class when implementing its functionality.

     global varName ?varName...?
          Creates a link to one or more global variables  in  the
          current  namespace  context.  Global variables can also
          be accessed in other namespaces by including  namespace
          qualifiers in varName.  This is useful when communicat-
          ing with Tk widgets that rely on global variables.

     previous command ?args...?
          Invokes command in the scope of the most immediate base
          class (i.e., the "previous" class) for the object.  For  |
          classes using single inheritance, this facility can  be
          used  to  avoid hard-wired base class references of the
          form "class::command", making code easier to  maintain.
          For  classes using multiple inheritance, the utility of
          this function is dubious.  If the class at the relevant
          scope has no base class, an error is returned.

     virtual command ?args...?
          Invokes command in the scope of the most-specific class  |
          for  the  object.   The  methods  within  a  class  are  |
          automatically virtual; whenever an  unqualified  method  |
          name  is  used,  it  always refers to the most-specific  |
          implementation for that method.  This function provides  |
          a way of evaluating code fragments in a base class that  |
          have access to the  most-specific  object  information.  |
          It  is  useful,  for example, for creating base classes  |
          that can  capture  and  save  an  object's  state.   It  |
          inverts  the  usual notions of object-oriented program-  |
          ming, however, and should therefore be used sparingly.

AUTO-LOADING

     Class definitions need not be loaded explicitly; they can be
     loaded  as  needed  by  the usual Tcl auto-loading facility.
     Each directory containing class definition files should have
     an  accompanying  "tclIndex"  file.   Each line in this file
     identifies a Tcl procedure or  [incr Tcl]  class  definition
     and the file where the definition can be found.

     For example, suppose a directory  contains  the  definitions
     for  classes "Toaster" and "SmartToaster".  Then the "tclIn-
     dex" file for this directory would look like:

         # Tcl autoload index file, version 2.0 for [incr Tcl]
         # This file is generated by the "auto_mkindex" command
         # and sourced to set up indexing information for one or
         # more commands.  Typically each line is a command that
         # sets an element in the auto_index array, where the
         # element name is the name of a command and the value is
         # a script that loads the command.

         set auto_index(::Toaster) "source $dir/Toaster.itcl"
         set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"

     The auto_mkindex command is used to automatically
     generate "tclIndex" files.

 The auto-loader must be made aware of this directory by  append-
 ing  the  directory name to the "auto_path" variable.  When this
 is in place, classes will be auto-loaded as needed when used  in
 an application.

KEYWORDS

     class, object, object-oriented
itcl2.2/html/itcl/itcl_info.n.html100666 1751 0 6211 6423554635 16037 0ustar kunkeewheel itcl User Commands - itcl_info

itcl User Commands - itcl_info

NAME

     itcl_info  -  query  info  regarding  classes  and   objects
     (obsolete)

SYNOPSIS

     itcl_info classes ?pattern?
     itcl_info  objects  ?pattern?   ?-class   className?   ?-isa
     className?

DESCRIPTION

     This command is considered obsolete,  but  is  retained  for
     backward-compatibility  with earlier versions of [incr Tcl].
     It has  been  replaced  by  the  "info  classes"  and  "info
     objects" commands, which should be used for any new develop-
     ment.


     The following commands are available in the global namespace
     to  query  information  about  classes and objects that have
     been created.

     itcl_info classes ?pattern?
          Returns a list of  classes  available  in  the  current
          namespace  context.   If a class belongs to the current  |
          namespace context, its simple name is reported;  other-  |
          wise,  if  a  class is imported from another namespace,  |
          its fully-qualified name is reported.

          If the optional pattern is specified, then the reported
          names  are  compared  using  the  rules  of the "string
          match" command, and only matching names are reported.

     itcl_info objects ?pattern? ?-class className? ?-
          isa className?
          Returns a list of  objects  available  in  the  current
          namespace context.  If an object belongs to the current  |
          namespace context, its simple name is reported;  other-  |
          wise,  if an object is imported from another namespace,  |
          its fully-qualified access command is reported.

          If the optional pattern is specified, then the reported
          names  are  compared  using  the  rules  of the "string
          match" command, and only matching names  are  reported.
          If  the  optional "-class" parameter is specified, this
          list is restricted to objects whose most-specific class
          is  className.   If  the  optional  "-isa" parameter is
          specified, this list is further restricted  to  objects
          having the given className anywhere in their heritage.

KEYWORDS

     class, object, object-oriented
itcl2.2/html/itcl/itclvars.n.html100666 1751 0 13532 6423554635 15744 0ustar kunkeewheel itcl User Commands - itclvars

itcl User Commands - itclvars

NAME

     itclvars - variables used by [incr Tcl]

DESCRIPTION

     The following  global  variables  are  created  and  managed
     automatically by the [incr Tcl] library.  Except where noted
     below, these variables should normally be treated  as  read-
     only by application-specific code and by users.

     itcl::library
          When an interpreter is created, [incr Tcl]  initializes
          this  variable to hold the name of a directory contain-
          ing the system library of [incr Tcl] scripts.  The ini-
          tial   value   of   itcl::library   is   set  from  the
          ITCL_LIBRARY environment variable if it exists, or from
          a compiled-in value otherwise.

     itcl::patchLevel
          When an interpreter is created, [incr Tcl]  initializes
          this  variable  to  hold  the  current  patch level for
          [incr Tcl].  For example, the value  "2.0p1"  indicates
          [incr Tcl]  version  2.0  with the first set of patches
          applied.

     itcl::purist
          When an interpreter is created  containing  Tcl/Tk  and
          the  [incr Tcl]  namespace facility, this variable con-
          trols  a  "backward-compatibility"  mode   for   widget
          access.

          In vanilla Tcl/Tk, there is a single pool of  commands,
          so  the  access command for a widget is the same as the
          window  name.   When  a  widget  is  created  within  a
          namespace,  however, its access command is installed in
          that namespace, and should be accessed outside  of  the
          namespace using a qualified name.  For example,

              namespace foo {
                  namespace bar {
                      button .b -text "Testing"
                  }
              }
              foo::bar::.b configure -background red
              pack .b

          Note that the window name ".b" is still  used  in  con-
          junction with commands like pack and destroy.  However,
          the access command for  the  widget  (i.e.,  name  that
          appears  as  the first argument on a command line) must
          be more specific.

          The "winfo command" command can be used  to  query  the
          fully-qualified  access  command for any widget, so one
          can write:

              [winfo command .b] configure -background red

          and this is good practice  when  writing  library  pro-
          cedures.   Also,  in conjunction with the bind command,
          the "%q" field can be used in  place  of  "%W"  as  the
          access command:

              bind Button <Key-Return> {%q flash; %q invoke}

          While this behavior makes sense from the standpoint  of
          encapsulation,  it causes problems with existing Tcl/Tk
          applications.  Many existing applications  are  written
          with  bindings  that use "%W".  Many library procedures
          assume that the window name is the access command.

          The  itcl::purist   variable   controls   a   backward-
          compatibility  mode.  By default, this variable is "0",
          and the window name can be used as an access command in
          any  context.   Whenever the unknown procedure stumbles
          across a widget name, it simply uses "winfo command" to
          determine  the appropriate command name.  If this vari-
          able is set to "1", this backward-compatibility mode is
          disabled.   This  gives better encapsulation, but using
          the window name as  the  access  command  may  lead  to
          "invalid command" errors.

     itcl::version
          When an interpreter is created, [incr Tcl]  initializes
          this  variable  to  hold the version number of the form
          x.y.  Changes to x represent major changes  with  prob-
          able incompatibilities and changes to y represent small
          enhancements and bug fixes that retain backward  compa-
          tibility.

KEYWORDS

     itcl, variables
itcl2.2/html/itcl/local.n.html100666 1751 0 4465 6423554635 15174 0ustar kunkeewheel itcl User Commands - local

itcl User Commands - local

NAME

     local - create an object local to a procedure

SYNOPSIS

     local className objName ?arg arg ...?

DESCRIPTION

     The local command creates an [incr Tcl] object that is local
     to  the  current call frame.  When the call frame goes away,
     the object is automatically deleted.  This command is useful
     for creating objects that are local to a procedure.

     As a side effect, this  command  creates  a  variable  named
     "itcl-local-xxx",  where  xxx is the name of the object that
     is created.  This variable detects when the  call  frame  is
     destroyed and automatically deletes the associated object.

EXAMPLE

     In the following example, a simple "counter" object is  used
     within  the  procedure  "test".  The counter is created as a
     local object, so it is automatically deleted each  time  the
     procedure  exits.   The  puts  statements  included  in  the
     constructor/destructor show the object coming and  going  as
     the procedure is called.

         class counter {
             private variable count 0
             constructor {} {
                 puts "created: $this"
             }
             destructor {
                 puts "deleted: $this"
             }

             method bump {{by 1}} {
                 incr count $by
             }
             method get {} {
                 return $count
             }
         }

         proc test {val} {
             local counter x
             for {set i 0} {$i < $val} {incr i} {
                 x bump
             }
             return [x get]
         }

         set result [test 5]
         puts "test: $result"

         set result [test 10]
         puts "test: $result"

         puts "objects: [info objects]"

KEYWORDS

     class, object, procedure
itcl2.2/html/ListOCmds.html100666 1751 0 142 6423554634 14517 0ustar kunkeewheel

List of Commands

itcl2.2/html/TclTkHeader.html100666 1751 0 333 6423554634 15012 0ustar kunkeewheel
Tcl/Tk Man Page Viewer

by Jim Ingham

Man page formatting man2html
itcl2.2/html/TclTkMainList.html100666 1751 0 1305 6423554634 15362 0ustar kunkeewheel 
Tcl User Cmds
Tcl C API
Tk User Cmds
Tk C API
Itcl User Cmds
Itk User Cmds
Iwidgets User Cmds
itcl2.2/html/index.html100666 1751 0 2026 6423554634 14010 0ustar kunkeewheel Tcl/Tk Man Pages itcl2.2/html/itk/ 40755 1751 0 0 6423554636 12503 5ustar kunkeewheelitcl2.2/html/itk/CVS/ 40755 1751 0 0 6423570012 13120 5ustar kunkeewheelitcl2.2/html/itk/CVS/Root100644 1751 0 26 6423554635 14036 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/html/itk/CVS/Repository100644 1751 0 11 6423674263 15264 0ustar kunkeewheel/usr/cvs itcl2.2/html/itk/CVS/Entries100644 1751 0 543 6423570012 14533 0ustar kunkeewheel/Archetype.n.html/1.1.1.1/Thu Oct 23 04:59:09 1997// /Toplevel.n.html/1.1.1.1/Thu Oct 23 04:59:09 1997// /Widget.n.html/1.1.1.1/Thu Oct 23 04:59:10 1997// /itk.n.html/1.1.1.1/Thu Oct 23 04:59:10 1997// /itkUserCmds.html/1.1.1.1/Thu Oct 23 04:59:10 1997// /itkvars.n.html/1.1.1.1/Thu Oct 23 04:59:10 1997// /usual.n.html/1.1.1.1/Thu Oct 23 04:59:10 1997// itcl2.2/html/itk/Archetype.n.html100666 1751 0 43313 6423554635 15675 0ustar kunkeewheel itk User Commands - Archetype

itk User Commands - Archetype

NAME

     Archetype - base class for all [incr Tk] mega-widgets

INHERITANCE

     none

WIDGET-SPECIFIC OPTIONS

     Name:           clientData
     Class:          ClientData
     Command-Line Switch:           -clientdata

          This does not affect the widget operation in  any  way.
          It is simply a hook that clients can use to store a bit
          of data with each widget.  This can come in handy  when
          using widgets to build applications.

DESCRIPTION

     The Archetype class is the basis  for  all  [incr Tk]  mega-
     widgets.   It  keeps track of component widgets and provides
     methods like "configure" and "cget" that are used to  access
     the  composite configuration options.  Each component widget
     must be registered with the Archetype base class  using  the
     "itk_component   add"   method.    When   the  component  is
     registered, its configuration options  are  integrated  into
     the  composite  option list.  Configuring a composite option
     like "-background" causes all of the internal components  to
     change their background color.

     It is not used as a widget by itself, but is used as a  base
     class  for  more specialized widgets.  The Widget base class
     inherits from Archetype, and adds a Tk frame which  acts  as
     the  "hull"  for  the  mega-widget.  The Toplevel base class
     inherits from Archetype, but adds a Tk toplevel  which  acts
     as the "hull".

     Each derived class must  invoke  the  itk_initialize  method
     within  its  constructor,  so  that all options are properly
     integrated and initialized in the composite list.

PUBLIC METHODS

     The following methods are provided  to  support  the  public
     interface of the mega-widget.

     pathName cget option
          Returns the current value of the  configuration  option
          given by option.
          In this case, option refers to a  composite  configura-
          tion option for the mega-widget.  Individual components
          integrate their own configuration options onto the com-
          posite   list   when   they   are   registered  by  the
          "itk_component add" method.

     pathName component ?name? ?command arg arg ...?
          Used to query or  access  component  widgets  within  a
          mega-widget.  With no arguments, this returns a list of
          symbolic names for component widgets that are  accessi-
          ble in the current scope.  The symbolic name for a com-
          ponent is established when  it  is  registered  by  the
          "itk_component  add" method.  Note that component widg-
          ets obey any public/protected/private  access  restric-
          tion that is in force when the component is created.

          If a symbolic name is specified,  this  method  returns
          the window path name for that component.

          Otherwise, the command and any remaining arg  arguments
          are  invoked as a method on the component with the sym-
          bolic name name.  This provides a well-defined  way  of
          accessing   internal   components  without  relying  on
          specific window path names, which are really details of
          the implementation.

     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  correspond-
          ing  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.

          In this case, the options refer to composite configura-
          tion  options  for  the  mega-widget.   Individual com-
          ponents integrate their own configuration options  onto
          the  composite  list  when  they  are registered by the
          "itk_component add" method.

PROTECTED METHODS

     The following methods are used in derived classes as part of
     the implementation for a mega-widget.

     itk_component add name createCmds ?optionCmds?
          Creates a component widget by executing the  createCmds
          argument  and registers the new component with the sym-
          bolic name name.  The createCmds code can  contain  any
          number  of commands, but it must return the window path
          name for the new component widget.

          The optionCmds script contains commands  that  describe
          how  the  configuration  options  for the new component
          should be integrated into the composite  list  for  the
          mega-widget.   It can contain any of the following com-
          mands:

          ignore option ?option option ...?
               Removes one or more configuration options from the
               composite   list.   All  options  are  ignored  by
               default, so the ignore command  is  only  used  to
               negate  the  effect  of  a previous keep or rename
               command.  This is useful, for  example,  when  the
               some  of  the  options  added by the usual command
               should not apply to a  particular  component,  and
               need to be ignored.

          keep option ?option option ...?
               Integrates one or more configuration options  into
               the  composite  list,  keeping  the name the same.
               Whenever the mega-widget option is configured, the
               new  value  is  also  applied  to the current com-
               ponent.  Options like "-background" and  "-cursor"
               are commonly found on the keep list.

          rename option switchName resourceName resourceClass
               Integrates the configuration option into the  com-
               posite  list  with  a  different name.  The option
               will be called switchName on the  composite  list.
               It  will  also  be  modified by setting values for
               resourceName and resourceClass in the X11 resource
               database.   The  "-highlightbackground"  option is
               commonly renamed to "-background",  so  that  when
               the mega-widget background changes, the background
               of the focus ring will change as well.

          usual ?tag?
               Finds the usual option-handling commands  for  the
               specified  tag name and executes them.  If the tag
               is not specified, then the widget  class  name  is
               used as the tag name.  The "usual" option-handling
               commands are registered via the usual command.

     If  the  optionCmds  script  is  not  specified,  the  usual
     option-handling  commands  associated  with the class of the
     component widget are used by default.

     itk_component delete name ?name name ...?
          Removes the component widget  with  the  symbolic  name
          name  from  the mega-widget.  The component widget will
          still exist, but it will no longer be accessible  as  a
          component  of the mega-widget.  Also, any options asso-
          ciated with the component are removed from  the  compo-
          site option list.

          Note that you can destroy a component using the destroy
          command, just as you would destroy any Tk widget.  Com-
          ponents  automatically  detach  themselves  from  their
          mega-widget  parent  when  destroyed, so "itk_component
          delete" is rarely used.


     itk_initialize ?option value option value...?
          This method must be invoked within the constructor  for
          each  class  in a mega-widget hierarchy.  It makes sure
          that all options are properly integrated into the  com-
          posite  option list, and synchronizes all components to
          the initial option values.  It is usually invoked  near
          the  bottom  of  the  constructor,  after all component
          widgets have been added.

          If any option/value pairs are specified, they  override
          settings  determined  from  the  X11 resource database.
          The arguments to the  constructor  are  usually  passed
          along to this method as follows:

              class MyWidget {
                  inherit Widget

                  constructor {args} {
                      .
                      .
                      .
                      eval itk_initialize $args
                  }
              }



     itk_option add optName ?optName optName ...?
          Adds one or more options to the composite  option  list
          for  a  mega-widget.  Here, optName can have one of the
          following forms:

          component.option
               Accesses an option belonging to a  component  with
               the  symbolic  name component.  The option name is
               specified without a leading "-" sign.

          className::option
               Accesses an  option  defined  by  the  "itk_option
               define"  command  in  class className.  The option
               name is specified without a leading "-" sign.

     Options are normally integrated into  the  composite  option
     list  when a component widget is first created.  This method
     can be used to add options at a later  time.   For  example,
     the  Widget  and  Toplevel  base  classes keep only the bare
     minimum options for their "hull" component:  -background and
     -cursor.   A  derived  class can override this decision, and
     add options that control the border of the "hull"  component
     as well:

         class MyWidget {
             inherit Widget

             constructor {args} {
                 itk_option add hull.borderwidth hull.relief

                 itk_component add label {
                     label $itk_interior.l1 -text "Hello World!"
                 }
                 pack $itk_component(label)

                 eval itk_initialize $args
             }
         }

?config?

     itk_option  define  switchName  resourceName  resourceClass  init
          This  command is used at the level of the class defini-
          tion to define a synthetic mega-widget option.   Within
          the  configure  and cget methods, this option is refer-
          enced by switchName, which must start with a "-"  sign.
          It  can  also be modified by setting values for resour-
          ceName and resourceClass in the X11 resource  database.
          The  init value string is used as a last resort to ini-
          tialize the option if no other value can be  used  from
          an  existing  option,  or queried from the X11 resource
          database.  If any config code is specified, it is  exe-
          cuted whenever the option is modified via the configure
          method.  The config code can also be specified  outside
          of the class definition via the configbody command.

          In the following  example,  a  synthetic  "-background"
          option  is  added  to  the  class, so that whenever the
          background changes, the new value is reported to  stan-
          dard  output.   Note  that  this  synthetic  option  is
          integrated with the rest of the  "-background"  options
          that have been kept from component widgets:

              class MyWidget {
                  inherit Widget
                  constructor {args} {
                      itk_component add label {
                          label $itk_interior.l1 -text "Hello World!"
                      }
                      pack $itk_component(label)

                      eval itk_initialize $args
                  }
                  itk_option define -background background Background #d9d9d9 {
                      puts "new background: $itk_option(-background)"
                  }
              }



     itk_option remove optName ?optName optName ...?
          Removes one or more options from the  composite  option
          list  for a mega-widget.  Here, optName can have one of
          the forms described above for the "itk_option add" com-
          mand.

          Options are  normally  integrated  into  the  composite
          option  list  when a component widget is first created.
          This method can be used to remove options  at  a  later
          time.   For  example,  a  derived class can override an
          option defined in a base class by removing and redefin-
          ing the option:

              class Base {
                  inherit Widget
                  constructor {args} {
                      eval itk_initialize $args
                  }

                  itk_option define -foo foo Foo "" {
                      puts "Base: $itk_option(-foo)"
                  }
              }

              class Derived {
                  inherit Base

                  constructor {args} {
                      itk_option remove Base::foo
                      eval itk_initialize $args
                  }
                  itk_option define -foo foo Foo "" {
                      puts "Derived: $itk_option(-foo)"

                  }
              }

          Without the "itk_option remove" command, the code frag-
          ments  for both of the "-foo" options would be executed
          each time the composite "-foo"  option  is  configured.
          In   the   example   above,  the  Base::foo  option  is
          suppressed in all Derived class widgets,  so  only  the
          Derived::foo option remains.

PROTECTED VARIABLES

     Derived classes can find useful information in the following
     protected variables.

     itk_component(name)
          The "itk_component" array returns the real window  path
          name  for  a  component  widget  with the symbolic name
          name.  The same information can be  queried  using  the
          component  method,  but  accessing this array is faster
          and more convenient.

     itk_interior
          This variable contains the name of the window that acts
          as a parent for internal components.  It is initialized
          to the name of the "hull"  component  provided  by  the
          Widget and Toplevel classes.  Derived classes can over-
          ride the initial setting to point to  another  interior
          window to be used for further-derived classes.

     itk_option(option)
          The "itk_option" array returns the current option value
          for  the  composite  widget option named option.  Here,
          the option name should include a leading "-" sign.  The
          same  information can be queried using the cget method,
          but accessing this array is faster and more convenient.

KEYWORDS

     itk, Widget, Toplevel, mega-widget
itcl2.2/html/itk/Toplevel.n.html100666 1751 0 11152 6423554635 15537 0ustar kunkeewheel itk User Commands - Toplevel

itk User Commands - Toplevel

NAME

     Widget - base class for mega-widgets within a frame

INHERITANCE

     itk::Archetype <- itk::Toplevel

STANDARD OPTIONS

     background      cursor

     See the "options" manual entry for details on  the  standard
     options.

WIDGET-SPECIFIC OPTIONS

     Name:   title
     Class:  Title
     Command-Line Switch:    -title

          Sets the title that the window manager displays in  the
          title  bar  above the window.  The default title is the
          null string.

DESCRIPTION

     The Toplevel class inherits everything  from  the  Archetype
     class, and adds a Tk toplevel called the "hull" component to
     represent the body of the  mega-widget.   The  window  class
     name for the hull is set to the most-specific class name for
     the mega-widget.  The protected variable  itk_interior  con-
     tains  the  window  path  name  for  the  "hull"  component.
     Derived classes specialize  this  widget  by  packing  other
     widget components into the hull.

     Since the hull for the Toplevel class is implemented with  a
     Tk  toplevel,  mega-widgets in the Toplevel class have their
     own toplevel window.  This class is used  to  create  dialog
     boxes and other pop-up windows.

COMPONENTS

     Name:           hull
     Class:          Toplevel

          The "hull" component acts as the body  for  the  entire
          mega-widget.  Other components are packed into the hull
          to further specialize the widget.

EXAMPLE


     The following example implements a MessageInfo  mega-widget.
     It  creates  a  pop-up  message that the user can dismiss by
     pushing the "Dismiss" button.

         option add *MessageInfo.title "Notice" widgetDefault

         class MessageInfo {
             inherit itk::Toplevel

             constructor {args} {
                 itk_component add dismiss {
                     button $itk_interior.dismiss -text "Dismiss"                 -command "destroy $itk_component(hull)"
                 }
                 pack $itk_component(dismiss) -side bottom -pady 4

                 itk_component add separator {
                     frame $itk_interior.sep -height 2 -borderwidth 1 -relief sunken
                 }
                 pack $itk_component(separator) -side bottom -fill x -padx 4

                 itk_component add icon {
                     label $itk_interior.icon -bitmap info
                 }
                 pack $itk_component(icon) -side left -padx 8 -pady 8

                 itk_component add infoFrame {
                     frame $itk_interior.info
                 }
                 pack $itk_component(infoFrame) -side left -expand yes             -fill both -padx 4 -pady 4

                 itk_component add message {
                     label $itk_interior.mesg -width 20
                 } {
                     usual
                     rename -text -message message Text
                 }
                 pack $itk_component(message) -expand yes -fill both

                 eval itk_initialize $args

                 after idle [code $this centerOnScreen]
             }

             protected method centerOnScreen {} {
                 update idletasks
                 set wd [winfo reqwidth $itk_component(hull)]
                 set ht [winfo reqheight $itk_component(hull)]
                 set x [expr ([winfo screenwidth $itk_component(hull)]-$wd)/2]
                 set y [expr ([winfo screenheight $itk_component(hull)]-$ht)/2]
                 wm geometry $itk_component(hull) +$x+$y
             }
         }
         usual MessageInfo {
             keep -background -cursor -foreground -font
             keep -activebackground -activeforeground -disabledforeground
             keep -highlightcolor -highlightthickness
         }

         #
         # EXAMPLE:  Create a notice window:
         #
         MessageInfo .m -message "File not found:0usr/local/bin/foo"

KEYWORDS

     itk, Archetype, Widget, mega-widget
itcl2.2/html/itk/Widget.n.html100666 1751 0 10342 6423554636 15171 0ustar kunkeewheel itk User Commands - Widget

itk User Commands - Widget

NAME

     Widget - base class for mega-widgets within a frame

INHERITANCE

     itk::Archetype <- itk::Widget

STANDARD OPTIONS

     background      cursor

     See the "options" manual entry for details on  the  standard
     options.

DESCRIPTION

     The Widget class  inherits  everything  from  the  Archetype
     class,  and  adds  a Tk frame called the "hull" component to
     represent the body of the  mega-widget.   The  window  class
     name for the hull is set to the most-specific class name for
     the mega-widget.  The protected variable  itk_interior  con-
     tains  the  window  path  name  for  the  "hull"  component.
     Derived classes specialize  this  widget  by  packing  other
     widget components into the hull.

     Since the hull for the Widget class is implemented with a Tk
     frame,  mega-widgets  in the Widget class can be packed into
     other frames and toplevels.

COMPONENTS

     Name:           hull
     Class:          Frame

          The "hull" component acts as the body  for  the  entire
          mega-widget.  Other components are packed into the hull
          to further specialize the widget.

EXAMPLE

     The following example implements a simple TextDisplay  mega-
     widget.   It creates a read-only display of text with a text
     widget and a scrollbar.

         option add *TextDisplay.wrap none widgetDefault
         option add *TextDisplay.textBackground ivory widgetDefault
         option add *TextDisplay.width 40 widgetDefault
         option add *TextDisplay.height 10 widgetDefault

         class TextDisplay {
             inherit itk::Widget
             constructor {args} {
                 itk_component add text {
                     text $itk_interior.info -state disabled                 -yscrollcommand [code $itk_interior.sbar set]
                 } {
                     usual
                     keep -tabs -wrap -width -height
                     rename -background -textbackground textBackground Background
                 }
                 pack $itk_component(text) -side left -expand yes -fill both

                 itk_component add scrollbar {
                     scrollbar $itk_interior.sbar                 -command [code $itk_interior.info yview]
                 }
                 pack $itk_component(scrollbar) -side right -fill y

                 eval itk_initialize $args
             }

             public method display {info}
             public method append {info}
         }

         body TextDisplay::display {info} {
             $itk_component(text) configure -state normal
             $itk_component(text) delete 1.0 end
             $itk_component(text) insert 1.0 $info
             $itk_component(text) configure -state disabled
         }

         body TextDisplay::append {info} {
             $itk_component(text) configure -state normal
             $itk_component(text) insert end $info
             $itk_component(text) configure -state disabled
         }

         usual TextDisplay {
             keep -background -cursor -foreground -font
             keep -activebackground -activerelief
             keep -highlightcolor -highlightthickness
             keep -insertbackground -insertborderwidth -insertwidth
             keep -insertontime -insertofftime
             keep -selectbackground -selectborderwidth -selectforeground
             keep -textbackground -troughcolor
         }

         #
         # EXAMPLE:  Display the /etc/passwd file
         #
         TextDisplay .file -background red
         pack .file

         .file display [exec cat /etc/passwd]

KEYWORDS

     itk, Archetype, Widget, mega-widget
itcl2.2/html/itk/itk.n.html100666 1751 0 7107 6423554636 14522 0ustar kunkeewheel itk User Commands - itk

itk User Commands - itk

NAME

     itk - framework for building mega-widgets in Tcl/Tk

DESCRIPTION

     Mega-widgets are high-level  widgets  that  are  constructed
     using  Tk  widgets as component parts, usually without any C
     code.  A fileselectionbox, for example, may have a few list-
     boxes,  some  entry widgets and some control buttons.  These
     individual widgets are put together in a way that makes them
     act like one big widget.  A fileselectionbox mega-widget can
     be created with a command like:

         fileselectionbox .fsb -background blue -foreground white

     Once it has been created, it can be reconfigured with a com-
     mand like:

         .fsb configure -background green -foreground black

     and all of its internal components will change color.   Each
     mega-widget has a set of methods that can be used to manipu-
     late it.  For example, the current selection can be  queried
     from a fileselectionbox like this:

         set fileName [.fsb get]

     In effect, a mega-widget looks and acts exactly  like  a  Tk
     widget, but is considerably easier to implement.

     [incr Tk] is a framework for building mega-widgets.  It uses
     [incr Tcl]  to  support  the  object paradigm, and adds base
     classes which provide default widget behaviors.

     All [incr Tk] widgets are derived from  the  Archetype  base
     class.   This  class manages internal component widgets, and
     provides methods like "configure" and "cget" to access  con-
     figuration options.

     The Widget base class inherits  everything  from  Archetype,
     and  adds a Tk frame which acts as a container for the mega-
     widget.  It is used to build mega-widgets that sit inside of
     other  frames  and  toplevels.  Derived classes create other
     internal components and pack  them  into  the  "hull"  frame
     created by the Widget base class.

     The Toplevel base class inherits everything from  Archetype,
     but  adds  a  Tk  toplevel which acts as a container for the
     mega-widget.  It is used  to  build  mega-widgets,  such  as
     dialog  boxes, that have their own toplevel window.  Derived
     classes create other internal components and pack them  into
     the "hull" toplevel created by the Toplevel base class.

[incr Widgets] LIBRARY

     [incr Widgets]  is  a  mega-widget   library   built   using
     [incr Tk].   It  can  be used right out of the box, and con-
     tains more than 30 different widget classes, including:

     -    fileselectiondialog

     -    tabnotebook

     -    panedwindow

     -    combobox

     -    optionmenu

     -    scrolledlistbox

     -    scrolledframe

     -    messagedialog

     -    and many others...

     The catalog demo in the "iwidgets/demos" directory shows all
     of  the  available widgets in action.  Each widget class has
     its own man page describing the features available.

KEYWORDS

     class, object, object-oriented, mega-widget
itcl2.2/html/itk/itkUserCmds.html100666 1751 0 1047 6423554636 15731 0ustar kunkeewheel
itk User Commands
itk User Commands
itcl2.2/html/itk/itkvars.n.html100666 1751 0 4010 6423554636 15404 0ustar kunkeewheel itk User Commands - itkvars

itk User Commands - itkvars

NAME

     itkvars - variables used by [incr Tk]

DESCRIPTION

     The following  global  variables  are  created  and  managed
     automatically  by the [incr Tk] library.  Except where noted
     below, these variables should normally be treated  as  read-
     only by application-specific code and by users.

     itk::library
          When an interpreter is created,  [incr Tk]  initializes
          this  variable to hold the name of a directory contain-
          ing the system library of [incr Tk] scripts.  The  ini-
          tial  value of itk::library is set from the ITK_LIBRARY
          environment variable if it exists, or from a  compiled-
          in value otherwise.

          When [incr Tk] is added to an interpreter, it  executes
          the  script "init.itk" in this directory.  This script,
          in turn, looks for other script  files  with  the  name
          "init.xxx".   Mega-widget  libraries  will be automati-
          cally  initialized  if  they  install  a  script  named
          "init.xxx"  in  this directory, where "xxx" is the name
          of  the  mega-widget   library.    For   example,   the
          [incr Widgets]     library    installs    the    script
          "init.iwidgets" in this directory.  This script  estab-
          lishes  the "iwidgets" namespace, and sets up autoload-
          ing for all [incr Widgets] commands.

KEYWORDS

     itcl, itk, variables
itcl2.2/html/itk/usual.n.html100666 1751 0 7707 6423554636 15072 0ustar kunkeewheel itk User Commands - usual

itk User Commands - usual

NAME

     usual - access default option-handling commands
          for a mega-widget component

SYNOPSIS

     usual ?tag? ?commands?

DESCRIPTION

     The usual command is used outside  of  an  [incr Tcl]  class
     definition  to  define the usual set of option-handling com-
     mands for a component widget.  Option-handling commands  are
     used  when a component is registered with the Archetype base
     class via the "itk_component add" method.  They specify  how
     the  component's  configuration options should be integrated
     into the composite option list for the mega-widget.  Options
     can be kept, renamed, or ignored, as described in the Arche-
     type man page.

     It is tedious to include the  same  declarations  again  and
     again  whenever  components  are  added.   The usual command
     allows a standard code fragment to be  registered  for  each
     widget  class,  which  is  used  by  default  to  handle the
     options.  All of the standard Tk widgets have usual declara-
     tions  defined  in  the  [incr Tk]  library.   Similar usual
     declarations should be created whenever  a  new  mega-widget
     class is conceived.  Only the most-generic options should be
     included in the usual declaration.

     The tag name is usually the name of a  widget  class,  which
     starts with a capital letter; however, any string registered
     here can be used later with the usual command  described  on
     the Archetype man page.

     If the commands argument is specified, it is associated with
     the  tag string, and can be accessed later via itk_component
     add.

     If only the tag argument is specified,  this  command  looks
     for an existing tag name and returns the commands associated
     with it.  If there are no commands associated with tag, this
     command returns the null string.

     If no arguments are specified, this command returns  a  list
     of all tag names previously registered.

EXAMPLE

     Following is the  usual  declaration  for  the  standard  Tk
     button widget:

         usual Button {
             keep -background -cursor -foreground -font
             keep -activebackground -activeforeground -disabledforeground
             keep -highlightcolor -highlightthickness
             rename -highlightbackground -background background Background
         }

     Only the options that would be common to all  buttons  in  a
     single  mega-widget  are  kept  or renamed.  Options like "-
     text" that would  be  unique  to  a  particular  button  are
     ignored.

KEYWORDS

     itk, Archetype, component, mega-widget
itcl2.2/html/iwidgets2.2.0/ 40755 1751 0 0 6423554641 14107 5ustar kunkeewheelitcl2.2/html/iwidgets2.2.0/CVS/ 40755 1751 0 0 6423570013 14531 5ustar kunkeewheelitcl2.2/html/iwidgets2.2.0/CVS/Root100644 1751 0 26 6423554636 15447 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/html/iwidgets2.2.0/CVS/Repository100644 1751 0 11 6423674264 16675 0ustar kunkeewheel/usr/cvs itcl2.2/html/iwidgets2.2.0/CVS/Entries100644 1751 0 3666 6423570013 16175 0ustar kunkeewheel/buttonbox.n.html/1.1.1.1/Thu Oct 23 04:59:10 1997// /canvasprintbox.n.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /canvasprintdialog.n.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /combobox.n.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /dialog.n.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /dialogshell.n.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /entryfield.n.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /feedback.n.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /fileselectionbox.n.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /fileselectiondialog.n.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /hyperhelp.n.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /iwidgets2.2.0UserCmds.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /labeledwidget.n.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /menubar.n.html/1.1.1.1/Thu Oct 23 04:59:11 1997// /messagedialog.n.html/1.1.1.1/Thu Oct 23 04:59:12 1997// /notebook.n.html/1.1.1.1/Thu Oct 23 04:59:12 1997// /optionmenu.n.html/1.1.1.1/Thu Oct 23 04:59:12 1997// /panedwindow.n.html/1.1.1.1/Thu Oct 23 04:59:12 1997// /promptdialog.n.html/1.1.1.1/Thu Oct 23 04:59:12 1997// /pushbutton.n.html/1.1.1.1/Thu Oct 23 04:59:12 1997// /radiobox.n.html/1.1.1.1/Thu Oct 23 04:59:12 1997// /scrolledcanvas.n.html/1.1.1.1/Thu Oct 23 04:59:12 1997// /scrolledframe.n.html/1.1.1.1/Thu Oct 23 04:59:12 1997// /scrolledhtml.n.html/1.1.1.1/Thu Oct 23 04:59:12 1997// /scrolledlistbox.n.html/1.1.1.1/Thu Oct 23 04:59:12 1997// /scrolledtext.n.html/1.1.1.1/Thu Oct 23 04:59:12 1997// /selectionbox.n.html/1.1.1.1/Thu Oct 23 04:59:13 1997// /selectiondialog.n.html/1.1.1.1/Thu Oct 23 04:59:13 1997// /shell.n.html/1.1.1.1/Thu Oct 23 04:59:13 1997// /spindate.n.html/1.1.1.1/Thu Oct 23 04:59:13 1997// /spinint.n.html/1.1.1.1/Thu Oct 23 04:59:13 1997// /spinner.n.html/1.1.1.1/Thu Oct 23 04:59:13 1997// /spintime.n.html/1.1.1.1/Thu Oct 23 04:59:13 1997// /tabnotebook.n.html/1.1.1.1/Thu Oct 23 04:59:13 1997// /tabset.n.html/1.1.1.1/Thu Oct 23 04:59:13 1997// /toolbar.n.html/1.1.1.1/Thu Oct 23 04:59:13 1997// itcl2.2/html/iwidgets2.2.0/buttonbox.n.html100666 1751 0 21024 6423554636 17401 0ustar kunkeewheel iwidgets2.2.0 User Commands - buttonbox

iwidgets2.2.0 User Commands - buttonbox

NAME

     buttonbox - Create and manipulate a manager widget for  but-
     tons

SYNOPSIS

     buttonbox pathName ?options?

INHERITANCE

     itk::Widget <- buttonbox

STANDARD OPTIONS

     background      cursor

     See the "options" manual entry for details on  the  standard
     options.

WIDGET-SPECIFIC OPTIONS

     Name:           orient
     Class:          Orient
     Command-Line Switch:           -orient

          Orientation of the button box: horizontal or  vertical.
          The default is horizontal.

     Name:           padX
     Class:          PadX
     Command-Line Switch:           -padx

          Specifies a  non-negative  padding  distance  to  leave
          between the button group and the outer edge of the but-
          ton box in the x direction.  The value may be given  in
          any  of  the  forms  acceptable  to  Tk_GetPixels.  The
          default is 5 pixels.

     Name:           padY
     Class:          PadY
     Command-Line Switch:           -pady

          Specifies a  non-negative  padding  distance  to  leave
          between the button group and the outer edge of the but-
          ton box in the y direction.  The value may be given  in
          any  of  the  forms  acceptable  to  Tk_GetPixels.  The
          default is 5 pixels.

DESCRIPTION

     The buttonbox command creates a manager widget for  control-
     ling  buttons.  The button box also supports the display and
     invocation of a default button.  The button box can be  con-
     figured either horizontally or vertically.

METHODS

     The buttonbox 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 com-
     mand.

     Many of the widget commands for the buttonbox  take  as  one
     argument  an  indicator of which button of the button box to
     operate on.  These indicators are called indexes  and  allow
     reference  and  manipulation  of buttons regardless of their
     current map state.  buttonbox indexes may  be  specified  in
     any of the following forms:

     number      Specifies  the  button  numerically,   where   0
                 corresponds  to  the left/top-most button of the
                 button box.

     end         Indicates the right/bottom-most  button  of  the
                 button box.

     default     Indicates the current default button of the but-
                 ton  box.   This  is the button with the default
                 ring displayed.

     pattern     If the index doesn't satisfy one  of  the  above
                 forms  then  this  form  is  used.   Pattern  is
                 pattern-matched against the tag of  each  button
                 in  the  button  box,  in order from left/top to
                 right/left, until a  matching  entry  is  found.
                 The rules of Tcl_StringMatch are used.

WIDGET-SPECIFIC METHODS

     pathName add tag args
          Add a button distinguished by tag to  the  end  of  the
          button  box.   If additional arguments are present they
          specify options to be applied to the button.  See Push-
          Button for information on the options available.

     pathName buttonconfigure index ?options?
          This command  is  similar  to  the  configure  command,
          except that it applies to the options for an individual
          button, whereas configure applies to  the  options  for
          the button box as a whole.  Options may have any of the
          values accepted by the PushButton 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 cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the buttonbox 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  correspond-
          ing  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 buttonbox command.

     pathName default index
          Sets the default button to the button given  by  index.
          This  causes  the  default  ring  to appear arround the
          specified button.

     pathName delete index
          Deletes the button given by index from the button box.

     pathName hide index
          Hides the button denoted by index.  This doesn't remove
          the button permanently, just inhibits its display.

     pathName index index
          Returns the numerical index corresponding to index.

     pathName insert index tag ?option value option value ...?
          Same as the add command except that it inserts the  new
          button  just  before the one given by index, instead of
          appending to the end of the button  box.   The  option,
          and value arguments have the same interpretation as for
          the add widget command.

     pathName invoke ?index?
          Invoke the command associated with  a  button.   If  no
          arguments  are given then the current default button is
          invoked, otherwise the argument is  expected  to  be  a
          button index.

     pathName show index
          Display a previously hidden button denoted by index.

EXAMPLE

           buttonbox .bb

           .bb add Yes -text Yes -command "puts Yes"
           .bb add No -text No -command "puts No"
           .bb add Maybe -text Maybe -command "puts Maybe"
           .bb default Yes

           pack .bb -expand yes -fill both

AUTHOR

     Bret A. Schuhmacher

     Mark L. Ulferts

KEYWORDS

     buttonbox, pushbutton, button, widget
itcl2.2/html/iwidgets2.2.0/canvasprintbox.n.html100666 1751 0 26706 6423554637 20433 0ustar kunkeewheel iwidgets2.2.0 User Commands - canvasprintbox

iwidgets2.2.0 User Commands - canvasprintbox

NAME

     canvasprintbox - Create and manipulate a  canvas  print  box
     widget

SYNOPSIS

     canvasprintbox pathName ?options?

INHERITANCE

     itk::Widget <- Canvasprintbox

STANDARD OPTIONS

     activeBackground               background      borderWidthcursor
     foreground      highlightBackground            highlightColorhighlightThickness
     insertBackground               insertBorderWidthinsertOffTimeinsertOnTime
     insertWidth     relief         repeatDelay     repeatInterval
     selectBackground               selectBorderWidthselectForeground

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

WIDGET-SPECIFIC OPTIONS

     Name:           filename
     Class:          FileName
     Command-Line Switch:           -filename

          The file to write the postscript output to  (Only  when
          output  is  set to "file"). If posterizing is turned on
          and hpagecnt and/or vpagecnt is more  than  1,  x.y  is
          appended to the filename where x is the horizontal page
          number and y the vertical page number.

     Name:           hpagecnt
     Class:          PageCnt
     Command-Line Switch:           -hpagecnt

          Is used in combination with posterize to determine over
          how  many  pages the output should be distributed. This
          attribute specifies how many pages should be used  hor-
          izontaly.   Any change to this attribute will automati-
          cally update the "stamp".  Defaults to 1.

     Name:           orient
     Class:          Orient
     Command-Line Switch:           -orient

          Determines the orientation of the output to the printer
          (or  file).   It  can  take  the  value  "portrait"  or
          "landscape" (default). Changes to this  attribute  will
          be  reflected  immediately in the "stamp".  Defaults to
          "landscape" but will be  changed  automaticaly  to  the
          value deemed appropiate for the current canvas. Setting
          this attribute when the canvasprintbox  is  first  con-
          structed (instead of using the "configure" method) will
          turn off the auto adjustment of this attribute.

     Name:           output
     Class:          Output
     Command-Line Switch:           -output

          Specifies where the postscript output should go: to the
          printer  or to a file. Can take on the values "printer"
          or "file".  The corresponding entry-widget will reflect
          the  contents  of  either the printcmd attribute or the
          filename attribute.  Defaults to "printer".

     Name:           pageSize
     Class:          PageSize
     Command-Line Switch:           -pagesize

          The pagesize the  printer  supports.  Changes  to  this
          attribute will be reflected immediately in the "stamp".
          Defaults to "a4".

     Name:           posterize
     Class:          Posterize
     Command-Line Switch:           -posterize

          Indicates if posterizing is turned on or not. Posteriz-
          ing  the output means that it is possible to distribute
          the output over more than one page. This way it is pos-
          sible to print a canvas/region which is larger than the
          specified pagesize without stretching. If used in  com-
          bination  with  stretching  it can be used to "blow up"
          the contents of a canvas to as large  as  size  as  you
          want  (See  attributes:   hpagecnt  and  vpagecnt). Any
          change to this attribute will automatically update  the
          "stamp".  Defaults to 0.

     Name:           printCmd
     Class:          PrintCmd
     Command-Line Switch:           -printcmd

          The command to execute  when  printing  the  postscript
          output.   The  command will get the postscript directed
          to its standard input  (Only  when  output  is  set  to
          "printer").  Defaults to "lpr".

     Name:           printRegion
     Class:          PrintRegion
     Command-Line Switch:           -printregion

          A list of four coordinates specifying which part of the
          canvas  to print.  An empty list means that the canvas'
          entire scrollregion should be printed.  Any  change  to
          this  attribute  will automatically update the "stamp".
          Defaults to an empty list.

     Name:           stretch
     Class:          Stretch
     Command-Line Switch:           -stretch

          Determines if the output should be  stretched  to  fill
          the  page  (as  defined  by  the attribute pagesize) as
          large as possible. The aspect-ratio of the output  will
          be  retained  and the output will never fall outside of
          the boundaries of the page.  Defaults to 0 but will  be
          changed automaticaly to the value deemed appropiate for
          the current canvas. Setting  this  attribute  when  the
          canvasprintbox  is  first constructed (instead of using
          the "configure" method) will turn off the auto  adjust-
          ment of this attribute.

     Name:           vPageCnt
     Class:          PageCnt
     Command-Line Switch:           -vpagecnt

          Is used in combination with  "posterize"  to  determine
          over  how  many pages the output should be distributed.
          This attribute specifies how many pages should be  used
          verticaly.  Any change to this attribute will automati-
          cally update the "stamp".  Defaults to 1.

DESCRIPTION

     Implements a print box for printing the contents of a canvas
     widget  to  a  printer  or a file. It is possible to specify
     page orientation, the number of pages to print the image  on
     and  if  the  output  should  be  stretched to fit the page.
     Options exist to control the appearance and actions  of  the
     widget.

METHODS

     The canvasprintbox command creates a new Tcl  command  whose
     name  is pathName.  This command may be used to invoke vari-
     ous operations on the widget.  It has the following  general
     form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.    The   following  commands  are  possible  for  can-
     vasprintbox widgets:

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the canvasprintbox 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  correspond-
          ing  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 canvasprintbox command.

     pathName getoutput
          Returns the value of the printercmd or filename  option
          depending on the current setting of output.

     pathName print
          Perfrom the actual printing of  the  canvas  using  the
          current  settings  of  all  the  attributes.  Returns a
          boolean indicating wether the printing  was  successful
          or not.

     pathName refresh
          Retrieves the current value for  all  edit  fields  and
          updates  the  stamp  accordingly.  Is useful for Apply-
          buttons.

     pathName setcanvas canvas
          This is used to set the canvas that has to be  printed.
          A  stamp-sized copy will automatically be drawn to show
          how the output would look with the current settings.

     pathName stop
          Stops the drawing of the "stamp". I'm currently  unable
          to detect when a Canvasprintbox gets destroyed or with-
          drawn. It's therefore advised that you perform  a  stop
          before you do something like that.

COMPONENTS

     Name:           prtflentry
     Class:          Entry

          The prtflentry component is the entry  field  for  user
          input  of the filename or printer command (depending on
          the value of output).

     Name:           hpcnt
     Class:          Entry

          The hpcnt component is the entry field for  user  input
          of  the number of pages to use horizontaly when poster-
          ize is turned on.
          Name:           vpcnt
          Class:          Entry

          The vpcnt component is the entry field for  user  input
          of  the number of pages to use verticaly when posterize
          is turned on.

EXAMPLE

          option add *textBackground GhostWhite

          canvasprintbox .fsb -orient landscape -stretch 1
          pack .fsb -padx 10 -pady 10 -fill both -expand yes

AUTHOR

     Tako Schotanus

     Tako.Schotanus@bouw.tno.nl

KEYWORDS

     canvasprintbox, widget
itcl2.2/html/iwidgets2.2.0/canvasprintdialog.n.html100666 1751 0 13770 6423554637 21077 0ustar kunkeewheel iwidgets2.2.0 User Commands - canvasprintdialog

iwidgets2.2.0 User Commands - canvasprintdialog

NAME

     canvasprintdialog - Create and  manipulate  a  canvas  print
     dialog widget

SYNOPSIS

     canvasprintdialog pathName ?options?

INHERITANCE

     itk::Toplevel <- Dialogshell <- Dialog <- Canvasprintdialog

STANDARD OPTIONS

     activeBackground               background      borderWidthcursor
     foreground      highlightBackground            highlightColorhighlightThickness
     insertBackground               insertBorderWidthinsertOffTimeinsertOnTime
     insertWidth     relief         repeatDelay     repeatInterval
     selectBackground               selectBorderWidthselectForeground

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     filename        hpagecnt       orient          output
     pagesize        posterize      printcmd        printregion
     vpagecnt

     See the "canvasprintbox" widget manual entry for details  on
     the above associated options.

INHERITED OPTIONS

     buttonBoxPadX   buttonBoxPadY  buttonBoxPos    padX
     padY            separator      thickness

     See the "dialogshell" widget manual entry for details on the
     above inherited options.

     master          modality       title

     See the "shell" widget manual entry for details on the above
     inherited options.

WIDGET-SPECIFIC OPTIONS

DESCRIPTION

     The canvasprintdialog command creates  a  print  dialog  for
     printing  the  contents of a canvas widget to a printer or a
     file. It is possible to specify page orientation, the number
     of  pages  to print the image on and if the output should be
     stretched to fit the page.

METHODS

     The canvasprintdialog 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 gen-
     eral form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.    The   following  commands  are  possible  for  can-
     vasprintdialog widgets:

ASSOCIATED METHODS

     getoutput       setcanvas      refresh         print

     See the "canvasprintbox" class manual entry for  details  on
     the associated methods.

INHERITED METHODS

     add             buttonconfigure                defaulthide
     insert          invoke         show

     See the "buttonbox" widget manual entry for details  on  the
     above inherited methods.

     activate        deactivate

     See the "dialogshell" widget manual entry for details on the
     above inherited methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the canvasprintdialog 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  correspond-
          ing  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  canvasprintdialog  com-
          mand.

COMPONENTS

     Name:           cpb
     Class:          Canvasprintbox

          The cpb component is the canvas print box for the  can-
          vas  print  dialog.   See  the  "canvasprintbox" widget
          manual entry for details on the cpb component item.

EXAMPLE

           option add *textBackground white

           canvasprintdialog .cpb
           .cpb activate

AUTHOR

     Tako Schotanus

     Tako.Schotanus@bouw.tno.nl

KEYWORDS

     canvasprintdialog, canvasprintbox, dialog, widget
itcl2.2/html/iwidgets2.2.0/combobox.n.html100666 1751 0 40067 6423554637 17176 0ustar kunkeewheel iwidgets2.2.0 User Commands - combobox

iwidgets2.2.0 User Commands - combobox

NAME

     combobox - Create and manipulate combination box widgets

SYNOPSIS

     combobox pathName ?options?

INHERITANCE

     itk::Widget <- LabeledWidget <- Entryfield <- Combobox

STANDARD OPTIONS

     background      borderWidth    cursor          exportSelection
     foreground      highlightColor highlightThicknessinsertBackground
     insertBorderWidth              insertOffTime   insertOnTimeinsertWidth
     justify         relief         selectBackgroundselectBorderWidth
     selectForeground               textVariable    width

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     hscrollmode     items          textBackground  textFont
     vscrollmode

     See the "scrolledlistbox" manual entry for  details  on  the
     above inherited options.

     show            state

     See the "entry" manual entry for details on the above inher-
     ited options.

INHERITED OPTIONS

     childSitePos    command        fixed           focusCommand
     invalid         textBackground textFont        validate

     See the "entryfield" class manual entry for details  on  the
     inherited options.

     labelBitmap     labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable

     See the "labeledwidget" class manual entry  for  details  on
     the inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           autoClear
     Class:          AutoClear
     Command-Line Switch:           -autoclear

          Boolean value that specifies wheather or not  to  clear
          the entry field as items are added to the list given in
          any of the forms  acceptable  to  Tcl_GetBoolean.   The
          default is true.

     Name:           arrowRelief
     Class:          Relief
     Command-Line Switch:           -arrowrelief

          Specifies the  relief  style  to  use  for  a  dropdown
          Combobox's  arrow  button  in  a normal (not depressed)
          state. Acceptable  values  are  raised,  sunken,  flat,
          ridge, and groove. Sunken is discouraged as this is the
          relief used to indicate a depressed state. This  option
          has  no  effect  on  simple  Comboboxes. The default is
          raised.

     Name:           dropdown
     Class:          Dropdown
     Command-Line Switch:           -dropdown

          Boolean describing the Combobox layout style  given  in
          any of the forms acceptable to Tcl_GetBoolean. If true,
          the Combobox will be  a  dropdown  style  widget  which
          displays  an entry field and an arrow button which when
          activated will pop up a scrollable list  of  items.  If
          false,  a  simple Combobox style will be used which has
          an entry field and a scrollable list beneath  it  which
          is  always visible. Both styles allow an optional label
          for the entry field area. The default is true.

     Name:           editable
     Class:          Editable
     Command-Line Switch:           -editable

          Boolean describing whether or not the text  entry  area
          is editable by the user. If true the user can add items
          to the combobox by entering text into  the  entry  area
          and  then  pressing Return. If false, the list of items
          is non-editable and can only be changed by calling  the
          insert  or  delete  methods.  Given in any of the forms
          acceptable to Tcl_GetBoolean. The default is true.

     Name:           flipArrow
     Class:          FlipArrow
     Command-Line Switch:           -fliparrow

          Boolean describing whether or not the arrow  button  of
          dropdowns  should  be reversed (point up) when the list
          is popped up. Given in any of the forms  acceptable  to
          Tcl_GetBoolean. The default is false.


     Name:           listHeight
     Class:          Height
     Command-Line Switch:           -listheight

          Height of the listbox specified in  any  of  the  forms
          acceptable to Tk_GetPixels.  The default is 100 pixels.

     Name:           margin
     Class:          Margin
     Command-Line Switch:           -margin

          Specifies the width in pixels between  the  entry  com-
          ponent  and  the  arrow  button for a dropdown Combobox
          given in any of the forms acceptable  to  Tk_GetPixels.
          This  option  has  no  effect on a simple Combobox. The
          default is 0.

     Name:           popupCursor
     Class:          Cursor
     Command-Line Switch:           -popupcursor

          Specifies the cursor to  be  used  for  dropdown  style
          listboxes.  The value may have any of the forms accept-
          able to Tk_GetCursor. The default is arrow.

     Name:           selectionCommand
     Class:          SelectionCommand
     Command-Line Switch:           -selectioncommand

          Specifies a Tcl command procedure which is called  when
          an  item in the listbox area is selected. The item will
          be selected in the list, the listbox will be removed if
          it is a dropdown Combobox, and the selected item's text
          will be  inserted  into  the  entry  field  before  the
          -selectioncommand proc is called. The default is {}.

     Name:           unique
     Class:          Unique
     Command-Line Switch:           -unique

          Boolean describing whether or not duplicate  items  are
          allowed  in the combobox list. If true, then duplicates
          are not allowed to be inserted. If false,  a  duplicate
          entry causes selection of the item. Given in any of the
          forms acceptable  to  Tcl_GetBoolean.  The  default  is
          true.

DESCRIPTION

     The combobox command creates an enhanced entry field  widget
     with  an  optional  associated  label and a scrollable list.
     When an item is selected in the list area of a Combobox it's
     value  is then displayed in the entry field text area. Func-
     tionally  similar  to  an  Optionmenu,  the  Combobox   adds
     (optional)  list  scrolling  and (optional) item editing and
     inserting capabilities.

     There are two basic styles of Comboboxes (determined by  the
     -dropdown  option):  dropdown and simple. The dropdown style
     adds an arrow button to the right of the entry  field  which
     when  activated  will pop up (and down) the scrolled listbox
     beneath the entry field. The simple (non-dropdown)  Combobox
     permanently displays the listbox beneath the entry field and
     has no arrow button. Either style allows an  optional  entry
     field label.

METHODS

     The combobox command creates a new Tcl command whose name is
     pathName.  This command may be used to invoke various opera-
     tions on the widget. It has the following general form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand. The following commands are possible for Combobox widg-
     ets:

ASSOCIATED METHODS

     icursor         scan

     See the "entry" manual entries  for  details  on  the  above
     associated methods.

     curselection    index          see             size
     xview           yview

     See the "listbox" manual entries for details  on  the  above
     associated methods.

     getcurselection justify        sort

     See the "scrolledlistbox" manual entries for details on  the
     above associated methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the combobox command.

     pathName clear ?component?
          Clears the contents from one or both components.  Valid
          component values are list, or entry.  With no component
          specified, both are cleared.

     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  correspond-
          ing  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 combobox command.

     pathName delete component first ?last?
          Delete one or more elements  from  a  given  component,
          list  or  entry.   If  a  list  item  to  be removed is
          currently selected (displayed in the entry field area),
          the entry field will be cleared.

     pathName get ?index?
          With no arguments, returns the  contents  currently  in
          the  entry  field area. With a single argument, returns
          the contents of  the  listbox  item  at  the  indicated
          index.

     pathName insert component index element ?element element ...?
          Insert  one  or  more  new elements into the given com-
          ponent, list or entry, just before the element given by
          index.

     pathName selection option first ?last?
          Adjust the selection within the listbox  component  and
          updates  the  contents  of the entry field component to
          the value of  the  selected  item.  See  the  "listbox"
          manual entry for more details on parameter options.

COMPONENTS

     Name:           entry
     Class:          Entryfield

          Text  entry  area  where  the  current   selection   is
          displayed.  If  the  Combobox is editable, the user can
          edit the contents of this item.

     Name:           list
     Class:          Scrolledlistbox

          Scrollable list which stores all the  items  which  the
          user  can  select  from.  For dropdown Comboboxes, this
          component is hidden until the user pops it up by press-
          ing  on the arrow button to the right of the entry com-
          ponent. For simple Comboboxes this component is  always
          visible just beneath the entry component.

DEFAULT BINDINGS

     The Combobox generally has the same bindings as it's primary
     component  items  - the Scrolledlistbox and Entryfield. How-
     ever it also adds these:

     [1] Button-1 mouse press on the arrow key of a dropdown Com-
     bobox  causes  the  list to be popped up. If the combobox is
     non-editable, a Button-1 press on the entry field area  will
     also pop up the list.

     [2] Button-1 mouse press anywhere on the display  removes  a
     dropdown  listbox  which  has  been  popped  up,  unless the
     keypress is  upon  one  of  the  Combobox  scrollbars  which
     scrolls  the list. If it is pressed upon an item in the list
     area, that item will be selected before the list is removed.

     [3] Button-3 mouse press on the arrow key of a dropdown Com-
     bobox  causes  the  next item to be selected. Shift-Button-3
     causes the previous item to be selected.

     [4] Escape keypress removes a dropdown list which  has  been
     popped up.

     [5] The <space> and <Return> keystrokes select  the  current
     item.  They also remove the popped up list for dropdown com-
     boboxes.

     [6] Up and Down arrow keypresses from the  entry  field  and
     arrow  button component cause the previous and next items in
     the listbox to be selected respectively. Ctl-P and Ctl-N are
     similarly mapped for emacs emulation.

     [7] Entry field and  arrow  button  component  Shift-Up  and
     Shift-Down arrow keys pop up and down the listbox of a drop-
     down Combobox. The arrow button component also maps <Return>
     and <space> similarly.

EXAMPLE

           proc selectCmd {} {
              puts stdout "[.cb2 getcurselection]"
           }

           #
           # Non-editable Dropdown Combobox
           #
           combobox .cb1 -labeltext Month: \
               -selectioncommand {puts "selected: [.cb1 getcurselection]"} \
               -editable false -listheight 185 -popupcursor hand1 \
               -items {Jan Feb Mar Apr May June Jul Aug Sept Oct Nov Dec}

           #
           # Editable Dropdown Combobox
           #
           combobox .cb2 -labeltext "Operating System:" \
              -items {Linux HP-UX SunOS Solaris Irix} -selectioncommand selectCmd

           #
           # Simple Combobox
           #
           combobox .cb3 -labeltext Fonts: -labelpos nw \
             -dropdown false -listheight 220 -items [exec xlsfonts]

           pack .cb1 -padx 10 -pady 10 -fill x
           pack .cb2 -padx 10 -pady 10 -fill x
           pack .cb3 -padx 10 -pady 10 -fill x

AUTHOR

     John S. Sigler

KEYWORDS

     combobox, entryfield, scrolledlistbox,  itk::Widget,  entry,
     listbox, widget, iwidgets
itcl2.2/html/iwidgets2.2.0/dialog.n.html100666 1751 0 11600 6423554637 16614 0ustar kunkeewheel iwidgets2.2.0 User Commands - dialog

iwidgets2.2.0 User Commands - dialog

NAME

     dialog - Create and manipulate a dialog widget

SYNOPSIS

     dialog pathName ?options?

INHERITANCE

     itk::Toplevel <- Shell <- Dialogshell <- Dialog

STANDARD OPTIONS

     background      cursor         foreground

     See the "options" manual entry for details on  the  standard
     options.

INHERITED OPTIONS

     buttonBoxPadX   buttonBoxPadY  buttonBoxPos    padX
     padY            separator      thickness

     See the "dialogshell" manual entry for details on the  above
     inherited options.

     master          modality       title

     See the "shell" manual entry for details on the above inher-
     ited options.

DESCRIPTION

     The dialog command creates a dialog box  providing  standard
     buttons  and  a  child site for use in derived classes.  The
     buttons include ok, apply, cancel, and  help.   Methods  and
     Options  exist to configure the buttons and their containing
     box.

METHODS

     The dialog command creates a new Tcl command whose  name  is
     pathName.  This command may be used to invoke various opera-
     tions on the widget.  It has the following general form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.   The following commands are possible for dialog widg-
     ets:

INHERITED METHODS


     add             buttonconfigure                defaulthide
     index           insert         invoke          show

     See the "buttonbox" manual entry for details  on  the  above
     inherited methods.

     childsite

     See the "dialogshell" manual entry for details on the  above
     inherited methods.

     activate        center         deactivate

     See the "shell" manual entry for details on the above inher-
     ited methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the dialog 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  correspond-
          ing  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 dialog command.

EXAMPLE

           dialog .d -modality global
           .d buttonconfigure OK -command {puts OK; .d deactivate 1}
           .d buttonconfigure Apply -command {puts Apply}
           .d buttonconfigure Cancel -command {puts Cancel; .d deactivate 0}
           .d buttonconfigure Help -command {puts Help}

           listbox [.d childsite].lb -relief sunken
           pack [.d childsite].lb -expand yes -fill both

           if {[.d activate]} {
               puts "Exit via OK button"
           } else {
               puts "Exit via Cancel button"
           }

AUTHOR

     Mark L. Ulferts

     Bret A. Schuhmacher

KEYWORDS

     dialog, dialogshell, shell, widget
itcl2.2/html/iwidgets2.2.0/dialogshell.n.html100666 1751 0 17404 6423554637 17654 0ustar kunkeewheel iwidgets2.2.0 User Commands - dialogshell

iwidgets2.2.0 User Commands - dialogshell

NAME

     dialogshell - Create and manipulate a dialog shell widget

SYNOPSIS

     dialogshell pathName ?options?

INHERITANCE

     itk::Toplevel <- Shell <- Dialogshell

STANDARD OPTIONS

     background      cursor         foreground

     See the "options" manual entry for details on  the  standard
     options.

INHERITED OPTIONS

     master          modality       title

     See the "shell" manual entry for details on the above inher-
     ited options.

WIDGET-SPECIFIC OPTIONS

     Name:           buttonBoxPadX
     Class:          Pad
     Command-Line Switch:           -buttonboxpadx

          Specifies a  non-negative  padding  distance  to  leave
          between the button group and the outer edge of the but-
          ton box in the x direction.  The value may be given  in
          any  of  the  forms  accpetable  to  Tk_GetPixels.  The
          default is 5 pixels.

     Name:           buttonBoxPadY
     Class:          Pad
     Command-Line Switch:           -buttonboxpady

          Specifies a  non-negative  padding  distance  to  leave
          between the button group and the outer edge of the but-
          ton box in the y direction.  The value may be given  in
          any  of  the  forms  accpetable  to  Tk_GetPixels.  The
          default is 5 pixels.

     Name:           buttonBoxPos
     Class:          Position
     Command-Line Switch:           -buttonboxpos

          Attaches buttons to the given side of the dialog: n, s,
          e or w.  The default is s.

     Name:           padX
     Class:          Pad
     Command-Line Switch:           -padx

          Specifies a padding distance for the childsite  in  the
          X-direction   in   any   of  the  forms  acceptable  to
          Tk_GetPixels.  The default is 10.

     Name:           padY
     Class:          Pad
     Command-Line Switch:           -pady

          Specifies a padding distance for the childsite  in  the
          Y-direction   in   any   of  the  forms  acceptable  to
          Tk_GetPixels.  The default is 10.

     Name:           separator
     Class:          Separator
     Command-Line Switch:           -separator

          Specifies whether a line is drawn to separate the  but-
          tons  from  the dialog box contents in any of the forms
          acceptable to Tcl_GetBoolean.  The default is true.

     Name:           thickness
     Class:          Thickness
     Command-Line Switch:           -thickness

          Specifies the thickness of the separator in any of  the
          forms  acceptable  to  Tk_GetPixels.   The default is 3
          pixels.

DESCRIPTION

     The dialogshell command creates a dialog shell  which  is  a
     top  level  widget  composed of a button box, separator, and
     child site area.  The class also has methods to control but-
     ton construction.

METHODS

     The dialogshell command create 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 com-
     mand.   The  following commands are possible for dialogshell
     widgets:

INHERITED METHODS

     activate        center         deactivate

     See the "shell" manual entry for details on the above inher-
     ited methods.

ASSOCIATED METHODS

     add             buttonconfigure                defaultdelete
     hide            index          insert          invoke
     show

     See the "buttonbox" manual entry for details on the  associ-
     ated methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the dialogshell command.

     pathName childsite
          Returns the pathname of the child site widget.

     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  correspond-
          ing  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 dialogshell command.

COMPONENTS

     Name:           dschildsite
     Class:          frame

          The dschildsite component is the user  child  site  for
          the  dialog shell.  See the "frame" widget manual entry
          for details on the dschildsite component item.

     Name:           separator
     Class:          frame

          The separator component devides the  area  between  the
          user  child  site  and the button box.  See the "frame"
          widget manual entry for details on the  separator  com-
          ponent item.

     Name:           bbox
     Class:          ButtonBox

          The bbox component is the  button  box  containing  the
          buttons  for  the  dialog  shell.   See the "ButtonBox"
          widget manual entry for details on the  bbox  component
          item.

EXAMPLE

           dialogshell .ds -modality none

           .ds add OK -text "OK"
           .ds add Cancel -text "Cancel"
           .ds default OK

           .ds activate

AUTHOR

     Mark L. Ulferts

KEYWORDS

     dialogshell, dialog, shell, widget
itcl2.2/html/iwidgets2.2.0/entryfield.n.html100666 1751 0 25021 6423554637 17524 0ustar kunkeewheel iwidgets2.2.0 User Commands - entryfield

iwidgets2.2.0 User Commands - entryfield

NAME

     entryfield - Create and manipulate a entry field widget

SYNOPSIS

     entryfield pathName ?options?

INHERITANCE

     itk::Widget <- LabeledWidget <- entryfield

STANDARD OPTIONS

     background      borderWidth    cursor          exportSelection
     foreground      highlightColor highlightThicknessinsertBackground
     insertBorderWidth              insertOffTime   insertOnTimeinsertWidth
     justify         relief         selectBackgroundselectBorderWidth
     selectForeground               textVariable    width

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     show            state

     See the "entry" manual entry for details on  the  associated
     options.

INHERITED OPTIONS

     labelBitmap     labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable

     See the "labeledwidget" class manual entry  for  details  on
     the inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           childSitePos
     Class:          Position
     Command-Line Switch:           -childsitepos

          Specifies the position of the child site in  the  entry
          field: n, s, e, or w.  The default is e.

     Name:           command
     Class:          Command
     Command-Line Switch:           -command

          Specifies a Tcl command to be executed  upon  detection
          of a Return key press event.

     Name:           fixed
     Class:          Fixed
     Command-Line Switch:           -fixed
          Restrict entry to the specified  number  of  chars.   A
          value  of  0,  which  is the default, denotes no limit.
          The value is the maximum number of chars the  user  may
          type  into  the  field,  regardles of field width.  For
          example, if the field width is set to 20 and the  fixed
          value  is  10,  the  user  will only be able to type 10
          characters into the field which is 20 characters long.

     Name:           focusCommand
     Class:          Command
     Command-Line Switch:           -focuscommand

          Specifies a Tcl command to be executed  upon  reception
          of focus.

     Name:           invalid
     Class:          Command
     Command-Line Switch:           -invalid

          Specifies a Tcl command to be executed upon  determina-
          tion of invalid input.  The default is bell.

     Name:           textBackground
     Class:          Background
     Command-Line Switch:           -textbackground

          Background color for  inside  textual  portion  of  the
          entry  field.   The  value  may  be given in any of the
          forms acceptable to Tk_GetColor.

     Name:           textFont
     Class:          Font
     Command-Line Switch:           -textfont

          Name of font to use for display of text in  entryfield.
          The  value  may be given in any of the forms acceptable
          to Tk_GetFont.

     Name:           validate
     Class:          Command
     Command-Line Switch:           -validate

          The validate option allows specification of  a  valida-
          tion  mechanism.  Standard character validation such as
          numeric, alphabetic, integer,  hexidecimal,  real,  and
          alphanumeric  can  be  handled  through the use of key-
          words.  Should more extensive validation be  necessary,
          the  value  may  contain  the name of a command script.
          The script should return a  boolean  value.   True  for
          valid,  false  for invalid.  If false is returned, then
          the procedure associated with the invalid  option  will
          be  invoked.   If  the validation 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  entryfield.   The  replacement
          depends on the character following the %, as defined in
          the list below.

     %c   Replaced with the current input character.

     %P   Replaced with the contents of the  entryfield  modified
          to  include the latest keystoke.  This is equivalent to
          peeking at  the  future  contents,  enabling  rejection
          prior to the update.

     %S   Replaced with the current contents  of  the  entryfield
          prior to the latest keystroke being added.

     %W   Replaced with the entryfield widget pathname.

DESCRIPTION

     The entryfield command creates an enhanced text entry widget
     with  an  optional associated label.  Addtional options sup-
     port validation and establishing a upper limit on the number
     of characters which may be entered in the field.

METHODS

     The entryfield 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 com-
     mand.   The  following  commands are possible for entryfield
     widgets:

ASSOCIATED METHODS

     delete          get            icursor         index
     insert          scan           selection       xview

     See the "entry" manual entry for details on  the  associated
     methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the entryfield command.

     pathName childsite
          Returns the path name of the child site.

     pathName clear
          Clear entry widget

     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  correspond-
          ing  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 entryfield command.

COMPONENTS

     Name:           efchildsite
     Class:          frame

          The efchildsite component is the user  child  site  for
          the  entry  field.  See the "frame" widget manual entry
          for details on the efchildsite component item.

     Name:           entry
     Class:          entry

          The entry component provides the entry field  for  user
          text  input and display.  See the "entry" widget manual
          entry for details on the entry component item.

EXAMPLE

           option add *textBackground white

           proc returnCmd {} {
               puts stdout "Return Pressed"
           }

           proc invalidCmd {} {
               puts stdout "Alphabetic contents invalid"
           }

           entryfield .ef -command returnCmd

           entryfield .fef -labeltext "Fixed:" -fixed 10 -width 12

           entryfield .nef -labeltext "Numeric:" -validate numeric -width 12

           entryfield .aef -labeltext "Alphabetic:" \
              -validate alphabetic -width 12 -invalid invalidCmd

           entryfield .pef -labeltext "Password:" \
              -show 267 -width 12 -command returnCmd

           LabeledWidget::alignLabels .ef .fef .nef .aef .pef

           pack .ef -fill x -expand yes -padx 10 -pady 5
           pack .fef -fill x -expand yes -padx 10 -pady 5
           pack .nef -fill x -expand yes -padx 10 -pady 5
           pack .aef -fill x -expand yes -padx 10 -pady 5
           pack .pef -fill x -expand yes -padx 10 -pady 5

AUTHOR

     Sue Yockey

     Mark L. Ulferts

KEYWORDS

     entryfield, widget
itcl2.2/html/iwidgets2.2.0/feedback.n.html100666 1751 0 13557 6423554637 17116 0ustar kunkeewheel iwidgets2.2.0 User Commands - feedback

iwidgets2.2.0 User Commands - feedback

NAME

     feedback -  Create  and  manipulate  a  feedback  widget  to
     display  feedback on the current status of an ongoing opera-
     tion to the user.

SYNOPSIS

     feedback pathName ?options?

INHERITANCE

     itk::Widget <- Labeledwidget <- Feedback

STANDARD OPTIONS

     background      borderWidth    cursor          foreground
     highlightColor  highlightThickness             relief

     See the "options" manual entry for details on  the  standard
     options.

INHERITED OPTIONS

     labelBitmap     labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable

     See the "labeledwidget" class manual entry  for  details  on
     the inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           barColor
     Class:          BarColor
     Command-Line Switch:           -barcolor

          Specifies the color of the status bar, in  any  of  the
          forms acceptable to Tk_GetColor.

     Name:           barHeight
     Class:          BarHeight
     Command-Line Switch:           -barheight

          Specifies the height of the status bar, in any  of  the
          forms acceptable to Tk_GetPixels.

     Name:           barWidth
     Class:          BarWidth
     Command-Line Switch:           -barwidth

          Specifies the total  width  of  the  status  bar  (when
          full,) in any of the forms acceptable to Tk_GetPixels.

     Name:           elementBorderWidth
     Class:          BorderWidth
     Command-Line Switch:           -elementborderwidth
          Sets the width of the border around the status bar,  in
          any  of the forms acceptable to Tk_GetPixels.  If it is
          set to zero, the status bar has no border.

     Name:           steps
     Class:          Steps
     Command-Line Switch:           -steps

          Specifies the total number of steps for the status bar.
          The default is 10.

DESCRIPTION

     The feedback command creates a feedback  widget  to  display
     feedback  on  the  current status of an ongoing operation to
     the user. Display is given as a percentage and as a thermom-
     eter type bar. Options exist for adding a label and control-
     ling its position.

METHODS

     The feedback command creates a new Tcl command whose name is
     pathName.  This command may be used to invoke various opera-
     tions on the widget.  It has the following general form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.   The following commands are possible for scrolledtext
     widgets:

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the scrolledhtml 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  correspond-
          ing  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 feedback command.

     pathName reset
          Reset status to 0%

     pathName step ?inc?
          Increase the current number of steps completed by  inc.
          Inc defaults to 1.

EXAMPLE

           feedback .fb -labeltext "Status" -steps 20
           pack .fb -padx 10 -pady 10 -fill both -expand yes

           for {set i 0} {$i < 20} {incr i} {
               .fb step
               after 500
           }

ACKNOWLEDGEMENTS

     Sam Shen

          This code is based largely  on  his  feedback.tcl  code
          from  tk  inspect.  The original feedback code is copy-
          right 1995 Lawrence Berkeley Laboratory.

AUTHOR

     Kris Raney

KEYWORDS

     feedback, widget
itcl2.2/html/iwidgets2.2.0/fileselectionbox.n.html100666 1751 0 46463 6423554637 20732 0ustar kunkeewheel iwidgets2.2.0 User Commands - fileselectionbox

iwidgets2.2.0 User Commands - fileselectionbox

NAME

     fileselectionbox - Create and manipulate  a  file  selection
     box widget

SYNOPSIS

     fileselectionbox pathName ?options?

INHERITANCE

     itk::Widget <- Fileselectionbox

STANDARD OPTIONS

     activeBackground               background      borderWidthcursor
     foreground      highlightColor highlightThicknessinsertBackground
     insertBorderWidth              insertOffTime   insertOnTimeinsertWidth
     relief          repeatDelay    repeatInterval  selectBackground
     selectBorderWidth              selectForeground

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     textBackground  textFont

     See the "entryfield" widget manual entry for details on  the
     above associated options.

     labelFont       labelMargin

     See the "labeledwidget" widget manual entry for  details  on
     the above associated options.

     activeRelief    elementBorderWidth             jumptroughColor

     See the "scrollbar" widget class manual entry for details on
     the above associated options.

     hscrollMode     sbWidth        scrollMargin    textBackground
     textFont        vscrollMode

     See the "scrolledlistbox" widget manual entry for details on
     the above associated options.

WIDGET-SPECIFIC OPTIONS

     Name:           childSitePos
     Class:          Position
     Command-Line Switch:           -childsitepos

          Specifies the position of the child site in the  selec-
          tion box: n, s, e, or w.  The default is s.

     Name:           dblDirsCommand
     Class:          Command
     Command-Line Switch:           -dbldirscommand

          Specifies a Tcl command procedure which is called  when
          an  directory  list  item is double clicked.  Typically
          this occurs when mouse button 1 is double clicked  over
          a directory name.

     Name:           dblFilesCommand
     Class:          Command
     Command-Line Switch:           -dblfilescommand

          Specifies a Tcl command procedure which is called  when
          an  file  list  item is double clicked.  Typically this
          occurs when mouse button 1 is  double  clicked  over  a
          file name.

     Name:           directory
     Class:          Directory
     Command-Line Switch:           -directory

          Specifies the initial default directory.   The  default
          is the present working directory.

     Name:           dirsfraction
     Class:          DirsFraction
     Command-Line Switch:           -dirsfraction

          Specifies the fraction as a percentage of  the  overall
          width that the directory list takes up.

     Name:           dirSearchCommand
     Class:          Command
     Command-Line Switch:           -dirsearchcommand

          Specifies a Tcl command to be  executed  to  perform  a
          directory search.  The command will receive the current
          working directory and filter mask  as  arguments.   The
          command  should  return  a  list of files which will be
          placed into the directory list.

     Name:           dirsLabel
     Class:          Text
     Command-Line Switch:           -dirslabel

          Specifies the text of the label for the directory list.
          The default is "Directories".

     Name:           dirsLabelPos
     Class:          Position
     Command-Line Switch:           -dirslabelpos
          Specifies the position of the label along the  side  of
          the directory list: n, ne, e, se, s, sw, w, or nw.  The
          default is nw.

     Name:           dirsOn
     Class:          DirsOn
     Command-Line Switch:           -dirson

          Specifies whether or not to display the directory list.
          The  value  may be given in any of the forms acceptable
          to Tcl_GetBoolean.  The default is true.

     Name:           fileSearchCommand
     Class:          Command
     Command-Line Switch:           -filesearchcommand

          Specifies a Tcl command to be  executed  to  perform  a
          file  search.   The  command  will  receive the current
          working directory and filter mask  as  arguments.   The
          command  should  return  a  list of files which will be
          placed into the file list.

     Name:           filesLabel
     Class:          Text
     Command-Line Switch:           -fileslabel

          Specifies the text of the label  for  the  files  list.
          The default is "Files".

     Name:           filesLabelPos
     Class:          Position
     Command-Line Switch:           -fileslabelpos

          Specifies the position of the label along the  side  of
          the  files  list: : n, ne, e, se, s, sw, w, or nw.  The
          default is nw.

     Name:           filesOn
     Class:          FilesOn
     Command-Line Switch:           -fileson

          Specifies whether or not to  display  the  files  list.
          The  value  may be given in any of the forms acceptable
          to Tcl_GetBoolean.  The default is true.

     Name:           fileType
     Class:          FileType
     Command-Line Switch:           -filetype

          Specify the type of files which may appear in the  file
          list: regular, directory, or any.  The default is regu-
          lar.

     Name:           filterCommand
     Class:          Command
     Command-Line Switch:           -filtercommand

          Specifies a Tcl command to be executed upon hitting the
          Return key in the filter entry widget.

     Name:           filterFocusCommand
     Class:          Command
     Command-Line Switch:           -filterfocuscommand

          Specifies a Tcl command to be executed  upon  reception
          of focus by the filter.

     Name:           filterLabel
     Class:          Text
     Command-Line Switch:           -filterlabel

          Specifies the text of the label for  the  filter  entry
          field.  The default is "Filter".

     Name:           filterLabelPos
     Class:          Position
     Command-Line Switch:           -filterlabelpos

          Specifies the position of the label along the  side  of
          the filter: n, ne, e, se, s, sw, w, or nw.  The default
          is nw.

     Name:           filterOn
     Class:          FilterOn
     Command-Line Switch:           -filteron

          Specifies whether or not to display the  filter  entry.
          The  value  may be given in any of the forms acceptable
          to Tcl_GetBoolean.  The default is true.

     Name:           height
     Class:          Height
     Command-Line Switch:           -height

          Specifies the height of the selection box.   The  value
          may  be  specified  in  any  of the forms acceptable to
          Tk_GetPixels.  The default is 360 pixels.

     Name:           horizmargin
     Class:          Margin
     Command-Line Switch:           -horizmargin

          Specifies    distance    between    the    lists    and
          filter/selection  entries.   The  value may be given in
          any of  the  forms  acceptable  to  Tk_GetPixels.   The
          default is 7.

     Name:           invalid
     Class:          Command
     Command-Line Switch:           -invalid

          Command to be executed should the  filter  contents  be
          proven invalid.  The default is {bell}.

     Name:           mask
     Class:          Mask
     Command-Line Switch:           -mask

          Specifies the initial file mask string.  The default is
          "*".

     Name:           noMatchString
     Class:          NoMatchString
     Command-Line Switch:           -nomatchstring

          Specifies the string to be displayed in the files  list
          should  no  files  match  the  mask.  The default is "[
          ]".

     Name:           selectDirCommand
     Class:          Command
     Command-Line Switch:           -selectdirommand

          Specifies a Tcl command to be executed following selec-
          tion of a directory in the directory list.

     Name:           selectFileCommand
     Class:          Command
     Command-Line Switch:           -selectfileommand

          Specifies a Tcl command to be executed following selec-
          tion of a file in the files list.

     Name:           selectionCommand
     Class:          Command
     Command-Line Switch:           -selectioncommand

          Specifies a Tcl command to be executed upon hitting the
          Return key in the selection entry widget.

     Name:           selectionFocusCommand
     Class:          Command
     Command-Line Switch:           -selectionfocuscommand

          Specifies a Tcl command to be executed  upon  reception
          of focus by the selection entry.

     Name:           selectionImage
     Class:          Image
     Command-Line Switch:           -selectionimage

          Specifies a image to be used  as  the  selection  entry
          label.  The  image  may be any of the values created by
          the image create command.

     Name:           selectionLabel
     Class:          Text
     Command-Line Switch:           -selectionlabel

          Specifies the text of the label for the selection entry
          field.  The default is "Selection".

     Name:           selectionLabelPos
     Class:          Position
     Command-Line Switch:           -selectionlabelpos

          Specifies the position of the label along the  side  of
          the  selection:  n,  ne,  e,  se, s, sw, w, or nw.  The
          default is nw.

     Name:           selectionOn
     Class:          SelectionOn
     Command-Line Switch:           -selectionon

          Specifies whether  or  not  to  display  the  selection
          entry.   The  value  may  be  given in any of the forms
          acceptable to Tcl_GetBoolean.  The default is true.

     Name:           style
     Class:          Syle
     Command-Line Switch:           -style

          Specifies display style of the fileselectionbox:  motif
          or notif.  The default is motif which reflects the lay-
          out of the OSF/Motif standard Xmfileselectionbox widget
          composed  of  directory and file scrolled lists as well
          as filter and selection entry fields.  The notif option
          setting  varies  the layout by removing directory names
          from the files, separates the lists by a paned  window,
          and  changes  the  filter  and  entry  fields into com-
          boboxes.

     Name:           vertmargin
     Class:          Margin
     Command-Line Switch:           -vertmargin

          Specifies  distance  between  the  directory  and  file
          lists.   The  value  may  be  given in any of the forms
          acceptable to Tk_GetPixels.  The default  is  7.   This
          option  is  only useful for motif styled fileselection-
          boxes.  For notif styled  ones,  use  the  dirsfraction
          option  to  modify  spacing  between  the directory and
          files lists.

     Name:           width
     Class:          Width
     Command-Line Switch:           -width

          Specifies the width of the selection  box.   The  value
          may  be  specified  in  any  of the forms acceptable to
          Tk_GetPixels.  The default is 470 pixels.

DESCRIPTION

     The fileselectionbox command creates a  file  selection  box
     similar  to the OSF/Motif standard Xmfileselectionbox compo-
     site widget.  The fileselectionbox is composed of  directory
     and  file  scrolled  lists  as  well as filter and selection
     entry fields.  Bindings are in place such that selection  of
     a  directory  list  item  loads  the  filter entry field and
     selection of a file list  item  loads  the  selection  entry
     field.   Options exist to control the appearance and actions
     of the widget.

METHODS

     The fileselectionbox command creates a new Tcl command whose
     name  is pathName.  This command may be used to invoke vari-
     ous operations on the widget.  It has the following  general
     form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.   The  following  commands are possible for fileselec-
     tionbox widgets:

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the fileselectionbox command.

     pathName childsite
          Returns the child site widget path name.

     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  correspond-
          ing  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 fileselectionbox command.

     pathName filter
          Update the current contents of the file  selection  box
          based on the current filter entry field value.

     pathName get
          Returns  the  current  value  of  the  selection  entry
          widget.

COMPONENTS

     Name:           childsite
     Class:          Frame

          The childsite component is the user child site for  the
          file  selection  box.   See  the  "frame" widget manual
          entry for details on the childsite component item.

     Name:           dirs
     Class:          Scrolledlistbox

          The dirs component is the directory list  box  for  the
          file  selection  box.  See the "scrolledlistbox" widget
          manual entry for details on the dirs component item.

     Name:           files
     Class:          Scrolledlistbox

          The files component is the file list box for  the  file
          selection box.  See the "scrolledlistbox" widget manual
          entry for details on the files component item.

     Name:           filter
     Class:          Entryfield

          The filter component is the entry field for user  input
          of  the  filter  value.   See  the  "entryfield" widget
          manual entry for details on the filter component item.


     Name:           selection
     Class:          Entryfield

          The selection component is the  entry  field  for  user
          input  of  the  currently selected file value.  See the
          "entryfield" widget manual entry  for  details  on  the
          selection component item.

EXAMPLE

          option add *textBackground GhostWhite

          fileselectionbox .fsb
          pack .fsb -padx 10 -pady 10 -fill both -expand yes

AUTHOR(S)

     Mark L. Ulferts

     Anthony Parent

KEYWORDS

     fileselectionbox, widget
itcl2.2/html/iwidgets2.2.0/fileselectiondialog.n.html100666 1751 0 20123 6423554637 21362 0ustar kunkeewheel iwidgets2.2.0 User Commands - fileselectiondialog

iwidgets2.2.0 User Commands - fileselectiondialog

NAME

     fileselectiondialog - Create and manipulate a file selection
     dialog widget

SYNOPSIS

     fileselectiondialog pathName ?options?

INHERITANCE

     itk::Toplevel  <-  Shell  <-  Dialogshell   <-   Dialog   <-
     Fileselectiondialog

STANDARD OPTIONS

     activeBackground               background      borderWidthcursor
     foreground      highlightColor highlightThicknessinsertBackground
     insertBorderWidth              insertOffTime   insertOnTimeinsertWidth
     relief          repeatDelay    repeatInterval  selectBackground
     selectBorderWidth              selectForeground

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     textBackground  textFont

     See the "entryfield" widget manual entry for details on  the
     above associated options.

     childSitePos    directory      dirsLabel       dirSearchCommand
     dirsFraction    dirsLabelPos   dirsOn          filesLabel
     filesLabelOn    fileSearchCommand              filesLabelPosfilesOn
     fileType        filterLabel    filterLabelPos  filterOn
     invalid         mask           noMatchString   selectionCommand
     selectionLabel  selectionLabelPos              selectionOnstyle
     vertMargin

     See the "fileselectionbox" widget manual entry  for  details
     on the above associated options.

     labelFont       labelMargin

     See the "labeledwidget" widget manual entry for  details  on
     the above associated options.

     horizMargin     hscrollMode    sbWidth         scrollMargin
     textBackground  textFont       vScrollMode

     See the "scrolledlistbox" widget manual entry for details on
     the above associated options.


     activeRelief    elementBorderWidth             jumptroughColor

     See the "scrollbar" widget class manual entry for details on
     the above associated options.

INHERITED OPTIONS

     buttonBoxPadX   buttonBoxPadY  buttonBoxPos    padX
     padY            separator      thickness

     See the "dialogshell" widget manual entry for details on the
     above inherited options.

     master          modality       title

     See the "shell" widget manual entry for details on the above
     inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           height
     Class:          Height
     Command-Line Switch:           -height

          Specifies the height of the file selection dialog.  The
          value  may  be specified in any of the forms acceptable
          to Tk_GetPixels.  The default is 435 pixels.

     Name:           width
     Class:          Width
     Command-Line Switch:           -width

          Specifies the width of the file selection dialog.   The
          value  may  be specified in any of the forms acceptable
          to Tk_GetPixels.  The default is 450 pixels.

DESCRIPTION

     The fileselectiondialog command  creates  a  file  selection
     dialog  similar  to the OSF/Motif standard composite widget.
     The fileselectiondialog is derived from the Dialog class and
     is  composed  of  a  FileSelectionBox with attributes set to
     manipulate the dialog buttons.

METHODS

     The fileselectiondialog 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 gen-
     eral form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.   The  following  commands are possible for fileselec-
     tiondialog widgets:

ASSOCIATED METHODS

     get             childsite      filter

     See the "fileselectionbox" class manual entry for details on
     the associated methods.

INHERITED METHODS

     add             buttonconfigure                defaulthide
     insert          invoke         show

     See the "buttonbox" widget manual entry for details  on  the
     above inherited methods.

     activate        center         deactivate

     See the "shell" widget manual entry for details on the above
     inherited methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the fileselectiondialog 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  correspond-
          ing  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 fileselectiondialog  com-
          mand.

COMPONENTS

     Name:           fsb
     Class:          Fileselectionbox

          The fsb component is the file  selection  box  for  the
          file  selection  dialog.   See  the  "fileselectionbox"
          widget manual entry for details on  the  fsb  component
          item.

EXAMPLE

           option add *textBackground white

           fileselectiondialog .fsd
           .fsd activate

AUTHOR

     Mark L. Ulferts

KEYWORDS

     fileselectiondialog, fileselectionbox, dialog,  dialogshell,
     shell, widget
itcl2.2/html/iwidgets2.2.0/hyperhelp.n.html100666 1751 0 16007 6423554637 17363 0ustar kunkeewheel iwidgets2.2.0 User Commands - hyperhelp

iwidgets2.2.0 User Commands - hyperhelp

NAME

     hyperhelp - Create and manipulate a hyperhelp widget

SYNOPSIS

     hyperhelp pathName ?options?

INHERITANCE

     itk::Toplevel <- shell <- hyperhelp

STANDARD OPTIONS

     activeBackground    background         borderWidth
     cursor              exportSelection    foreground
     highlightColor      highlightThickness insertBackground
     insertBorderWidth   insertOffTime      insertOnTime
     insertWidth         padX               padY
     relief              repeatDelay        repeatInterval
     selectBackground    selectBorderWidth  selectForeground
     setGrid

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     hscrollmode     vscrollmode    textbackground  fontname
     fontsize        fixedfont      link            linkhighlight
     width           height         state           wrap
     unknownimage

     See the "scrolledhtml" widget manual entry  for  details  on
     the above associated options.

INHERITED OPTIONS

     modality        title

     See the "shell" manual entry for details on the above inher-
     ited options.

WIDGET-SPECIFIC OPTIONS

     Name:   topics
     Class:  Topics
     Command-Line Switch:    -topics

          Specifies a list of help topics in  the  form  {?topic?
          ...  }. Topic may either be a topic name, in which case
          the document associated with the topic should be in the
          file helpdir/topic.html, or it may be of the form {name
          file}. In the latter case, name  is  displayed  in  the
          topic  menu, and selecting the name loads file. If file
          has a relative path, it is assumed to  be  relative  to
          helpdir.

     Name:   helpdir
     Class:  Directory
     Command-Line Switch:    -helpdir

          Specifies the directory where help files are located.

DESCRIPTION

     The hyperhelp command creates a shell window with a pulldown
     menu  showing  a list of topics. The topics are displayed by
     importing a HTML formatted  file  named  helpdir/topic.html.
     For a list of supported HTML tags, see scrolledhtml(n).

METHODS

     The hyperhelp 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 com-
     mand.   The following commands are possible for dialog widg-
     ets:

INHERITED METHODS

     activate        center         childsite       deactivate

     See the "shell" manual entry for details on the above inher-
     ited methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the hyperhelp 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  correspond-
          ing  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 hyperhelp command.

     pathName showtopic topic
          Display html file helpdir/topic.html. Topic may option-
          ally be of the form topicname#anchorname. In this form,
          either topicname or anchorname or both may be empty. If
          topicname  is  empty,  the current topic is assumed. If
          anchorname is empty, the top of the document is assumed

     pathName followlink href
          Display html file href. Href may be  optionally  be  of
          the  form  filename#anchorname.  In  this  form, either
          filename  or  anchorname  or  both  may  be  empty.  If
          filename  is empty, the current document is assumed. If
          anchorname  is  empty,  the  top  of  the  document  is
          assumed.

     pathName forward
          Display html file  one  forward  in  history  list,  if
          applicable.

     pathName back
          Display html file one back in history list, if applica-
          ble.

EXAMPLE

           hyperhelp .h -topics { Intro Help } -helpdir ~/help
           .h showtopic Intro

AUTHOR

     Kris Raney

KEYWORDS

     hyperhelp, html, help, shell, widget
itcl2.2/html/iwidgets2.2.0/iwidgets2.2.0UserCmds.html100666 1751 0 5050 6423554637 20750 0ustar kunkeewheel
iwidgets2.2.0 User Commands
iwidgets2.2.0 User Commands
itcl2.2/html/iwidgets2.2.0/labeledwidget.n.html100666 1751 0 17047 6423554637 20164 0ustar kunkeewheel iwidgets2.2.0 User Commands - labeledwidget

iwidgets2.2.0 User Commands - labeledwidget

NAME

     labeledwidget - Create and manipulate a labeled widget

SYNOPSIS

     labeledwidget pathName ?options?

INHERITANCE

     itk::Widget <- labeledwidget

STANDARD OPTIONS

     background      cursor         foreground

     See the "options" manual entry for details on  the  standard
     options.

WIDGET-SPECIFIC OPTIONS

     Name:           labelBitmap
     Class:          Bitmap
     Command-Line Switch:           -labelbitmap

          Specifies a bitmap to display in the widget, in any  of
          the  forms  acceptable  to  Tk_GetBitmap.   This option
          overrides the labeltext option.

     Name:           labelFont
     Class:          Font
     Command-Line Switch:           -labelfont

          Specifies the font to be used for the label.

     Name:           labelImage
     Class:          Image
     Command-Line Switch:           -labelimage

          Specifies a image to be used as the  label.  The  image
          may  be  any  of the values created by the image create
          command.  This option overrides  both  the  labelbitmap
          and labeletext options.

     Name:           labelMargin
     Class:          Margin
     Command-Line Switch:           -labelmargin

          Specifies the distance between the childsite and  label
          in  any  of  the forms acceptable to Tk_GetPixels.  The
          default is 1 pixel.

     Name:           labelPos
     Class:          Position
     Command-Line Switch:           -labelpos
          Specifies the position of the label along the  side  of
          the  childsite:  n,  ne,  e,  se, s, sw, w, or nw.  The
          default is w.

     Name:           labelText
     Class:          Text
     Command-Line Switch:           -labeltext

          Specifies the text of the label around the childsite.

     Name:           labelVariable
     Class:          Variable
     Command-Line Switch:           -labelvariable

          Specifies the text variable of  the  label  around  the
          childsite.

DESCRIPTION

     The labeledwidget command creates  a  labeled  widget  which
     contains  a label and child site.  The child site is a frame
     which can filled with any widget  via  a  derived  class  or
     though  the  use  of  the  childsite method.  This class was
     designed to be a general purpose base class  for  supporting
     the  combination  of  label  widget  and  a  childsite.  The
     options include the ability to position the label around the
     childsite  widget,  modify  the font and margin, and control
     the display of the labels.

METHODS

     The labeledwidget command creates a new  Tcl  command  whose
     name  is pathName.  This command may be used to invoke vari-
     ous operations on the widget.  It has the following  general
     form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.  The following commands are possible for labeledwidget
     widgets:

WIDGET-SPECIFIC METHODS

     pathName childsite
          Return the path name of the child site.

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the labeledwidget 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  correspond-
          ing  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 labeledwidget command.

STATIC METHODS

     Labeledwidget::alignlabels widget ?widget ...?
          The alignlabels  procedure  takes  a  list  of  widgets
          derived from the Labeledwidget class and uses the label
          margin to make each widget have the  same  total  space
          for  the  combination  of  label  and  margin.  The net
          effect is to left align the  labels.   Generally,  this
          method is only useful with a label position of w, which
          is the default.

COMPONENTS

     Name:           label
     Class:          label

          The label component provides the label for the  labeled
          widget.   See  the  "label"  widget  manual  entry  for
          details on the label component item.

     Name:           lwchildsite
     Class:          frame

          The lwchildsite component is the user  child  site  for
          the  labeled  widget.   See  the  "frame" widget manual
          entry for details on the lwchildsite component item.

EXAMPLE

          The labeledwidget was primarily  meant  to  be  a  base
          class.   The  ScrolledListBox  and  EntryField are good
          examples of derived classes of the labeledwidget class.
          In   order  to  provide  equal  support  for  composite
          classes, the 'childsite' methods also exists.  The fol-
          lowing is an example of 'childsite' method usage.


           labeledwidget .lw -labeltext "Canvas Widget" -labelpos s
           pack .lw -fill both -expand yes -padx 10 -pady 10

           set cw [canvas [.lw childsite].c -relief raised -width 200 -height 200]
           pack $cw -padx 10 -pady 10

AUTHOR

     Mark L. Ulferts

KEYWORDS

     labeledwidget, widget
itcl2.2/html/iwidgets2.2.0/menubar.n.html100666 1751 0 65405 6423554637 17022 0ustar kunkeewheel iwidgets2.2.0 User Commands - menubar

iwidgets2.2.0 User Commands - menubar

NAME

     menubar - Create and manipulate menubar menu widgets

SYNOPSIS

     menubar pathName ?options?

INHERITANCE

     itk::Widget <- menubar

STANDARD OPTIONS

     activeBackground               borderWidth     highlightBackgroundpadY
     activeBorderWidth              cursor          highligthThicknessrelief
     activeForeground               disabledForegroundhighlightColorwrapLength
     anchor          font           justify
     background      foreground     padX

     See the "options" manual entry for details on  the  standard
     options.

WIDGET-SPECIFIC OPTIONS

     Name:           helpVariable
     Class:          HelpVariable
     Command-Line Switch:           -helpvariable

          Specifies the global variable to  update  whenever  the
          mouse is in motion over a menu entry. This global vari-
          able is updated with the current value  of  the  active
          menu  entry's  helpStr.  Other widgets can "watch" this
          variable with the trace command, or as is the case with
          entry or label widgets, they can set their textVariable
          to the same global variable. This allows for  a  simple
          implementation of a help status bar. Whenever the mouse
          leaves a menu entry, the helpVariable  is  set  to  the
          empty  string  {}.  The  mainwindow(1)  associates  its
          helpstatus and its menubar in this fashion.

     Name:           menuButtons
     Class:          MenuButtons
     Command-Line Switch:           -menubuttons

          The menuButton option is a string which  specifies  the
          arrangement  of  menubuttons on the menubar frame. Each
          menubutton entry is delimited by the newline character.

          menubar .mb -menubuttons {
                  menubutton file -text File
                  menubutton edit -text Edit
                  menubutton options -text Options
          }

          specifies that three menubuttons will be added  to  the
          menubar (file, edit, options). Each entry is translated
          into an add command call.

          The menuButtons option can accept  embedded  variables,
          commands, and backslash quoting. Embedded variables and
          commands must be  enclosed  in  curly  braces  ({})  to
          ensure proper parsing of the substituted values.

DESCRIPTION

     The menubar command creates a new window (given by the path-
     Name  argument)  and  makes  it  into a menubar menu widget.
     Additional options, described above may be specified on  the
     command  line or in the option database to configure aspects
     of the menubar such as its colors and font. The menubar com-
     mand 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 menubar is a widget that simplifies the task  of  creating
     menu hierarchies. It encapsulates a frame widget, as well as
     menubuttons, menus, and menu  entries.  The  menubar  allows
     menus  to  be  specified and referenced in a more consistent
     manner than using Tk to build menus directly.

     Menubar allows a menu tree to be expressed in a  hierachical
     "language".  The  menubar  accepts a menuButtons option that
     allows a list of menubuttons to be added to the menubar.  In
     turn, each menubutton accepts a menu option that specifies a
     list of menu entries to be added to the  menubutton's  menu.
     Cascade entries also accept the menu option for specifying a
     list of menu entries to be added to the cascade's menu.

     Additionally, the menubar allows each component of the menu-
     bar system to be referenced by a simple menuPathName syntax.
     The menubar also extends the set of options for menu entries
     to include a helpStr option.

MENU PATH NAMES

     A menuPathName is a series of component names  separated  by
     the  `.' character. Each menubar component can be referenced
     via these menuPathNames. menuPathNames are similar to widget
     pathNames  in Tk. Some correspond directly to a widget path-
     Name  (components  of  type  menu  or  menubutton),   others
     correspond to a menu entry type. Every widget and entry in a
     menubar can be referenced with the menuPathName naming  con-
     vention. A menubar can have four types of components:

          frame. A menubar holds exactly one frame which  manages
          menubuttons.  The  frame is always signified by the `.'
          character as the path name.
          menubutton. A menubutton corresponds directly to  a  Tk
          menubutton. See menubutton(n).

          menu.  A  menu  is  attached  to   a   menubutton   and
          corresponds  directly  to  Tk's  menu widget. A menu is
          always signified by the menuPathName  ending  with  the
          keyword menu. See menu(n).

          entry. An  entry  corresponds  directly  to  Tk's  menu
          widget  entries.  Menus consist of a column of one line
          entries. Entries may be of type: command,  checkbutton,
          radiobutton,  separator,  or  cascade.  For  a complete
          description  of  these  types  see  the  discussion  on
          ENTRIES in menu(n).

     The suffix of a menuPathName may have the form of:

     tkWidgetName  Specifies the name of the component, either  a
                   frame,  menubutton, menu, or an entry. This is
                   the normal naming  of  widgets.  For  example,
                   .file references a menubutton named file.

     The  menuPathName  is  a  series  of  segment  names,   each
     separated  by the '.' character. Segment names may be one of
     the following forms:

     number        Specifies the index of the the component.  For
                   menubuttons,  0  corresponds  to the left-most
                   menubutton of the menu bar frame. As an  exam-
                   ple,  .1  would correspond to the second menu-
                   button on the menu bar frame.

                   For entries, 0  corresponds  to  the  top-most
                   entry  of the menu. For example, .file.0 would
                   correspond to the  first  entry  on  the  menu
                   attached to the menubutton named file.

     end           Specifes the last component. For  menubuttons,
                   it  specifies the right-most entry of the menu
                   bar frame. For menu entries, it specifies  the
                   bottom-most entry of the menu.

     last          Same as end.

     Finally, menu components always end with the  menu  keyword.
     These  components  are  automatically  created via the -menu
     option on menubuttons and cascades or via the add or  insert
     commands.

     menu          Specifes the menu pane that is associated with
                   the  given  menubutton  prefix.  For  example,
                   .file.menu specifies the menu pane attached to
                   the

     For example, the path .file.new specifies  the  entry  named
     new  on the menu associated with the file menubutton located
     on the menu bar. The path .file.menu specifies the menu pane
     associated  with the menubutton .file. The path .last speci-
     fies the last menu on the menu bar. The path  .0.last  would
     specify  the  first  menu  (file) and the last entry on that
     menu (quit), yielding .file.quit.

     As a restriction, the last name segment of menuPathName can-
     not  be one of the keywords last, menu, end, nor may it be a
     numeric value (integer).

WIDGET-SPECIFIC METHODS

     The menubar command creates a new Tcl command whose name  is
     pathName.  This command may be used to invoke various opera-
     tions on the widget. It has the following general form:

          pathName option ?arg arg ...?

     option and the args determine the exact behavior of the com-
     mand.

     In addition, many of the widget commands for menubar take as
     one  argument  a  path  name to a menu component. These path
     names are called menuPathNames. See the discussion on  MENU-
     BAR PATH NAMES above.

     The following commands are possible for menubar widgets:

     pathName add type menuPathName ?option value option value?
          Adds either a menu to the menu bar or a menu entry to a
          menu pane.

          If  additional  arguments  are  present,  they  specify
          options  available to component type entry. See the man
          pages for menu(1) in the section on ENTRIES.

          If  type  is  one  of  cascade,  checkbutton,  command,
          radiobutton,  or  separator  it adds a new entry to the
          bottom of the menu denoted by the prefix  of  menuPath-
          Name.  If additonal arguments are present, they specify
          options available to menu entry widgets.  In  addition,
          the  helpStr  option  is added by the menubar widget to
          all components of type entry.

          -helpstr value
               Specifes the string to associate with  the  entry.
               When  the  mouse  moves over the associated entry,
               the  variable  denoted  by  helpVariable  is  set.
               Another  widget  can  bind to the helpVariable and
               thus display status help.

          If the type of the component  added  is  menubutton  or
          cascade,  a menubutton or cascade is added to the menu-
          bar. If additional arguments are present, they  specify
          options  available to menubutton or cascade widgets. In
          addition, the menu  option  is  added  by  the  menubar
          widget to all menubutton and cascade widgets.

          -menu menuSpec
               This is only valid for menuPathNames of type menu-
               button or cascade. Specifes an option set and/or a
               set of entries to place on a  menu  and  associate
               with the menubutton or cascade. The option keyword
               allows the menu widget to be configured. Each item
               in  the  menuSpec is treated as add commands (each
               with  the  possibility  of  having   other   -menu
               options).  In  this  way a menu can be recursively
               built.

               The last segment of menuPathName cannot be one  of
               the keywords last, menu, end. Additionally, it may
               not be a number. However the menuPathName  may  be
               referenced  in this manner (see discussion of COM-
               PONENT PATH NAMES).

               Note that the same curly brace quoting rules apply
               to  -menu  option  strings  as did to -menubuttons
               option strings.  See  the  earlier  discussion  on
               umenubuttons in the "WIDGET-SPECIFIC OPTIONS" sec-
               tion.

     pathName cget option
          Returns the current value of the  configuration  option
          given by option.

     pathName configure ?options 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  correspond-
          ing  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.

     pathName delete menuPathName ?menuPathName2?
          If menuPathName is  of  component  type  Menubutton  or
          Menu,  delete  operates on menus. If menuPathName is of
          component type Entry, delete operates on menu entries.

          This command deletes all components  between  menuPath-
          Name  and  menuPathName2 inclusive. If menuPathName2 is
          omitted then it defaults to  menuPathName.  Returns  an
          empty string.

          If menuPathName is of type menubar, then all menus  and
          the  menu  bar  frame  will  be destroyed. In this case
          menuPathName2 is ignored.

     pathName index menuPathName
          If menuPathName is  of  type  menubutton  or  menu,  it
          returns  the  position  of  the  menu/menubutton on the
          menubar frame.

          If  menuPathName  is  of   type   command,   separator,
          radiobutton,  checkbutton,  or  cascade, it returns the
          menu widget's numerical index for the entry correspond-
          ing  to  menuPathName. If path is not found or the path
          is equal to ".", a value of -1 is returned.

     pathName insert menuPathName type name ?option value?
          Insert a new component named name before the  component
          specified by menuPathName.

          If menuPathName is of type Menubutton or Menu, the  new
          component  inserted  is of type Menu and given the name
          name. In this case valid option value pairs  are  those
          accepted by menubuttons.

          If menuPathName is of type  Entry,  the  new  component
          inserted  is  of type entry and given the name name. In
          this case, valid option value pairs are those  accepted
          by  menu  entries.   Name cannot be one of the keywords
          last, menu, end. Additionally, it may not be a  number.
          However  the  menuPathName  may  be  referenced in this
          manner (see discussion of COMPONENT PATH NAMES).

     pathName invoke menuPathName
          Invoke the action of the menu entry  denoted  by  menu-
          PathName. See the sections on the individual entries in
          the menu(1) man pages. If the menu  entry  is  disabled
          then  nothing happens. If the entry has a command asso-
          ciated 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.

          If menuPathName is  not  a  menu  entry,  an  error  is
          issued.

     pathName menucget menuPathName ?option value option value?
          Returns the current value of the  configuration  option
          given  by  option.  The  component type of menuPathName
          determines the valid available options.

     pathName menuconfigure menuPathName ?option value?
          Query or modify the configuration options of  the  com-
          ponet  of  the menubar specified by menuPathName. If no
          option is specified, returns a list describing  all  of
          the    available    options   for   menuPathName   (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 sub-
          list 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. The component type of menuPathName deter-
          mines the valid available options.

     pathName path ?mode? pattern
          Returns a fully formed menuPathName that  matches  pat-
          tern.  If  no  match  is  found it returns -1. The mode
          argument indicates how the  search  is  to  be  matched
          against  pattern  and it must have one of the following
          values:

          -glob
               Pattern is a glob-style pattern which  is  matched
               against  each  component path using the same rules
               as the string match command.

          -regexp
               Pattern is treated as  a  regular  expression  and
               matched against each component of the menuPathName
               using the same rules as the regexp  command.   The
               default mode is -glob.

     pathName type menuPathName
          Returns the type of the component  specified  by  menu-
          PathName.  For  menu entries, this is the type argument
          passed to the add/insert widget command when the  entry
          was  created, such as command or separator. Othewise it
          is either a menubutton or a menu.

     pathName yposition menuPathName
          Returns a decimal string giving the y-coordinate within
          the  menu  window  of  the  topmost  pixel in the entry
          specified by menuPathName. If the menuPathName  is  not
          an entry, an error is issued.

EXAMPLE ONE: USING GRAMMAR

     The following example creates a menubar with "File", "Edit",
     "Options"  menubuttons.  Each  of  these  menubuttons has an
     associated menu. In turn the File menu has menu entries,  as
     well as the Edit menu and the Options menu. The Options menu
     is a tearoff menu with selectColor (for radiobuttons) set to
     blue.   In  addition,  the Options menu has a cascade titled
     More, with several menu entries attached to it as  well.  An
     entry widget is provided to display help status.

     menubar .mb -helpvariable helpVar -menubuttons {
         menubutton file -text File -menu {
             options -tearoff false
             command new -label New \
                 -helpstr "Open new document" \
                 -command {puts NEW}
             command close -label Close \
                 -helpstr "Close current document" \
                 -command {puts CLOSE}
             separator sep1
             command exit -label Exit -command {exit} \
                 -helpstr "Exit application"
         }
         menubutton edit -text Edit -menu {
             options -tearoff false
             command undo -label Undo -underline 0 \
                 -helpstr "Undo last command" \
                 -command {puts UNDO}
             separator sep2
             command cut -label Cut -underline 1 \
                 -helpstr "Cut selection to clipboard" \
                 -command {puts CUT}
             command copy -label Copy -underline 1 \
                 -helpstr "Copy selection to clipboard" \
                 -command {puts COPY}
             command paste -label Paste -underline 0 \
                 -helpstr "Paste clipboard contents" \
                 -command {puts PASTE}
         }
         menubutton options -text Options -menu {
             options -tearoff false -selectcolor blue
             radiobutton byName -variable viewMode \
                 -value NAME -label "by Name" \
                 -helpstr "View files by name order" \
                 -command {puts NAME}
             radiobutton byDate -variable viewMode \
                 -value DATE -label "by Date" \
                 -helpstr "View files by date order" \
                 -command {puts DATE}
             cascade prefs -label Preferences -menu {
                 command colors -label Colors... \
                     -helpstr "Change text colors" \
                     -command {puts COLORS}
                 command fonts -label Fonts... \
                     -helpstr "Change text font" \
                     -command {puts FONT}
             }
         }

     }

     frame .fr -width 300 -height 300
     entry .ef -textvariable helpVar
     pack .mb -anchor nw -fill x -expand yes
     pack .fr -fill both -expand yes
     pack .ef -anchor sw -fill x -expand yes

EXAMPLE TWO: USING METHODS

     Alternatively the same menu could be created  by  using  the
     add and configure methods:

      menubar .mb
      .mb configure -menubuttons {
             menubutton file -text File -menu {
                     command new -label New
                     command close -label Close
                     separator sep1
                     command        quit -label Quit
             }
             menubutton edit -text Edit
      }


      .mb add command .edit.undo -label Undo -underline 0
      .mb add separator .edit.sep2
      .mb add command .edit.cut -label Cut -underline 1
      .mb add command .edit.copy -label Copy -underline 1
      .mb add command .edit.paste -label Paste -underline 0

      .mb add menubutton .options -text Options -menu {
             radiobutton byName -variable viewMode \
                      -value NAME -label "by Name"
             radiobutton byDate -variable viewMode \
                      -value DATE -label "by Date"
     }

      .mb add cascade .options.prefs -label Preferences -menu {
                     command colors -label Colors...
                     command fonts -label Fonts...
      }
      pack .mb -side left -anchor nw -fill x -expand yes

CAVEATS

     The -menubuttons option as  well  as  the  -menu  option  is
     evaluated  by  menubar  with the subst command. The positive
     side of this is that the option  string  may  contain  vari-
     ables,  commands,  and/or  backslash substitutions. However,
     substitutions might expand into more  than  a  single  word.
     These  expansions  can  be  protected by enclosing candidate
     substitutions in curly braces ({}). This ensures, for  exam-
     ple, a value for an option will still be treated as a single
     value and not multiple values. The following example  illus-
     trates this case:

          set fileMenuName "File Menu"
          set var {}
          menubar .mb -menubuttons {
                  menubutton file -text {$fileMenuName}
                  menubutton edit -text Edit -menu {
                          checkbutton check \
                                  -label Check \
                                  -variable {[scope var]} \
                                  -onvalue 1 \
                                  -offvalue 0
                  }
                  menubutton options -text Options
          }

          The variable fileMenuName will expand  to  "File  Menu"
          when  the  subst  command  is  used  on  the menubutton
          specification. In addition, the [scope...] command will
          expand  to  @scope :: var. By enclosing these inside {}
          they stay as a single value. Note that only {} work for
          this.  [list...],  ""  etc. will not protect these from
          the subst command.

ACKNOWLEDGMENTS

     Bret Schumaker

          1994 - Early work on a menubar widget.

     Mark Ulferts, Mark Harrison, John Sigler

          Invaluable feedback on grammar  and  usability  of  the
          menubar widget

AUTHOR

     Bill W. Scott

KEYWORDS

     frame, menu, menubutton, entries, help
itcl2.2/html/iwidgets2.2.0/messagedialog.n.html100666 1751 0 16623 6423554640 20165 0ustar kunkeewheel iwidgets2.2.0 User Commands - messagedialog

iwidgets2.2.0 User Commands - messagedialog

NAME

     messagedialog -  Create  and  manipulate  a  message  dialog
     widget

SYNOPSIS

     messagedialog pathName ?options?

INHERITANCE

     itk::Toplevel <- Shell <-  Dialogshell  <-  Dialog  <-  Mes-
     sagedialog

STANDARD OPTIONS

     anchor          background     bitmap          cursor
     font            foreground     image           justify
     text            wrapLength

     See the "options" manual entry for details on  the  standard
     options.

INHERITED OPTIONS

     buttonBoxPadX   buttonBoxPadY  buttonBoxPos    padX
     padY            separator      thickness

     See the "dialogshell" widget manual entry for details on the
     above inherited options.

     master          modality       title

     See the "shell" widget manual entry for details on the above
     inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           imagePos
     Class:          Position
     Command-Line Switch:           -imagepos

          Specifies the image position relative  to  the  message
          text: n, s, e, or w.  The default is w.

     Name:           textPadX
     Class:          Pad
     Command-Line Switch:           -textpadx

          Specifies a  non-negative  value  indicating  how  much
          extra  space  to  request for the message text in the X
          direction.  The value may have any of the forms accept-
          able to Tk_GetPixels.

     Name:           textPadY
     Class:          Pad
     Command-Line Switch:           -textpady

          Specifies a  non-negative  value  indicating  how  much
          extra  space  to  request for the message text in the X
          direction.  The value may have any of the forms accept-
          able to Tk_GetPixels.

DESCRIPTION

     The messagedialog command creates a message dialog composite
     widget.  The  messagedialog is derived from the Dialog class
     and is composed of an image and associated message text with
     commands to manipulate the dialog buttons.

METHODS

     The messagedialog command creates a new  Tcl  command  whose
     name  is pathName.  This command may be used to invoke vari-
     ous operations on the widget.  It has the following  general
     form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.  The following commands are possible for messagedialog
     widgets:

INHERITED METHODS

     add             buttonconfigure                defaulthide
     insert          invoke         show

     See the "buttonbox" widget manual entry for details  on  the
     above inherited methods.

     childsite

     See the "dialogshell" widget manual entry for details on the
     above inherited methods.

     activate        center         deactivate

     See the "dialogshell" widget manual entry for details on the
     above inherited methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the messagedialog 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  correspond-
          ing  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 messagedialog command.

COMPONENTS

     Name:           image
     Class:          Label

          The image component is the bitmap or image of the  mes-
          sage  dialog.   See the "label" widget manual entry for
          details on the image component item.

     Name:           msg
     Class:          Label

          The msg component provides the textual portion  of  the
          message  dialog.   See  the "label" widget manual entry
          for details on the msg component item.

EXAMPLE

           #
           # Standard question message dialog used for confirmation.
           #
           messagedialog .md -title "Message Dialog" -text "Are you sure ?" \
                          -bitmap questhead -modality global

           .md hide Help
           .md buttonconfigure OK -text Yes
           .md buttonconfigure Cancel -text No

           if {[.md activate]} {
              .md configure -text "Are you really sure ?"
              if {[.md activate]} {
                          puts stdout "Yes"
              } else {
                          puts stdout "No"
              }
           } else {
              puts stdout "No"

           }

           destroy .md

           #
           # Copyright notice with automatic deactivation.
           #
           messagedialog .cr -title "Copyright" -bitmap @dsc.xbm -imagepos n \
               -text "Copyright 1995 DSC Communications Corporation\n \
                              All rights reserved"

           .cr hide Apply
           .cr hide Cancel
           .cr hide Help

           .cr activate
           after 10000 ".cr deactivate"

AUTHOR

     Mark L. Ulferts

KEYWORDS

     messagedialog, dialog, dialogshell, shell, widget
itcl2.2/html/iwidgets2.2.0/notebook.n.html100666 1751 0 42176 6423554640 17203 0ustar kunkeewheel iwidgets2.2.0 User Commands - notebook

iwidgets2.2.0 User Commands - notebook

NAME

     notebook - create and manipulate notebook widgets

SYNOPSIS

     notebook pathName ?options?

INHERITANCE

     itk::Widget <- notebook

STANDARD OPTIONS

     background      foreground     scrollCommand   width
     cursor          height

     See the "options" manual entry for details on  the  standard
     options.

WIDGET-SPECIFIC OPTIONS

     Name:           auto
     Class:          Auto
     Command-Line Switch:           -auto

          Specifies    whether    to    use     the     automatic
          packing/unpacking algorithm of the notebook. A value of
          true indicates that page frames will  be  unpacked  and
          packed  acoording  to  the  algorithm  described in the
          select command. A value of  false  leaves  the  current
          page  packed  and subsequent selects, next, or previous
          commands do not switch pages automatically.  In  either
          case   the  page's  associated  command  (see  the  add
          command's  description  of  the  command   option)   is
          invoked.  The  value may have any of the forms accepted
          by the Tcl_GetBoolean, such as true, false, 0, 1,  yes,
          or no.

          For example, if a series of pages in a notebook  simply
          change  certain  display  configurations of a graphical
          display, the -auto flag could be used. By  setting  it,
          the -command procs could do the appropriate reconfigur-
          ing of the page when the page is switched.

DESCRIPTION

     The notebook command creates a  new  window  (given  by  the
     pathName  argument)  and  makes  it  into a notebook widget.
     Additional options, described above may be specified on  the
     command  line or in the option database to configure aspects
     of the notebook such as its  colors,  font,  and  text.  The
     notebook  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 notebook is a widget that contains  a  set  of  pages.  It
     displays  one page from the set as the selected page. When a
     page is selected, the page's contents are displayed  in  the
     page area. When first created a notebook has no pages. Pages
     may be added or  deleted  using  widget  commands  described
     below.

NOTEBOOK PAGES

     A notebook's pages area contains a single child site  frame.
     When  a new page is created it is a child of this frame. The
     page's child site frame serves as a geometry  container  for
     applications  to pack widgets into. It is this frame that is
     automatically unpacked or packed when  the  auto  option  is
     true. This creates the effect of one page being visible at a
     time. When a new page is selected, the  previously  selected
     page's  child  site frame is automatically unpacked from the
     notebook's child site frame and the  newly  selected  page's
     child site is packed into the notebook's child site frame.

     However, sometimes it is desirable to handle page changes in
     a  different manner. By specifying the auto option as false,
     child site packing can be disabled and done differently. For
     example,  all  widgets might be packed into the first page's
     child site frame. Then when a  new  page  is  selected,  the
     application can reconfigure the widgets and give the appear-
     ance that the page was flipped.

     In both cases the command option for a page specifies a  Tcl
     Command to execute when the page is selected. In the case of
     auto being true, it is called between the unpacking  of  the
     previously  selected  page  and  the  packing  of  the newly
     selected page.

WIDGET-SPECIFIC METHODS

     The notebookfR 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 com-
     mand.

     Many of the widget commands for a notebook take as one argu-
     ment  an  indicator of which page of the notebook to operate
     on. These indicators are called indexes and may be specified
     in any of the following forms:

     number
          Specifies the index of the the component. For menus,  0
          corresponds  to the left-most menu of the menu bar. For
          entries, 0 corresponds to the  top-most  entry  of  the
          menu.   number  Specifies the page numerically, where 0
          corresponds to the first page in the notebook, 1 to the
          second, and so on.

     select
          Specifies the currently selected page's  index.  If  no
          page is currently selected, the value -1 is returned.

     end  Specifes the last page in the notebooks's index. If the
          notebook is empty this will return -1.

     pattern
          If the index doesn't satisfy the form of a number, then
          this  form  is used. Pattern is pattern-matched against
          the label of each page in the notebook, in  order  from
          the  first  to the last page, until a matching entry is
          found. The rules of Tcl_StringMatch are used.

     The following commands are possible for notebook widgets:

     pathName add ?option value?
          Add a new page at the end of the notebook. A new  child
          site frame is created. Returns the child site pathName.
          If additional arguments are present, they  specify  any
          of the following options:

          -background value
               Specifies a background color to use for displaying
               the  child site frame of this page. If this option
               is specified as an  empty  string  (the  default),
               then  the  background option for the overall note-
               book is used.

          -command value
               Specifies a Tcl command to be executed  when  this
               page  is  selected.  This  allows the programmer a
               hook to reconfigure this  page's  widgets  or  any
               other page's widgets.

               If the notebook has the auto option set  to  true,
               when  a  page  is  selected  this  command will be
               called immediately after the  previously  selected
               page  is unpacked and immediately before this page
               is selected. The index value select is valid  dur-
               ing  this  Tcl command. `index select' will return
               this page's page number.

               If the auto option is set to false, when a page is
               selected  the  unpack and pack calls are bypassed.
               This Tcl command is still called.

          -foreground value
               Specifies a foreground color to use for displaying
               tab   labels   when   tabs  are  in  their  normal
               unselected state. If this option is  specified  as
               an empty string (the default), then the foreground
               option for the overall notebook is used.

          -label value
               Specifies a string to associate  with  this  page.
               This label serves as an additional identifier used
               to reference the page. This label may be used  for
               the index value in widget commands.

     pathName childSite ?index?
          If passed no arguments, returns a list of pathNames for
          all  the  pages  in  the  notebook.  If the notebook is
          empty, an empty list is returned

          If index is passed, it returns  the  pathName  for  the
          page's  child  site  frame  specified by index. Widgets
          that are created with this pathName will  be  displayed
          when the associated page is selected. If index is not a
          valid index, an empty string is returned.

     pathName cget option
          Returns the current value of the  configuration  option
          given by option.

     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  correspond-
          ing  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 notebook command.

     pathName delete index1 ?index2?
          Delete all of  the  pages  between  index1  and  index2
          inclusive.  If  index2  is  omitted then it defaults to
          index1. Returns an empty string.

     pathName index index
          Returns the numerical index corresponding to index.

     pathName insert index ?option value?
          Insert a new page  in  the  notebook  before  the  page
          specified  by index. A new child site frame is created.
          See the add command  for  valid  options.  Returns  the
          child site pathName.

     pathName next
          Advances the selected page to the next page  (order  is
          determined   by  insertion  order).  If  the  currently
          selected page is the last page  in  the  notebook,  the
          selection  wraps  around to the first page in the note-
          book.

          For notebooks with auto set to true the current  page's
          child  site  is unpacked from the notebook's child site
          frame. Then the next page's child site is  packed  into
          the  notebooks  child site frame. The Tcl command given
          with the command option will be invoked  between  these
          two operations.

          For notebooks with auto set to false  the  Tcl  command
          given with the command option will be invoked.

     pathName pagecget index ?option?
          Returns the current value of the  configuration  option
          given  by  option  for the page specified by index. The
          valid available options are the same  as  available  to
          the add command.

     pathName pageconfigure index ?option? ?value option value ...?
          This  command  is  similar  to  the  configure command,
          except that it applies to the options for an individual
          page,  whereas configure applies to the options for the
          notebook. 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 page index (see Tk_ConfigureInfo for infor-
          mation on the format of this list).

     pathName prev
          Moves the selected page to the previous page (order  is
          determined   by  insertion  order).  If  the  currently
          selected page is the first page in  the  notebook,  the
          selection  wraps  around  to the last page in the note-
          book.

          For notebooks with auto set to true the current  page's
          child  site  is unpacked from the notebook's child site
          frame. Then the previous page's child  site  is  packed
          into  the  notebooks  child site frame. The Tcl command
          given with the command option will be  invoked  between
          these two operations.

          For notebooks with auto set to false  the  Tcl  command
          given with the command option will be invoked.

     pathName select index
          Selects the page specified by index  as  the  currently
          selected page.

          For notebooks with auto set to true the current  page's
          child  site  is unpacked from the notebook's child site
          frame. Then the index page's child site is packed  into
          the  notebooks  child site frame. The Tcl command given
          with the command option will be invoked  between  these
          two operations.

          For notebooks with auto set to false  the  Tcl  command
          given with the command option will be invoked.

     pathName view
          Returns the currently selected page.  This  command  is
          for compatibility with the scrollbar widget.

     pathName view index
          Selects the page specified by index  as  the  currently
          selected  page.  This command is for compatibility with
          the scrollbar widget.

     pathName view moveto fraction
          Uses the fraction value to determine the  corresponding
          page to move to. This command is for compatibility with
          the scrollbar widget.

     pathName view scroll num what
          Uses the num value to determine how many pages to  move
          forward  or backward (num can be negative or positive).
          The what argument is ignored. This command is for  com-
          patibility with the scrollbar widget.

EXAMPLE

     Following is an example that creates  a  notebook  with  two
     pages. In this example, we use a scrollbar widget to control
     the notebook widget.

          # Create the notebook widget and pack it.
            notebook .nb -width 100 -height 100
            pack .nb -anchor nw \
                  -fill both \
                  -expand yes \
                  -side left \
                  -padx 10 \
                  -pady 10

          # Add two pages to the notebook, labelled
          # "Page One" and "Page Two", respectively.
            .nb add -label "Page One"
            .nb add -label "Page Two"

          # Get the child site frames of these two pages.
            set page1CS [.nb childsite 0]
            set page2CS [.nb childsite "Page Two"]

          # Create buttons on each page of the notebook
            button $page1CS.b -text "Button One"
            pack $page1CS.b
            button $page2CS.b -text "Button Two"
            pack $page2CS.b

          # Select the first page of the notebook
            .nb select 0

          # Create the scrollbar and associate teh scrollbar
          # and the notebook together, then pack the scrollbar
            ScrollBar .scroll -command ".nb view"
            .nb configure -scrollcommand ".scroll set"
            pack .scroll -fill y -expand yes -pady 10

AUTHOR

     Bill W. Scott

KEYWORDS

     notebook page
itcl2.2/html/iwidgets2.2.0/optionmenu.n.html100666 1751 0 26312 6423554640 17552 0ustar kunkeewheel iwidgets2.2.0 User Commands - optionmenu

iwidgets2.2.0 User Commands - optionmenu

NAME

     optionmenu - Create and manipulate a option menu widget

SYNOPSIS

     optionmenu pathName ?options?

INHERITANCE

     itk::Widget <- Labeledwidget <- optionmenu

STANDARD OPTIONS

     activeBackground               activeBorderWidthactiveForegroundbackground
     borderWidth     cursor         disabledForegroundfont
     foreground      highlightColor highlightThicknessrelief

     See the "options" manual entry for details on  the  standard
     options.

INHERITED OPTIONS

     labelBitmap     labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable

     See the "LabeledWidget" manual  entry  for  details  on  the
     inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           clickTime
     Class:          ClickTime
     Command-Line Switch:           -clicktime

          Interval time, in msec, used to determine that a single
          mouse  click  has  occurred.  Used  to  post  menu on a
          "quick" mouse click.  Note:  changing  this  value  may
          cause  the  sigle-click functionality to not work prop-
          erly.  The default is 150 msec.

     Name:           command
     Class:          Command
     Command-Line Switch:           -command

          Specifies a Tcl command procedure to be evaluated  fol-
          lowing a  change in the current option menu selection.

     Name:           cyclicOn
     Class:          CyclicOn
     Command-Line Switch:           -cyclicon

          Turns on/off the 3rd mouse button capability. The value
          may  be  specified  in  any  of the forms acceptable to
          Tcl_GetBoolean.  This feature allows  the  right  mouse
          button  to  cycle  through  the popup menu list without
          poping it up. The right mouse button cycles through the
          menu in reverse order.  The default is true.

     Name:           items
     Class:          Items
     Command-Line Switch:           -items

          Sepcifies the list of items  to  be  displayed  in  the
          menu.

     Name:           popupCursor
     Class:          Cursor
     Command-Line Switch:           -popupcursor

          Specifies  the mouse cursor to be used  for  the  popup
          menu.  The value may have any of the  forms  acceptable
          to Tk_GetCursor.

     Name:           state
     Class:          State
     Command-Line Switch:           -state

          Specified one of two states for the optionmenu: normal,
          or  disabled.   If  the  optionmenu  is  disabled, then
          option menu selection is ignored.

     Name:           width
     Class:          Width
     Command-Line Switch:           -width

          Specifies a fixed size for the menu button label in any
          of  the  forms acceptable to Tk_GetPixels.  If the text
          is too small to fit in the label, the text is  clipped.
          Note:  Normally,  when  a  new  list is created, or new
          items are added to an existing list,  the  menu  button
          label  is  resized  automatically.  Setting this option
          overrides that functionality.

DESCRIPTION

     The optionmenu command creates an option  menu  widget  with
     options  to manage it.  An option menu displays a frame con-
     taining a label and a button.  A pop-up menu will allow  for
     the value of the button to change.

METHODS

     The optionmenu 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 com-
     mand.

     Many of the widget commands for an optionmenu  take  as  one
     argument  an  indicator of which entry of the option 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 option
                 menu, 1 to the entry below it, and so on.

     end         Indicates the bottommost entry in the menu.   If
                 there  are  no  entries in the menu then zero is
                 returned.

     select      Returns the numerical  index  of  the  currently
                 selected option menu entry.  If no entries exist
                 in the menu, then -1 is returned.

     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 option 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  optionmenu
     widgets:

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the optionmenu 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  correspond-
          ing  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 optionmenu command.

     pathName delete first ?last?
          Delete all of the option menu entries between first and
          last inclusive.  If last is omitted then it defaults to
          first.

     pathName disable index
          Disable the option menu entry specified by index. Disa-
          bling a menu item will prevent the user from being able
          to select this item from the menu.  This  only  effects
          the  state  of  the  item  in the menu, in other words,
          should the item be the  currently  selected  item,  the
          programmer  is  responsible for determining this condi-
          tion and taking appropriate action.

     pathName enable index
          Enable the option menu entry specified by index.   Ena-
          bling  a  menu item allows the user to select this item
          from the menu.

     pathName get
          Returns the currently selected option menu item.

     pathName index index
          Returns the numerical index corresponding to index.

     pathName insert index string ?string?
          Insert an item, or list of  items,  into  the  menu  at
          location index.

     pathName select index
          Select an item from the option menu to be displayed  as
          the currently selected item.

     pathName sort mode
          Sort the current menu in either ascending, or  descend-
          ing  order.   The  values increasing, or decreasing are
          also accepted.

COMPONENTS

     Name:           menuBtn
     Class:          Frame

          The menuBtn component is the option menu  button  which
          displays  the  current choice from the popup menu.  See
          the "frame" widget manual  entry  for  details  on  the
          menuBtn component item.

     Name:           menuLabel
     Class:          Label

          The menuLabel component is the label whose text is  the
          currently selected choice from the popup menu.  See the
          "label" widget manual entry for details on the  menuLa-
          bel component item.

     Name:           popupMenu
     Class:          Menu

          The popupMenu component is menu displayed  upon  selec-
          tion of the menu button.  The menu contains the choices
          for the option menu.   See  the  "menu"  widget  manual
          entry for details on the popupMenu component item.

EXAMPLE

           optionmenu .om -labelmargin 5 \
               -labelon true -labelpos w -labeltext "Operating System :" \
               -items {Unix VMS Linux OS/2 {Windows NT} DOS}

           .om insert end CPM {MS DOS} HP/UX
           .om sort ascending
           .om select Linux

           pack .om  -padx 10 -pady 10

ACKNOWLEDGEMENTS:

     Michael J. McLennan

          Borrowed some ideas (next & previous) from OptionButton
          class.

     Steven B. Jaggers

          Provided an initial prototype in [incr Tcl].

     Bret Schuhmacher

          Helped with popup menu functionality.

AUTHOR

     Alfredo Jahn

KEYWORDS

     optionmenu, widget
itcl2.2/html/iwidgets2.2.0/panedwindow.n.html100666 1751 0 31523 6423554640 17674 0ustar kunkeewheel iwidgets2.2.0 User Commands - panedwindow

iwidgets2.2.0 User Commands - panedwindow

NAME

     panedwindow - Create and manipulate a paned window widget

SYNOPSIS

     panedwindow pathName ?options?

INHERITANCE

     itk::Widget <- panedwindow

STANDARD OPTIONS

     background      cursor

     See the "options" manual entry for details on  the  standard
     options.

WIDGET-SPECIFIC OPTIONS

     Name:           height
     Class:          Height
     Command-Line Switch:           -height

          Specifies the overall height of the paned window in any
          of  the  forms acceptable to Tk_GetPixels.  The default
          is 10 pixels.

     Name:           orient
     Class:          Orient
     Command-Line Switch:           -orient

          Specifies the orientation of the  separators:  vertical
          or horizontal.  The default is horizontal.

     Name:           sashBorderWidth
     Class:          BorderWidth
     Command-Line Switch:           -sashborderwidth

          Specifies a value  indicating  the  width  of  the  3-D
          border to draw around the outside of the sash in any of
          the forms acceptable to Tk_GetPixels.  The default is 2
          pixels.

     Name:           sashCursor
     Class:          Cursor
     Command-Line Switch:           -sashcursor

          Specifies the type of cursor to  be  displayed  in  the
          sash.  The default is crosshair.

     Name:           sashHeight
     Class:          Height
     Command-Line Switch:           -sashheight
          Specifies the height of the sash in any  of  the  forms
          acceptable to Tk_GetPixels.  The default is 10 pixels.

     Name:           sashIndent
     Class:          SashIndent
     Command-Line Switch            sashindent

          Specifies the placement of the sash along the panes  in
          any  of  the forms acceptable to Tk_GetPixels.  A posi-
          tive value causes the sash to be offset from  the  near
          (left/top)  side  of  the  pane,  and  a negative value
          causes  the  sash   to   be   offset   from   the   far
          (right/bottom) side.  If the offset is greater than the
          width, then the sash is placed flush against the  side.
          The default is -10 pixels.

     Name:           sashWidth
     Class:          Width
     Command-Line Switch:           -sashwidth

          Specifies the width of the sash in  any  of  the  forms
          acceptable to Tk_GetPixels.  The default is 10 pixels.

     Name:           thickness
     Class:          Thickness
     Command-Line Switch:           -thickness

          Specifies the thickness of the separators in any of the
          forms  acceptable  to  Tk_GetPixels.   The default is 3
          pixels.

     Name:           width
     Class:          Width
     Command-Line Switch:           -width

          Specifies the overall width of the paned window in  any
          of  the  forms acceptable to Tk_GetPixels.  The default
          is 10 pixels.

DESCRIPTION

     The panedwindow command  creates  a  multiple  paned  window
     widget  capable  of orienting the panes either vertically or
     horizontally.  Each pane is itself a frame acting as a child
     site  for  other  widgets.   The border separating each pane
     contains a sash which allows user positioning of  the  panes
     relative to one another.

METHODS

     The panedwindow 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 com-
     mand.

     Many of the widget commands for the panedwindow take as  one
     argument  an  indicator of which pane of the paned window to
     operate on.  These indicators are called indexes  and  allow
     reference  and  manipulation  of  panes  regardless of their
     current map state.  Paned window indexes may be specified in
     any of the following forms:

     number      Specifies  the   pane   numerically,   where   0
                 corresponds  to the nearest (top/left-most) pane
                 of the paned window.

     end         Indicates the farthest (bottom/right-most)  pane
                 of the paned window.

     pattern     If the index doesn't satisfy one  of  the  above
                 forms  then  this  form  is  used.   Pattern  is
                 pattern-matched against the tag of each pane  in
                 the  panedwindow,  in  order  from  left/top  to
                 right/left, until a  matching  entry  is  found.
                 The rules of Tcl_StringMatch are used.

WIDGET-SPECIFIC METHODS

     pathName add tag ?option value option value?
          Adds a new pane to the paned window  on  the  far  side
          (right/bottom).   The  following  options may be speci-
          fied:

          -margin value
               Specifies the border distance between the pane and
               pane  contents  is  any of the forms acceptable to
               Tk_GetPixels.  The default is 8 pixels.

          -minimum value
               Specifies the minimum size that a pane's  contents
               may reach not inclusive of twice the margin in any
               of the  forms  acceptable  to  Tk_GetPixels.   The
               default is 10 pixels.

               The add method returns the path name of the pane.

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the panedwindow command.

     pathName childsite ?index?
          Returns a list of  the  child  site  path  names  or  a
          specific  child  site given an index.  The list is con-
          structed from the near side (left/top) to the far  side
          (right/bottom).

     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  correspond-
          ing  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 panedwindow command.

     pathName delete index
          Deletes a specified pane given an index.

     pathName fraction percentage  percentage  ?percentage  percentage
          Sets  the visible percentage of the panes.  Specifies a
          set of percentages which are  applied  to  the  visible
          panes  from  the  near  side (left/top).  The number of
          percentages must be equal  to  the  current  number  of
          visible (mapped) panes and add up to 100.

     pathName hide index
          Changes the visiblity of the specified pane, allowing a
          previously displayed pane to be visually removed rather
          than deleted.

     pathName index index
          Returns the numerical index corresponding to index.

     pathName insert index tag ?option value option value ...?
          Same as the add command except that it inserts the  new
          pane  just  before  the  one given by index, instead of
          appending to the end of the panedwindow.   The  option,
          and value arguments have the same interpretation as for
          the add widget command.

     pathName paneconfigure index ?options?
          This command  is  similar  to  the  configure  command,
          except that it applies to the options for an individual
          pane, whereas configure applies to the options for  the
          paned  window  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 reset
          Redisplays the pane window using default percentages.

     pathName show index
          Changes the visiblity of the specified pane, allowing a
          previously hidden pane to be displayed.

NOTES

          Dynamic changing of the margin and or  minimum  options
          to  values which make the current configuration invalid
          will block subsequent sash movement until the fractions
          are  modified  via  the fraction method.  For example a
          panedwindow is created with three panes and the minimum
          and margin options are at their default settings.  Next
          the user moves the sashes to compact the panes  to  one
          side.   Now,  if  the  minimum is increased on the most
          compressed pane via the paneconfigure method to a large
          enough  value,  then sash movement is blocked until the
          fractions are adjusted.  This situation is unusual  and
          under normal operation of the panedwindow, this problem
          will never occur.

EXAMPLE

           panedwindow .pw -width 300 -height 300
           .pw add top
           .pw add middle -margin 10
           .pw add bottom -margin 10 -minimum 10

           pack .pw -fill both -expand yes

           foreach pane [.pw childSite] {
              button $pane.b -text $pane -relief raised -borderwidth 2
              pack $pane.b -fill both -expand yes
           }

           .pw fraction 50 30 20
           .pw paneconfigure 0 -minimum 20
           .pw paneconfigure bottom -margin 15

ACKNOWLEDGEMENTS:

     Jay Schmidgall

          1994 - Base logic posted to comp.lang.tcl

     Joe Hidebrand <hildjj@fuentez.com>

          07/25/94  -   Posted   first   multipane   version   to
          comp.lang.tcl

          07/28/94 - Added support for vertical panes

     Ken Copeland <ken@hilco.com>

          09/28/95 - Smoothed out the  sash  movement  and  added
          squeezable panes.

AUTHOR

     Mark L. Ulferts

KEYWORDS

     panedwindow, widget
itcl2.2/html/iwidgets2.2.0/promptdialog.n.html100666 1751 0 15555 6423554640 20065 0ustar kunkeewheel iwidgets2.2.0 User Commands - promptdialog

iwidgets2.2.0 User Commands - promptdialog

NAME

     promptdialog - Create and manipulate a prompt dialog widget

SYNOPSIS

     promptdialog pathName ?options?

INHERITANCE

     itk::Toplevel <- dialogshell <- dialog <- promptdialog

STANDARD OPTIONS

     background      borderWidth    cursor          exportSelection
     foreground      highlightColor highlightThicknessinsertBackground
     insertBorderWidth              insertOffTime   insertOnTimeinsertWidth
     justify         relief         selectBackgroundselectBorderWidth
     selectForeground textVariable

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     show            state          width

     See the "entry" widget manual entry for details on the above
     associated options.

     childSitePos    fixed          invalid         textBackground
     textFont        validate

     See the "entryfield" widget manual entry for details on  the
     above associated options.

     labelBitmap     labelFont      labelImage      labelMargin
     olabelPos       labelText

     See the "labeledwidget" widget manual entry for  details  on
     the above associated options.

INHERITED OPTIONS

     buttonBoxPadX   buttonBoxPadY  buttonBoxPos    padX
     padY            separator      thickness

     See the "dialogshell" widget manual entry for details on the
     above inherited options.

     master          modality       title

     See the "shell" widget manual entry for details on the above
     inherited options.

DESCRIPTION

     The promptdialog command creates a prompt dialog similar  to
     the  OSF/Motif standard prompt dialog composite widget.  The
     promptdialog is derived from the dialog class  and  is  com-
     posed of a EntryField with commands to manipulate the dialog
     buttons.

METHODS

     The promptdialog command creates a  new  Tcl  command  whose
     name  is pathName.  This command may be used to invoke vari-
     ous operations on the widget.  It has the following  general
     form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.   The following commands are possible for promptdialog
     widgets:

ASSOCIATED METHODS

     delete          get            icursor         index
     insert          scan           selection       xview

     See the "entry" widget manual entry for details on the above
     associated methods.

     clear

     See the "entryfield" widget manual entry for details on  the
     above associated methods.

INHERITED METHODS

     add             buttonconfigure                defaulthide
     invoke          show

     See the "buttonbox" widget manual entry for details  on  the
     above inherited methods.

     childsite

     See the "dialogshell" widget manual entry for details on the
     above inherited methods.

     activate        center         deactivate

     See the "shell" widget manual entry for details on the above
     inherited methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the promptdialog 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  correspond-
          ing  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 promptdialog command.

COMPONENTS

     Name:           ef
     Class:          Entryfield

          The ef component is the entry field for user  input  in
          the  prompt dialog.  See the "entryfield" widget manual
          entry for details on the ef component item.

EXAMPLE

           option add *textBackground white

           promptdialog .pd -modality global -title Password -labeltext Password: -show *
           .pd buttonconfigure OK -command {.pd deactivate 1}
           .pd hide Apply
           .pd buttonconfigure Cancel -command {.pd deactivate 0}
           .pd hide Help

           if {[.pd activate]} {
               puts "Password entered: [.pd get]"
           } else {
               puts "Password prompt cancelled"
           }

AUTHOR

     Mark L. Ulferts

KEYWORDS

     promptdialog, dialog, dialogshell, shell, widget
itcl2.2/html/iwidgets2.2.0/pushbutton.n.html100666 1751 0 14072 6423554640 17570 0ustar kunkeewheel iwidgets2.2.0 User Commands - pushbutton

iwidgets2.2.0 User Commands - pushbutton

NAME

     pushbutton - Create and manipulate a push button widget

SYNOPSIS

     pushbutton pathName ?options?

INHERITANCE

     itk::Widget <- pushbutton

STANDARD OPTIONS

     activeBackground               activeForegroundanchorbackground
     bitmap          borderWidth    command         cursor
     disabledForeground             font            foregroundhighlightBackground
     highlightColor  highlightThickness             imagejustify
     padX            padY           state           text
     textVariable    underline      wrapLength

     See the "options" manual entry for details on  the  standard
     options.

WIDGET-SPECIFIC OPTIONS

     Name:           defaultRing
     Class:          DefaultRing
     Command-Line Switch:           -defaultring

          Boolean describing  whether  the  button  displays  its
          default  ring  given  in any of the forms acceptable to
          Tcl_GetBoolean.  The default is false.

     Name:           defaultRingPad
     Class:          Pad
     Command-Line Switch:           -defaultringpad

          Specifies the amount of space to be  allocated  to  the
          indentation  of  the  default ring ring given in any of
          the forms acceptable to Tcl_GetPixels.  The option  has
          no  effect  if  the defaultring option is set to false.
          The default is 2 pixels.

     Name:           height
     Class:          Height
     Command-Line Switch:           -height

          Specifies the height of the  button  inclusive  of  any
          default  ring  given  in any of the forms acceptable to
          Tk_GetPixels.  A value of zero  lets  the  push  button
          determine the height based on the requested height plus
          highlightring and defaultringpad.


     Name:           width
     Class:          Width
     Command-Line Switch:           -width

          Specifies the width of  the  button  inclusive  of  any
          default  ring  given  in any of the forms acceptable to
          Tk_GetPixels.  A value of zero  lets  the  push  button
          determine  the  width based on the requested width plus
          highlightring and defaultringpad.

DESCRIPTION

     The  pushbutton  command  creates  a  push  button  with  an
     optional  default  ring  used  for  default  designation and
     traversal.

METHODS

     The pushbutton 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 com-
     mand.   The  following  commands are possible for pushbutton
     widgets:

ASSOCIATED METHODS

     flash           invoke

     See the "button" manual entry for details on the  associated
     methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the pushbutton 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  pushbutton
          command.

COMPONENTS

     Name:           pushbutton
     Class:          Button

          The pushbutton component is the  button  surrounded  by
          the  optional  default  ring.   See the "button" widget
          manual entry for details on  the  pushbutton  component
          item.

EXAMPLE

          pushbutton .pb -text "Hello" -command {puts "Hello World"} -defaultring 1
          pack .pb -padx 10 -pady 10

AUTHOR

     Bret A. Schuhmacher

     Mark L. Ulferts

KEYWORDS

     pushbutton, widget
itcl2.2/html/iwidgets2.2.0/radiobox.n.html100666 1751 0 17023 6423554640 17163 0ustar kunkeewheel iwidgets2.2.0 User Commands - radiobox

iwidgets2.2.0 User Commands - radiobox

NAME

     radiobox - Create and manipulate a radiobox widget

SYNOPSIS

     radiobox pathName ?options?

INHERITANCE

     itk::Widget <- labeledwidget <- radiobox

STANDARD OPTIONS

     background      borderWidth    cursor          foreground
     relief

     See the "options" manual entry for details on  the  standard
     options.

INHERITED OPTIONS

     labelBitmap     labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable

     See the "labeledwidget" class manual entry  for  details  on
     the inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:   command
     Class:  Command
     Command-Line Switch:    -command

          Specifies a Tcl command procedure to be evaluated  fol-
          lowing a  change in the current radio box selection.

DESCRIPTION

     The radiobox command creates a radio button box widget capa-
     ble of adding, inserting, deleting, selecting, and configur-
     ing radiobuttons as well as obtaining the currently selected
     button.

METHODS

     The radiobox command creates a new Tcl command whose name is
     pathName.  This command may be used to invoke various opera-
     tions on the widget.  It has the following general form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.
     Many of the widget commands for the  radiobox  take  as  one
     argument  an  indicator of which radiobutton of the radiobox
     to operate on.  These  indicators  are  called  indexes  and
     allow  reference and manipulation of radiobuttons.  Radiobox
     indexes may be specified in any of the following forms:

     number      Specifies the radiobutton numerically,  where  0
                 corresponds   to  the  top  radiobutton  of  the
                 radiobox.

     end         Indicates the last radiobutton of the radiobox.

     pattern     If the index doesn't satisfy one  of  the  above
                 forms  then  this  form  is  used.   Pattern  is
                 pattern-matched  against   the   tag   of   each
                 radiobutton  in  the radiobox, in order from top
                 to bottom, until a matching entry is found.  The
                 rules of Tcl_StringMatch are used.

WIDGET-SPECIFIC METHODS

     pathName add tag ?option value option value?
          Adds a new radiobutton to the  radiobuttond  window  on
          the bottom.  The command takes additional options which
          are passed on to the radiobutton as construction  argu-
          ments.   These  include  the  standard  Tk  radiobutton
          options.  The tag is returned.

     pathName buttonconfigure index ?options?
          This command  is  similar  to  the  configure  command,
          except that it applies to the options for an individual
          radiobutton, whereas configureapplies  to  the  options
          for  the  radiobox as a whole.  Options may have any of
          the values accepted by  the  add  widget  command.   If
          options  are  specified,  options are modified as indi-
          cated 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 cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the radiobox 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  correspond-
          ing  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 radiobox command.

     pathName delete index
          Deletes a specified radiobutton given an index.

     pathName deselect index
          Deselects a specified radiobutton given an index.

     pathName flash index
          Flashes a specified radiobutton given an index.

     pathName get
          Returns the tag of the currently selected radiobutton.

     pathName index index
          Returns the numerical index corresponding to index.

     pathName insert index tag ?option value option value ...?
          Same as the add command except that it inserts the  new
          radiobutton just before the one given by index, instead
          of appending to the end of the radiobox.   The  option,
          and value arguments have the same interpretation as for
          the add widget command.

     pathName select index
          Selects a specified radiobutton given an index.

EXAMPLE

           radiobox .rb -labeltext Fonts
           .rb add times -text Times
           .rb add helvetica -text Helvetica
           .rb add courier -text Courier
           .rb add symbol -text Symbol
           .rb select courier

           pack .rb -padx 10 -pady 10 -fill both -expand yes

AUTHOR

     Michael J. McLennan

     Mark L. Ulferts

KEYWORDS

     radiobox, widget
itcl2.2/html/iwidgets2.2.0/scrolledcanvas.n.html100666 1751 0 25024 6423554640 20357 0ustar kunkeewheel iwidgets2.2.0 User Commands - scrolledcanvas

iwidgets2.2.0 User Commands - scrolledcanvas

NAME

     scrolledcanvas - Create and manipulate scrolled canvas widg-
     ets

SYNOPSIS

     scrolledcanvas pathName ?options?

INHERITANCE

     itk::Widget <- Labeledwidget <- scrolledcanvas

STANDARD OPTIONS

     activeBackground               background      borderWidthcursor
     exportSelection font           foreground      highlightColor
     highlightThickness             insertBorderWidthinsertOffTimeinsertOnTime
     insertWidth     relief         repeatDelay     repeatInterval
     selectBackground               selectBorderWidthselectForeground

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     closeEnough     confine        scrollRegion    xScrollIncrement
     yScrollIncrement

     See the "canvas" widget manual  entry  for  details  on  the
     above associated options.

     activeRelief    elementBorderWidth             jumptroughColor

     See the "scrollbar" widget manual entry for details  on  the
     above associated options.

INHERITED OPTIONS

     labelBitmap     labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable

     See the "labeledwidget" class manual entry  for  details  on
     the inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           autoMargin
     Class:          AutoMargin
     Command-Line Switch:           -automargin

          Specifies the autoresize extra margin to reserve.  This
          option  is  only  effective  with autoresize turned on.
          The default is 10.

     Name:           autoResize
     Class:          AutoResize
     Command-Line Switch:           -autoresize

          Automatically adjusts the scrolled  region  to  be  the
          bounding  box covering all the items in the canvas fol-
          lowing the execution of any  method  which  creates  or
          destroys  items.   Thus,  as  new  items are added, the
          scrollbars adjust accordingly.

     Name:           height
     Class:          Height
     Command-Line Switch:           -height

          Specifies the height of the scrolled canvas  widget  in
          any  of  the  forms  acceptable  to  Tk_GetPixels.  The
          default height is 30 pixels.

     Name:           hscrollMode
     Class:          ScrollMode
     Command-Line Switch:           -hscrollmode

          Specifies the the display mode to be used for the  hor-
          izontal scrollbar: static, dynamic, or none.  In static
          mode,  the  scroll  bar  is  displayed  at  all  times.
          Dynamic  mode  displays the scroll bar as required, and
          none disables the scroll bar display.  The  default  is
          static.

     Name:           sbWidth
     Class:          Width
     Command-Line Switch:           -sbwidth

          Specifies the width of the  scrollbar  in  any  of  the
          forms acceptable to Tk_GetPixels.  The default width is
          15 pixels..

     Name:           scrollMargin
     Class:          ScrollMargin
     Command-Line Switch:           -scrollmargin

          Specifies the distance between the canvas and scrollbar
          in  any  of  the forms acceptable to Tk_GetPixels.  The
          default is 3 pixels.

     Name:           textBackground
     Class:          Background
     Command-Line Switch -textbackground

          Specifies the background color for  the  canvas.   This
          allows the background within the canvas to be different
          from the normal background color.


     Name:           vscrollMode
     Class:          ScrollMode
     Command-Line Switch:           -vscrollmode

          Specifies the the display mode to be used for the vert-
          ical  scrollbar:  static,  dynamic, or none.  In static
          mode,  the  scroll  bar  is  displayed  at  all  times.
          Dynamic  mode  displays the scroll bar as required, and
          none disables the scroll bar display.  The  default  is
          static.

     Name:           width
     Class:          Width
     Command-Line Switch:           -width

          Specifies the width of the scrolled  canvas  widget  in
          any  of  the  forms  acceptable  to  Tk_GetPixels.  The
          default height is 30 pixels.

DESCRIPTION

     The scrolledcanvas command creates a  scrolled  canvas  with
     additional   options   to  manage  horizontal  and  vertical
     scrollbars.   This  includes  options   to   control   which
     scrollbars  are displayed and the method, i.e. statically or
     dynamically.

METHODS

     The scrolledcanvas command creates a new Tcl  command  whose
     name  is pathName.  This command may be used to invoke vari-
     ous operations on the widget.  It has the following  general
     form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.   The following commands are possible for scrolledcan-
     vas widgets:

ASSOCIATED METHODS

     addtag          bbox           bind            canvasx
     canvasy         coords         create          dchars
     delete          dtag           find            focus
     gettags         icursor        index           insert
     itemconfigure   lower          move            postscript
     raise           scale          scan            select
     type            xview          yview

     See the "canvas" manual entry for details on the  associated
     methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the scrolledcanvas command.

     pathName childsite
          Returns the child site widget path name.

     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  correspond-
          ing  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 scrolledcanvas command.

     pathName justify direction
          Justifies the canvas contents via the  scroll  bars  in
          one of four directions:  left, right, top, or bottom.

COMPONENTS

     Name:           scrCanvas
     Class:          Canvas

          The scrCanvas component is the canvas widget.  See  the
          "canvas" widget manual entry for details on the scrCan-
          vas component item.

     Name:           hSB
     Class:          Scrollbar

          The hSB component is the horizontal  scroll  bar.   See
          the  "ScrollBar" widget manual entry for details on the
          hSB component item.

     Name:           vSB
     Class:          Scrollbar

          The vSB component is the vertical scroll bar.  See  the
          "ScrollBar"  widget manual entry for details on the vSB
          component item.

EXAMPLE

            scrolledcanvas .sc

            .sc create rectangle 100 100 400 400 -fill red
            .sc create rectangle 300 300 600 600 -fill green
            .sc create rectangle 200 200 500 500 -fill blue

            pack .sc -padx 10 -pady 10 -fill both -expand yes

AUTHOR

     Mark L. Ulferts

KEYWORDS

     scrolledcanvas, canvas, widget
itcl2.2/html/iwidgets2.2.0/scrolledframe.n.html100666 1751 0 23046 6423554640 20200 0ustar kunkeewheel iwidgets2.2.0 User Commands - scrolledframe

iwidgets2.2.0 User Commands - scrolledframe

NAME

     scrolledframe - Create and manipulate scrolled frame widgets

SYNOPSIS

     scrolledframe pathName ?options?

INHERITANCE

     itk::Widget <- Labeledwidget <- scrolledframe

STANDARD OPTIONS

     activeBackground               background      borderWidthcursor
     font            foreground     highlightColor  highlightThickness
     relief          repeatDelay    repeatInterval  selectBackground
     selectBorderWidth              selectForeground

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     activeRelief    elementBorderWidth             jumptroughColor

     See the "scrollbar" manual entry for details on the  associ-
     ated options.

INHERITED OPTIONS

     LabelBitmap     labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable

     See the "labeledwidget" class manual entry  for  details  on
     the inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           height
     Class:          Height
     Command-Line Switch:           -height

          Specifies the height of the scrolled  frame  widget  in
          any  of  the  forms  acceptable  to  Tk_GetPixels.  The
          default height is 100 pixels.

     Name:           hscrollMode
     Class:          ScrollMode
     Command-Line Switch:           -hscrollmode

          Specifies the the display mode to be used for the  hor-
          izontal scrollbar: static, dynamic, or none.  In static
          mode,  the  scroll  bar  is  displayed  at  all  times.
          Dynamic  mode  displays the scroll bar as required, and
          none disables the scroll bar display.  The  default  is
          static.

     Name:           sbWidth
     Class:          Width
     Command-Line Switch:           -sbwidth

          Specifies the width of the  scrollbar  in  any  of  the
          forms acceptable to Tk_GetPixels.  The default width is
          15 pixels.

     Name:           scrollMargin
     Class:          Margin
     Command-Line Switch:           -scrollmargin

          Specifies the distance between the frame and  scrollbar
          in  any  of  the forms acceptable to Tk_GetPixels.  The
          default is 3 pixels.

     Name:           vscrollMode
     Class:          ScrollMode
     Command-Line Switch:           -vscrollmode

          Specifies the the display mode to be used for the vert-
          ical  scrollbar:  static,  dynamic, or none.  In static
          mode,  the  scroll  bar  is  displayed  at  all  times.
          Dynamic  mode  displays the scroll bar as required, and
          none disables the scroll bar display.  The  default  is
          static.

     Name:           width
     Class:          Width
     Command-Line Switch:           -width

          Specifies the width of the scrolled frame widget in any
          of  the  forms acceptable to Tk_GetPixels.  The default
          height is 100 pixels.

DESCRIPTION

     The scrolledframe combines the functionallity  of  scrolling
     with  that of a typical frame widget to implement a clipable
     viewing area whose visible region may be modified  with  the
     scroll bars. This enables the contruction of visually larger
     areas than which could normally be displayed,  containing  a
     heterogenous mix of other widgets. Options exist which allow
     full control over which scrollbars  are  displayed  and  the
     method, i.e. statically or dynamically. The frame itself may
     be accessed by the childsite method  and  then  filled  with
     other widget combinations.

METHODS


     The scrolledframe command creates a new  Tcl  command  whose
     name  is pathName.  This command may be used to invoke vari-
     ous operations on the widget.  It has the following  general
     form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.  The following commands are possible for scrolledframe
     widgets:

ASSOCIATED METHODS

     xview           yview

     See the "canvas" manual entry for details on the  associated
     methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the scrolledframe command.

     pathName childsite
          Return the path name of the child site.

     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  correspond-
          ing  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 scrolledframe command.

     pathName justify direction
          Justifies the frame contents via the scroll bars in one
          of four directions:  left, right, top, or bottom.

COMPONENTS

     Name:           canvasFrame
     Class:          Frame

          The  canvasFrame  component  provides  relief  for  the
          scrCanvas  component.   See  the  "frame" widget manual
          entry for details on the canvasFrame component item.

     Name:           scrCanvas
     Class:          Canvas

          The scrCanvas component provides the  scrolling  region
          for the scrolled frame.  See the "canvas" widget manual
          entry for details on the scrCanvas component item.

     Name:           scrFrame
     Class:          Frame

          The scrFrame component is  internal  to  the  scrCanvas
          component,  providing  a  container for children of the
          scrolled frame.  See the "frame"  widget  manual  entry
          for details on the scrFrame component item.

     Name:           hSB
     Class:          Scrollbar

          The hSB component is the horizontal  scroll  bar.   See
          the  "ScrollBar" widget manual entry for details on the
          hSB component item.

     Name:           vSB
     Class:          Scrollbar

          The vSB component is the vertical scroll bar.  See  the
          "ScrollBar"  widget manual entry for details on the vSB
          component item.

EXAMPLE

          scrolledframe .sf -width 150 -height 180 -labelon yes -labeltext scrolledframe

          set cs [.sf childsite]
          pack [button $cs.b1 -text Hello] -pady 10
          pack [button $cs.b2 -text World] -pady 10
          pack [button $cs.b3 -text "This is a test"] -pady 10
          pack [button $cs.b4 -text "This is a really big button"] -pady 10
          pack [button $cs.b5 -text "This is another really big button"] -pady 10
          pack [button $cs.b6 -text "This is the last really big button"] -pady 10

          pack .sf -expand yes -fill both -padx 10 -pady 10

AUTHOR

     Sue Yockey

     Mark L. Ulferts

KEYWORDS

     scrolledframe, frame, widget
itcl2.2/html/iwidgets2.2.0/scrolledhtml.n.html100666 1751 0 37555 6423554640 20064 0ustar kunkeewheel iwidgets2.2.0 User Commands - scrolledhtml

iwidgets2.2.0 User Commands - scrolledhtml

NAME

     scrolledhtml - Create and manipulate a scrolled text  widget
     with the capability of displaying HTML formatted documents.

SYNOPSIS

     scrolledhtml pathName ?options?

INHERITANCE

     itk::Widget <- Labeledwidget <- Scrolledtext <- Scrolledhtml

STANDARD OPTIONS

     activeBackground               background      borderWidthcursor
     exportSelection foreground     highlightColor  highlightThickness
     insertBackground               insertBorderWidthinsertOffTimeinsertOnTime
     insertWidth     padX           padY            relief
     repeatDelay     repeatInterval selectBackgroundselectBorderWidth
     selectForeground               setGrid

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     activeRelief    elementBorderWidth             jumptroughColor

     See the "scrollbar" widget manual entry for details  on  the
     above associated options.

     spacing1        spacing2       spacing3        state
     wrap

     See the "text" widget manual entry for details on the  above
     associated options.

INHERITED OPTIONS

     labelBitmap     labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable   height
     hscrollMode     sbWidth        scrollMargin    visibleitems
     vscrollMode     width

     See the "scrolledtext" class manual entry for details on the
     inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           feedback
     Class:          FeedBack
     Command-Line Switch:           -feedback

          Specifies the callback command to use to give  feedback
          on current status.  Two integers are appended onto this
          command.  They  represent  the  current  point  in  the
          rendering  process, and the maximum point.  The maximum
          depends on the length of the text being rendered.

     Name:           fixedfont
     Class:          FixedFont
     Command-Line Switch:           -fixedfont

          Specifies the name of the font to be  used  for  fixed-
          width   character   text  (such  as  <pre>...</pre>  or
          <tt>...</tt>.) The size, style, and other  font  attri-
          butes  are  determined  by the format tags in the docu-
          ment. The default is courier.

     Name:           fontname
     Class:          FontName
     Command-Line Switch:           -fontname

          Specifies the name of the font to be used  for  normal-
          width character spaced text. The size, style, and other
          font attributes are determined by the  format  tags  in
          the document. The default is times.

     Name:           fontsize
     Class:          FontSize
     Command-Line Switch:           -fontsize

          Specifies the general size of the fonts  used.  One  of
          small, medium, large, or huge. The default is medium.

     Name:           foreground
     Class:          Foreground
     Command-Line Switch:           -foreground

          Specifies the color of text other than hypertext links,
          in  any  of  the  forms acceptable to Tk_GetColor. This
          value may be overridden in a particular document by the
          text attribute of the Body HTML tag.

     Name:           link
     Class:          Link
     Command-Line Switch:           -link

          Specifies the default color of hypertext links  in  any
          of  the forms acceptable to Tk_GetColor. This value may
          be overridden in a  particular  document  by  the  link
          attribute of the Body HTML tag. The default is blue.

     Name:           linkcommand
     Class:          LinkCommand
     Command-Line Switch:           -linkcommand

          Specifies the command to execute when the  user  clicks
          on  a hypertext link. Execution is of the form linkcom-
          mand href, where href is the value given  in  the  href
          attribute of the A HTML tag.

     Name:           linkhighlight
     Class:          LinkHighlight
     Command-Line Switch:           -linkhighlight

          Specifies the color of hypertext links when the  cursor
          is  over  the  link  in  any of the forms acceptable to
          Tk_GetColor. The default is red.

     Name:           textBackground
     Class:          Background
     Command-Line Switch:           -textbackground

          Specifies the background color for the text area in any
          of  the forms acceptable to Tk_GetColor. This value may
          be overridden in a particular document by  the  bgcolor
          attribute of the Body HTML tag.

     Name:           unknownimage
     Class:          UnknownImage
     Command-Line Switch:           -unknownimage

          Specifies the name of the image file to display when an
          img specified in the html document cannot be loaded.

DESCRIPTION

     The scrolledhtml command creates a scrolled text widget with
     the  additional  capability  to display html formatted docu-
     ments.  An import method is provided to read an  html  docu-
     ment file, and a render method is provided to display a html
     formatted text string.

METHODS

     The scrolledhtml command creates a  new  Tcl  command  whose
     name  is pathName.  This command may be used to invoke vari-
     ous operations on the widget.  It has the following  general
     form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.   The following commands are possible for scrolledhtml
     widgets:

ASSOCIATED METHODS

     bbox            compare        debug           delete
     dlineinfo       get            index           insert
     mark            scan           search          see
     tag             window         xview           yview

     See the "text" manual entry  for  details  on  the  standard
     methods.

INHERITED METHODS

     export          clear

     See the "scrolledhtml"  manual  entry  for  details  on  the
     inherited methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the scrolledhtml 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  correspond-
          ing  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 scrolledhtml command.

     pathName import ?option? href
          Load html formatted text from a file.  Href must exist.
          If  option  is -link, href is assumed to be relative to
          the application's current working directory. Otherwise,
          href  is assumed to be relative to the path of the last
          page loaded. Href is either a filename, or a  reference
          of  the  form  filename#anchorname. In the latter form,
          fIFilename and/or anchorname may be empty. If  filename
          is  empty,  the current document is assumed. If anchor-
          name is empty, the top of the document is assumed.

     pathName pwd
          Print the current working directory of the widget, i.e.
          the directory of the last page loaded.

     pathName render htmltext ?wd?
          Display HTML formatted text htmltext. Wd gives the base
          path  to  use for all links and images in the document.
          Wd defaults to the application's current working direc-
          tory.

     pathName title
          Return the title of the current page, as given  in  the
          <title>...</title> field in the document.

SUPPORTED HTML TAGS

     a               /code          h5              /samp
     /a              dir            /h5             small
     address         /dir           h6              /small
     /address        dl             /h6             sub
     b               /dl            i               /sub
     /b              dt             /i              sup
     base            dd             img             /sup
     big             dfn            kbd             strong
     /big            /dfn           li              /strong
     blockquote      em             listing         title
     /blockquote     /em            /listing        /title
     body            h1             menu            tt
     /body           /h1            /menu           /tt
     br              h2             ol              u
     center          /h2            /ol             /u
     /center         h3             p               ul
     cite            /h3            pre             /ul
     /cite           h4             /pre            var
     code            /h4            samp            /var

TAGS WITH ATTRIBUTES

     a

          href reference  to   html   document,   of   the   form
               filename#anchorname

          name name of this anchor, to be used in an href

          id   same as name

     body

          bgcolor
               background color

          link color of hypertext links

          text color of text

     hn
          align
               text alignment, one of left, right, or center

          src  path to image to precede text

     hr

          noshade
               if present, indicates the rule should be  a  plain
               black line

          size height of the rule, in pixels

     img

          alt  text to display in place of image if image is  not
               found

          height
               height of area to reserve if image is not found

          src  filename of image

          width
               width of area to reserve if image is not found

     p

          align
               alignment of following  paragraph,  one  of  left,
               right,  or center. Defaults to alignment of previ-
               ous paragraph, or left for first paragraph

          id   ID for use as anchorname in a link to  this  docu-
               ment

     ul

          plain
               if present list will not use bullets

          src  image to use as bullet

          dingbat
               same as src

EXAMPLE

           option add *textBackground white

           scrolledhtml .sh -fontname helvetica -linkcommand "this import -link"

           pack .sh -padx 10 -pady 10 -fill both -expand yes
           .sh import ~/public_html/index.html

ACKNOWLEDGEMENTS

     Sam Shen

          This code is based largely on his tkhtml.tcl code  from
          tk  inspect. Tkhtml is copyright 1995 Lawrence Berkeley
          Laboratory.

AUTHOR

     Kris Raney

KEYWORDS

     scrolledhtml, html, text, widget
itcl2.2/html/iwidgets2.2.0/scrolledlistbox.n.html100666 1751 0 36207 6423554640 20575 0ustar kunkeewheel iwidgets2.2.0 User Commands - scrolledlistbox

iwidgets2.2.0 User Commands - scrolledlistbox

NAME

     scrolledlistbox - Create  and  manipulate  scrolled  listbox
     widgets

SYNOPSIS

     scrolledlistbox pathName ?options?

INHERITANCE

     itk::Widget <- Labeledwidget <- Scrolledlistbox

STANDARD OPTIONS

     activeBackground               background      borderWidthcursor
     exportSelection foreground     highlightColor  highlightThickness
     relief          repeatDelay    repeatInterval  selectBackground
     selectBorderWidth              selectForeground

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     selectMode

     See the "listbox" widget manual entry  for  details  on  the
     above associated options.

     activeRelief    elementBorderwidth             jumptroughColor

     See the "scrollbar" widget manual entry for details  on  the
     above associated options.

INHERITED OPTIONS

     labeledBitmap   labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable

     See the "labeledwidget" class manual entry  for  details  on
     the inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           dblClickCommand
     Class:          Command
     Command-Line Switch:           -dblclickcommand

          Specifies a Tcl command procedure which is called  when
          an  item is double clicked.  Typically this occurs when
          mouse button 1 is double clicked over an item.   Selec-
          tion policy does not matter.

     Name:           height
     Class:          Height
     Command-Line Switch:           -height
          Specifies the height of the scrolled  list  box  as  an
          entire  unit.  The value may be specified in any of the
          forms acceptable to Tk_GetPixels.  Any additional space
          needed  to display the other components such as labels,
          margins,  and  scrollbars  force  the  listbox  to   be
          compressed.   A value of zero along with the same value
          for the width causes the  value  given  for  the  visi-
          bleitems   option   to  be  applied  which  administers
          geometry  constraints  in  a  different  manner.    The
          default height is zero.

     Name:           hscrollMode
     Class:          ScrollMode
     Command-Line Switch:           -hscrollmode

          Specifies the the display mode to be used for the  hor-
          izontal scrollbar: static, dynamic, or none.  In static
          mode,  the  scroll  bar  is  displayed  at  all  times.
          Dynamic  mode  displays the scroll bar as required, and
          none disables the scroll bar display.  The  default  is
          static.

     Name:           items
     Class:          Items
     Command-Line Switch:           -items

          Specifies the contents of the listbox as a proper  list
          of elements.

     Name:           sbWidth
     Class:          Width
     Command-Line Switch:           -sbwidth

          Specifies the width of the  scrollbar  in  any  of  the
          forms acceptable to Tk_GetPixels.  The default width is
          15 pixels..

     Name:           scrollMargin
     Class:          Margin
     Command-Line Switch:           -scrollmargin

          Specifies  the  distance  between   the   listbox   and
          scrollbar   in   any   of   the   forms  acceptable  to
          Tk_GetPixels.  The default is 3 pixels.

     Name:           selectionCommand
     Class:          Command
     Command-Line Switch:           -selectioncommand

          Specifies a Tcl command procedure which is called  when
          an item is selected.  Selection policy does not matter.

     Name:           textBackground
     Class:          Background
     Command-Line Switch -textbackground

          Specifies the background color for the  listbox.   This
          allows  the  background  within  the listbox to be dif-
          ferent from the normal background color.

     Name:           textFont
     Class:          Font
     Command-Line Switch:           -textfont

          Specifies the font to be used for text in the  listbox.
          This  allows for the font associated with text internal
          to the scrolled listbox to be different than  the  font
          for labels.

     Name:           visibleitems
     Class:          VisibleItems
     Command-Line Switch:           -visibleitems

          Specifies the widthxheight in characters and lines  for
          the  listbox.   This option is only administered if the
          width and height options are both set to  zero,  other-
          wise they take precedence.  The default value is 20x10.
          With the visibleitems  option  engaged,  geometry  con-
          straints  are maintained only on the listbox.  The size
          of the other components such as  labels,  margins,  and
          scroll  bars,  are  additive and independent, effecting
          the overall size of the scrolled  list  box.   In  con-
          trast,  should  the  width  and height options have non
          zero values, they are applied to the scrolled list  box
          as  a  whole.  The listbox is compressed or expanded to
          maintain the geometry constraints.

     Name:           vscrollMode
     Class:          ScrollMode
     Command-Line Switch:           -vscrollmode

          Specifies the the display mode to be used for the vert-
          ical  scrollbar:  static,  dynamic, or none.  In static
          mode,  the  scroll  bar  is  displayed  at  all  times.
          Dynamic  mode  displays the scroll bar as required, and
          none disables the scroll bar display.  The  default  is
          static.

     Name:           width
     Class:          Width
     Command-Line Switch:           -width

          Specifies the width of the  scrolled  list  box  as  an
          entire  unit.  The value may be specified in any of the
          forms acceptable to Tk_GetPixels.  Any additional space
          needed  to display the other components such as labels,
          margins,  and  scrollbars  force  the  listbox  to   be
          compressed.   A value of zero along with the same value
          for the height causes the value  given  for  the  visi-
          bleitems   option   to  be  applied  which  administers
          geometry  constraints  in  a  different  manner.    The
          default width is zero.

DESCRIPTION

     The scrolledlistbox command creates a scrolled listbox  with
     additional   options   to  manage  horizontal  and  vertical
     scrollbars.   This  includes  options   to   control   which
     scrollbars  are displayed and the method, i.e. statically or
     dynamically.

METHODS

     The scrolledlistbox command creates a new Tcl command  whose
     name  is pathName.  This command may be used to invoke vari-
     ous operations on the widget.  It has the following  general
     form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.

     Many of the widget commands for a  scrolledlistbox  take  as
     one  argument an indicator of which entry of the list box to
     operate on.  These indicators are called indexes and may  be
     specified in any of the following forms:

     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 cur-
                 sor.   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 com-
                 mands  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.

     pattern     If the index doesn't satisfy one  of  the  above
                 forms  then  this  form  is  used.   Pattern  is
                 pattern-matched against the items  in  the  list
                 box,  in order from the top down, until a match-
                 ing   entry   is   found.     The    rules    of
                 Tcl_StringMatch are used.

     The following widget commands are possible for scrolledlist-
     box widgets:

ASSOCIATED METHODS

     activate        bbox           curselection    delete
     get             index          insert          nearest
     scan            see            selection       size
     xview           yview

     See the "listbox" manual entry for details on the associated
     methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the scrolledlistbox command.

     pathName clear
          Clears the listbox of all items.

     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  correspond-
          ing  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 scrolledlistbox command.

     pathName getcurselection
          Returns the contents of the listbox  element  indicated
          by the current selection indexes.  Short cut version of
          get and curselection command combination.

     pathName justify direction
          Justifies the list contents via teh scroll bars in  one
          of four directions:  left, right, top, or bottom.

     pathName selecteditemcount
          Returns the number of items currently selected  in  the
          list.

     pathName sort order
          Sort the current list in either ascending or descending
          order.  The  values  increasing and decreasing are also
          accepted.

COMPONENTS

     Name:           listbox
     Class:          listbox

          The listbox component is the listbox widget.   See  the
          "listbox"  widget manual entry for details on the list-
          box component item.

     Name:           horizsb
     Class:          Scrollbar

          The horizsb component is  the  horizontal  scroll  bar.
          See  the "scrollbar" widget manual entry for details on
          the horizsb component item.

     Name:           vertsb
     Class:          Scrollbar

          The vertsb component is the vertical scroll  bar.   See
          the  "scrollbar" widget manual entry for details on the
          vertsb component item.

EXAMPLE

          wm minsize . 0 0
          option add *textBackground white
          proc selCmd {} {
              puts stdout "[.slb getcurselection]"
          }
          proc defCmd {} {
              puts stdout "Double Click"
              return [selCmd]
          }
          scrolledlistbox .slb -selection single \
              -items {Hello {Out There} World} \
              -vscrollmode static -hscrollmode dynamic -labeltext "List" \
              -selectioncommand selCmd -dblclickcommand defCmd
          pack .slb -padx 10 -pady 10 -fill both -expand yes

AUTHOR

     Mark L. Ulferts

KEYWORDS

     scrolledlistbox, listbox, widget
itcl2.2/html/iwidgets2.2.0/scrolledtext.n.html100666 1751 0 27114 6423554640 20072 0ustar kunkeewheel iwidgets2.2.0 User Commands - scrolledtext

iwidgets2.2.0 User Commands - scrolledtext

NAME

     scrolledtext - Create and manipulate a scrolled text widget

SYNOPSIS

     scrolledtext pathName ?options?

INHERITANCE

     itk::Widget <- Labeledwidget <- Scrolledtext

STANDARD OPTIONS

     activeBackground               background      borderWidthcursor
     exportSelection foreground     highlightColor  highlightThickness
     insertBackground               insertBorderWidthinsertOffTimeinsertOnTime
     insertWidth     padX           padY            relief
     repeatDelay     repeatInterval selectBackgroundselectBorderWidth
     selectForeground               setGrid

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     activeRelief    elementBorderWidth             jumptroughColor

     See the "scrollbar" widget manual entry for details  on  the
     above associated options.

     spacing1        spacing2       spacing3        state
     wrap

     See the "text" widget manual entry for details on the  above
     associated options.

INHERITED OPTIONS

     labelBitmap     labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable

     See the "labeledwidget" class manual entry  for  details  on
     the inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           height
     Class:          Height
     Command-Line Switch:           -height

          Specifies the height of the scrolled text as an  entire
          unit.   The  value may be specified in any of the forms
          acceptable  to  Tk_GetPixels.   Any  additional   space
          needed  to display the other components such as labels,
          margins,  and  scrollbars  force   the   text   to   be
          compressed.   A value of zero along with the same value
          for the width causes the  value  given  for  the  visi-
          bleitems   option   to  be  applied  which  administers
          geometry  constraints  in  a  different  manner.    The
          default height is zero.

     Name:           hscrollMode
     Class:          ScrollMode
     Command-Line Switch:           -hscrollmode

          Specifies the the display mode to be used for the  hor-
          izontal scrollbar: static, dynamic, or none.  In static
          mode,  the  scroll  bar  is  displayed  at  all  times.
          Dynamic  mode  displays the scroll bar as required, and
          none disables the scroll bar display.  The  default  is
          static.

     Name:           sbWidth
     Class:          Width
     Command-Line Switch:           -sbwidth

          Specifies the width of the  scrollbar  in  any  of  the
          forms acceptable to Tk_GetPixels.

     Name:           scrollMargin
     Class:          Margin
     Command-Line Switch:           -scrollmargin

          Specifies  the  distance  between  the  text  area  and
          scrollbar   in   any   of   the   forms  acceptable  to
          Tk_GetPixels.  The default is 3 pixels.

     Name:           textBackground
     Class:          Background
     Command-Line Switch:           -textbackground

          Specifies the background color for the text area in any
          of the forms acceptable to Tk_GetColor.

     Name:           textFont
     Class:          Font
     Command-Line Switch:           -textfont

          Specifies the font to be  used  in  the  scrolled  text
          area.

     Name:           visibleitems
     Class:          VisibleItems
     Command-Line Switch:           -visibleitems

          Specifies the widthxheight in characters and lines  for
          the  text.   This  option  is  only administered if the
          width  and  height  options  are  both  set  to   zero,
          otherwise  they  take precedence.  The default value is
          80x24.  With the visibleitems option engaged,  geometry
          constraints  are maintained only on the text.  The size
          of the other components such as  labels,  margins,  and
          scroll  bars,  are  additive and independent, effecting
          the overall size of the scrolled  text.   In  contrast,
          should  the  width  and  height  options  have non zero
          values, they are applied to  the  scrolled  text  as  a
          whole.   The text is compressed or expanded to maintain
          the geometry constraints.

     Name:           vscrollMode
     Class:          ScrollMode
     Command-Line Switch:           -vscrollmode

          Specifies the the display mode to be used for the vert-
          ical  scrollbar:  static,  dynamic, or none.  In static
          mode,  the  scroll  bar  is  displayed  at  all  times.
          Dynamic  mode  displays the scroll bar as required, and
          none disables the scroll bar display.  The  default  is
          static.

     Name:           width
     Class:          Width
     Command-Line Switch:           -width

          Specifies the width of the scrolled text as  an  entire
          unit.   The  value may be specified in any of the forms
          acceptable  to  Tk_GetPixels.   Any  additional   space
          needed  to display the other components such as labels,
          margins,  and  scrollbars  force   the   text   to   be
          compressed.   A value of zero along with the same value
          for the height causes the value  given  for  the  visi-
          bleitems   option   to  be  applied  which  administers
          geometry  constraints  in  a  different  manner.    The
          default width is zero.

DESCRIPTION

     The scrolledtext command creates a scrolled text widget with
     additional  options to manage the scrollbars.  This includes
     options to control the method in which  the  scrollbars  are
     displayed,  i.e.  statically  or  dynamically.  Options also
     exist for adding a label to the scrolled text area and  con-
     trolling  its  position.   Import/export of methods are pro-
     vided for file I/O.

METHODS


     The scrolledtext command creates a  new  Tcl  command  whose
     name  is pathName.  This command may be used to invoke vari-
     ous operations on the widget.  It has the following  general
     form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.   The following commands are possible for scrolledtext
     widgets:

ASSOCIATED METHODS

     bbox            compare        debug           delete
     dlineinfo       get            index           insert
     mark            scan           search          see
     tag             window         xview           yview

     See the "text" manual entry  for  details  on  the  standard
     methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the scrolledtext command.

     pathName clear
          Clear the text area of all characters.

     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  correspond-
          ing  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 scrolledtext command.

     pathName import filename
          Load text from a file.  The filename must exist.

     pathName export filename
          Write text to a file.  If filename exists then contents
          are replaced with text widget contents.

COMPONENTS

     Name:           text
     Class:          Text

          The text component is the text widget.  See the  "text"
          widget  manual  entry for details on the text component
          item.

     Name:           horizsb
     Class:          Scrollbar

          The horizsb component is  the  horizontal  scroll  bar.
          See  the "scrollbar" widget manual entry for details on
          the horizsb component item.

     Name:           vertsb
     Class:          Scrollbar

          The vertsb component is the vertical scroll  bar.   See
          the  "scrollbar" widget manual entry for details on the
          vertsb component item.

EXAMPLE

           option add *textBackground white

           scrolledtext .st -scrollmode dynamic -labeltext "Password File"

           pack .st -padx 10 -pady 10 -fill both -expand yes

           .st import /etc/passwd

AUTHOR

     Mark L. Ulferts

KEYWORDS

     scrolledtext, text, widget
itcl2.2/html/iwidgets2.2.0/selectionbox.n.html100666 1751 0 26763 6423554641 20066 0ustar kunkeewheel iwidgets2.2.0 User Commands - selectionbox

iwidgets2.2.0 User Commands - selectionbox

NAME

     selectionbox - Create and manipulate a selection box widget

SYNOPSIS

     selectionbox pathName ?options?

INHERITANCE

     itk::Widget <- selectionbox

STANDARD OPTIONS

     activeBackground               background      borderWidthcursor
     exportSelection foreground     highlightColor  highlightThickness
     insertBackground               insertBorderWidthinsertOffTimeinsertOnTime
     insertWidth     relief         repeatDelay     repeatInterval
     selectBackground               selectBorderWidthselectForeground

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     textBackground  textFont

     See the "entryfield" widget class manual entry  for  details
     on the above associated options.

     labelFont       labelMargin

     See the "labeledwidget" class manual entry  for  details  on
     the above associated options.

     activeRelief    elementBorderWidth             jumptroughColor

     See the "scrollbar" widget class manual entry for details on
     the above associated options.

     dblClickCommand hscrollMode    items           sbWidth
     scrollMargin    textBackground textFont        vscrollMode

     See the "scrolledlistbox"  widget  class  manual  entry  for
     details on the above associated options.

WIDGET-SPECIFIC OPTIONS

     Name:           childSitePos
     Class:          Position
     Command-Line Switch:           -childsitepos

          Specifies the position of the child site in the  selec-
          tion box: n, s, e, w, or .  The default is center

     Name:           height
     Class:          Height
     Command-Line Switch:           -height

          Specifies the height of the selection box.   The  value
          may  be  specified  in  any  of the forms acceptable to
          Tk_GetPixels.  The default is 320 pixels.

     Name:           itemsCommand
     Class:          Command
     Command-Line Switch:           -itemscommand

          Specifies a command to be evaluated following selection
          of an item.

     Name:           itemsLabel
     Class:          Text
     Command-Line Switch:           -itemslabel

          Specifies the text of the label  for  the  items  list.
          The default is "List".

     Name:           itemsLabelPos
     Class:          Position
     Command-Line Switch:           -itemslabelpos

          Specifies the position of the label along the  side  of
          the  items  list:  n,  ne, e, se, s, sw, w, or nw.  The
          default is nw.

     Name:           itemsOn
     Class:          ItemsOn
     Command-Line Switch:           -itemson

          Specifies whether or not to display the items  list  in
          any  of  the  forms  acceptable to Tcl_GetBoolean.  The
          default is true.

     Name:           margin
     Class:          Margin
     Command-Line Switch:           -margin

          Specifies distance between the items list and selection
          entry  in  any of the forms acceptable to Tk_GetPixels.
          The default is 7 pixels.

     Name:           selectionCommand
     Class:          Command
     Command-Line Switch:           -selectioncommand

          Specifies a Tcl  procedure  to  be  associated  with  a
          return key press event in the selection entry field.

     Name:           selectionLabel
     Class:          Text
     Command-Line Switch:           -selectionlabel

          Specifies the text of the label for the selection entry
          field.  The default is "Selection".

     Name:           selectionLabelPos
     Class:          Position
     Command-Line Switch:           -selectionlabelpos

          Specifies the position of the label along the  side  of
          the  selection:  n,  ne,  e,  se, s, sw, w, or nw.  The
          default is nw.

     Name:           selectionOn
     Class:          SelectionOn
     Command-Line Switch:           -selectionon

          Specifies whether or not to display the selection entry
          in  any of the forms acceptable to Tcl_GetBoolean.  The
          default is true.

     Name:           width
     Class:          Width
     Command-Line Switch:           -width

          Specifies the width of the selection  box.   The  value
          may  be  specified  in  any  of the forms acceptable to
          Tk_GetPixels.  The default is 260 pixels.

DESCRIPTION

     The selectionbox command creates a scrolled  list  of  items
     and a selection entry field.  The user may choose any of the
     items displayed in the scrolled list of alternatives and the
     selection field will be filled with the choice.  The user is
     also free to enter a new value in the selection entry field.
     Both  the list and entry areas have labels.  A child site is
     also provided in which the user may create other widgets  to
     be used in conjunction with the selection box.

METHODS

     The selectionbox command creates a  new  Tcl  command  whose
     name  is pathName.  This command may be used to invoke vari-
     ous operations on the widget.  It has the following  general
     form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.

ASSOCIATED METHODS

     curselection    delete         index           nearest
     scan            selection      size

     See the "listbox" widget class manual entry for  details  on
     the associated methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the selectionbox command.

     pathName childsite
          Returns the child site widget path name.

     pathName clear component
          Delete the  contents  of  either  the  selection  entry
          widget  or  items  list.  The component argument may be
          either items or selection.

     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  correspond-
          ing  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 selectionbox command.

     pathName get
          Returns  the  current  value  of  the  selection  entry
          widget.

     pathName insert component args
          Insert  element(s)  into  either  the  selection  entry
          widget  or  items  list.  The component argument may be
          either items or selection.  The args follow  the  rules
          of either an entry or list widget depending on the com-
          ponent value.

     pathName selectitem
          Replace the selection entry  field  contents  with  the
          currently selected items value.

COMPONENTS

     Name:           childsite
     Class:          Frame

          The childsite component is the user child site for  the
          selection box.  See the "frame" widget manual entry for
          details on the childsite component item.

     Name:           items
     Class:          Scrolledlistbox

          The items component provides the scrolled list  box  of
          items for the selection box.  See the "scrolledlistbox"
          widget manual entry for details on the items  component
          item.

     Name:           selection
     Class:          Entryfield

          The selection component provides the entry field in the
          selection  box  for display of the selected item in the
          items component.  See the  "entryfield"  widget  manual
          entry for details on the selection component item.

EXAMPLE

           option add *textBackground white

           selectionbox .sb -items {Hello {Out There} World}
           pack .sb -padx 10 -pady 10 -fill both -expand yes

           set cs [label [.sb childsite].label -text "Child Site"]
           pack $cs -fill x -padx 10 -pady 10

           .sb insert items 2 {Cruel Cruel}

           .sb selection set 1

AUTHOR

     Mark L. Ulferts

KEYWORDS

     selectionbox, widget
itcl2.2/html/iwidgets2.2.0/selectiondialog.n.html100666 1751 0 17633 6423554641 20531 0ustar kunkeewheel iwidgets2.2.0 User Commands - selectiondialog

iwidgets2.2.0 User Commands - selectiondialog

NAME

     selectiondialog - Create and manipulate a  selection  dialog
     widget

SYNOPSIS

     selectiondialog pathName ?options?

INHERITANCE

     itk::Toplevel <- Shell <- Dialogshell <-  Dialog  <-  Selec-
     tiondialog

STANDARD OPTIONS

     activeBackground               background      borderWidthcursor
     exportSelection foreground     highlightColor  highlightThickness
     insertBackground               insertBorderWidthinsertOffTimeinsertOnTime
     insertWidth     relief         repeatDelay     repeatInterval
     selectBackground               selectBorderWidthselectForeground

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     textBackground  textFont

     See the "entryfield" widget manual entry for details on  the
     above associated options.

     labelFont       labelMargin

     See the "labeledwidget" widget manual entry for  details  on
     the above associated options.

     activeRelief    elementBorderWidth             jumptroughColor

     See the "scrollbar" widget class manual entry for details on
     the above associated options.

     hscrollMode     items          sbWidth         scrollMargin
     textBackground  textFont       vscrollMode

     See the "scrolledlistbox"  widget  class  manual  entry  for
     details     on     the     above     associated     options.
     childsitepos    itemsCommand   itemsLabel      itemsLabelPos
     itemsOn         margin         selectionCommandselectionLabel
     selectionLabelPos              selectionOn

     See the "selectionbox" widget manual entry  for  details  on
     the above associated options.

INHERITED OPTIONS

     buttonBoxPadX   buttonBoxPadY  buttonBoxPos    padX
     padY            separator      thickness

     See the "dialogshell" widget  manual entry  for  details  on
     the above inherited options.

     master          modality       title

     See the "shell" widget  manual  entry  for  details  on  the
     above inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           height
     Class:          Height
     Command-Line Switch:           -height

          Specifies the height  of  the  selection  dialog.   The
          value  may  be specified in any of the forms acceptable
          to Tk_GetPixels.  The default is 350 pixels.

     Name:           width
     Class:          Width
     Command-Line Switch:           -width

          Specifies the width of the selection dialog.  The value
          may  be  specified  in  any  of the forms acceptable to
          Tk_GetPixels.  The default is 300 pixels.

DESCRIPTION

     The selectiondialog command creates a selection box  similar
     to the OSF/Motif standard selection dialog composite widget.
     The selectiondialog is derived from the Dialog class and  is
     composed  of  a selectionbox with commands to manipulate the
     dialog buttons.

METHODS

     The selectiondialog command creates a new Tcl command  whose
     name  is pathName.  This command may be used to invoke vari-
     ous operations on the widget.  It has the following  general
     form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.  The following commands are possible for selectiondia-
     log widgets:

ASSOCIATED METHODS

     childsite       clear          get             insert
     selectitem

     See the "selectionbox" widget manual entry  for  details  on
     the above associated methods.

     curselection    delete         index           nearest
     scan            selection      size

     See the "listbox" widget manual entry  for  details  on  the
     above associated methods.

INHERITED METHODS

     add             buttonconfigure                defaulthide
     invoke          show

     See the "buttonbox" widget manual entry for details  on  the
     above inherited methods.

     activate        center         deactivate

     See the "shell" widget manual entry for details on the above
     inherited methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the selectiondialog 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  correspond-
          ing  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 selectiondialog command.

COMPONENTS

     Name:           sb
     Class:          Selectionbox

          The sb component is the selection box for the selection
          dialog.
           See the "selectionbox" widget manual entry for details
          on the sb component item.

EXAMPLE

           option add *textBackground GhostWhite

           selectiondialog .sd
           .sd activate

AUTHOR

     Mark L. Ulferts

KEYWORDS

     selectiondialog, selectionbox, dialog,  dialogshell,  shell,
     widget
itcl2.2/html/iwidgets2.2.0/shell.n.html100666 1751 0 15070 6423554641 16464 0ustar kunkeewheel iwidgets2.2.0 User Commands - shell

iwidgets2.2.0 User Commands - shell

NAME

     shell - Create and manipulate a shell widget

SYNOPSIS

     shell pathName ?options?

INHERITANCE

     itk::Toplevel <- shell

STANDARD OPTIONS

     background      cursor         foreground

     See the "options" manual entry for details on  the  standard
     options.

WIDGET-SPECIFIC OPTIONS

     Name:           master
     Class:          Window
     Command-Line Switch:           -master

          Defines the shell as being a transient window with  the
          master  window  given by the master option.  The master
          window should be either another existing toplevel  win-
          dow  or {} for no master.  The default is {} for shells
          and "." for dialogs.

     Name:           modality
     Class:          Modality
     Command-Line Switch:           -modality

          Allows the shell to grab control of the screen  in  one
          of three different ways:  application, system, or none.
          Application modal prevents any other  toplevel  windows
          within the application which are direct children of '.'
          from gaining focus.  System modal locks the screen  and
          prevents  all  windows from gaining focus regardless of
          application.  A modality of none performs no  grabs  at
          all.  The default is none.

     Name:           padX
     Class:          Pad
     Command-Line Switch:           -padx

          Specifies a padding distance for the childsite  in  the
          X-direction   in   any   of  the  forms  acceptable  to
          Tk_GetPixels.  The default is 10.

     Name:           padY
     Class:          Pad
     Command-Line Switch:           -pady
          Specifies a padding distance for the childsite  in  the
          Y-direction   in   any   of  the  forms  acceptable  to
          Tk_GetPixels.  The default is 10.

     Name:           title
     Class:          Title
     Command-Line Switch:           -title

          String to be displayed in the title window decoration.

DESCRIPTION

     The shell command creates a  shell  which  is  a  top  level
     widget which supports modal operation.

METHODS

     The shell command create a new Tcl  command  whose  name  is
     pathName.  This command may be used to invoke various opera-
     tions on the widget.  It has the following general form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.   The  following commands are possible for shell widg-
     ets:

WIDGET-SPECIFIC METHODS

     pathName activate
          Display the shell and wait based on the modality.   For
          application  and  system  modal  activations, perform a
          grab operation, and wait for the  result.   The  result
          may  be  returned  via  an  argument  to the deactivate
          method.

     pathName center ?widget?
          Centers the shell with respect to another widget.   The
          widget argument is optional.  If provided, it should be
          the path of another widget with  to  center  upon.   If
          absent,  then  the shell will be centered on the screen
          as a whole.

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the shell command.

     pathName childsite
          Returns the pathname of the child site widget.

     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  correspond-
          ing  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 shell command.

     pathName deactivate ?arg?
          Deactivate the display of the shell.  The method  takes
          an  optional  argument  to  be  passed  to the activate
          method which returns the value.  The optional  argument
          is only effective for application and system modal dia-
          logs.

COMPONENTS

     Name:           shellchildsite
     Class:          frame

          The shellchildsite component is the user child site for
          the  shell.   See  the  "frame" widget manual entry for
          details on the shellchildsite component item.

EXAMPLE

           shell .sh -modality application -padx 20 -pady 20 -title Shell

           pack [label [.sh childsite].l -text SHELL]

           .sh center
           .sh activate

AUTHOR

     Mark L. Ulferts

     Kris Raney

KEYWORDS

     shell, widget
itcl2.2/html/iwidgets2.2.0/spindate.n.html100666 1751 0 24612 6423554641 17166 0ustar kunkeewheel iwidgets2.2.0 User Commands - spindate

iwidgets2.2.0 User Commands - spindate

NAME

     spindate - Create and manipulate time spinner widgets

SYNOPSIS

     spindate pathName ?options?

INHERITANCE

     itk::Widget <- Spindate

STANDARD OPTIONS

     background      cursor         foreground      highlightColor
     highlightThickness             relief          selectBackgroundselectBorderWidth
     selectForeground

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     textBackground  textFont

     See the "entryfield" manual entry for details on  the  above
     associated options.

     labelFont       labelMargin

     See the "labeledwidget" manual  entry  for  details  on  the
     above associated options.

     step

     See the "spinint" manual entry  for  details  on  the  above
     associated options.

     arrowOrient     repeatDelay    repeatInterval

     See the "spinner" manual entry  for  details  on  the  above
     associated options.

WIDGET-SPECIFIC OPTIONS

     Name:           dateMargin
     Class:          Margin
     Command-Line Switch:           -datemargin

          Specifies the margin space between the month, day,  and
          year  spinners  is  any  of  the  forms  accpetable  to
          Tcl_GetPixels.  The default is 1 pixel.


     Name:           dayLabel
     Class:          Text
     Command-Line Switch:           -daylabel

          Specifies the text of the label for  the  day  spinner.
          The default is "Day".

     Name:           dayOn
     Class:          dayOn
     Command-Line Switch:           -dayon

          Specifies whether or not to display the day spinner  in
          any  of  the  forms  acceptable to Tcl_GetBoolean.  The
          default is true.

     Name:           dayWidth
     Class:          Width
     Command-Line Switch:           -daywidth

          Specifies the width of the day spinner in  any  of  the
          forms  acceptable  to  Tcl_GetPixels.  The default is 3
          pixels.

     Name:           labelPos
     Class:          Position
     Command-Line Switch:           -labelpos

          Specifies the position of the label along the sides  of
          the various spinners: n, e, s, or w.  The default is w.

     Name:           monthFormat
     Class:          MonthFormat
     Command-Line Switch:           -monthformat

          Specifies the format of month display,  integer  (1-12)
          or  string  (Jan  -  Dec),  or a user specified list of
          values.

     Name:           monthLabel
     Class:          Text
     Command-Line Switch:           -monthlabel

          Specifies the text of the label for the month  spinner.
          The default is "Month".

     Name:           monthOn
     Class:          monthOn
     Command-Line Switch:           -monthon

          Specifies whether or not to display the  month  spinner
          in  any of the forms acceptable to Tcl_GetBoolean.  The
          default is true.

     Name:           monthWidth
     Class:          Width
     Command-Line Switch:           -monthwidth

          Specifies the width of the month spinner in any of  the
          forms  acceptable  to  Tcl_GetPixels.  The default is 3
          pixels.

     Name:           orient
     Class:          Orient
     Command-Line Switch:           -orient

          Specifies the orientation of the month, day,  and  year
          spinners:  vertical or horizontal.  The default is hor-
          izontal.

     Name:           yearDigits
     Class:          YearDigits
     Command-Line Switch:           -yeardigits

          Specifies the number of digits to be displayed  as  the
          value for the year spinner.  The valid values are 2 and
          4.  The default is 2.

     Name:           yearLabel
     Class:          Text
     Command-Line Switch:           -yearlabel

          Specifies the text of the label for the  year  spinner.
          The default is "Year"

     Name:           yearOn
     Class:          yearOn
     Command-Line Switch:           -yearon

          Specifies whether or not to display the year spinner in
          any  of  the  forms  acceptable to Tcl_GetBoolean.  The
          default is true.

     Name:           yearWidth
     Class:          Width
     Command-Line Switch:           -yearwidth

          Specifies the width of the year spinner in any  of  the
          forms  acceptable  to  Tcl_GetPixels.  The default is 3
          pixels.

DESCRIPTION


     The spindate command creates a set of spinners  for  use  in
     date  value entry.  The set includes an month, day, and year
     spinner widget.

METHODS

     The spindate command creates a new Tcl command whose name is
     pathName.  This command may be used to invoke various opera-
     tions on the widget. It has the following general form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand. The following commands are possible for spindate widg-
     ets:

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the spindate command.

     pathName clear
          Delete the contents of all spinner components.

     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  correspond-
          ing  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 spindate command.

     pathName delete component first ?last?
          Delete one or more characters  of  the  specified  com-
          ponent,  where  component  can  be month, day, or year.
          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.

     pathName get ?component?
          Get returns the  value  for  the  speicifed  component:
          month,  day,  or  year.  Without parameters the command
          returns the all three values as a list.

     pathName insert component index string
          Inserts the characters of string just before the  char-
          acter  indicated  by index in the component, where com-
          ponent can be month, day, or year.

COMPONENTS

     Name:           month
     Class:          Spinner

          The month spinner component is the month spinner of the
          date  spinner.  See the Spinner widget manual entry for
          details on the month component item.

     Name:           day
     Class:          Spinint

          The day spinner component is the  day  spinner  of  the
          date  spinner.  See the SpinInt widget manual entry for
          details on the day component item.

     Name:           year
     Class:          Spinint

          The year spinner component is the year spinner  of  the
          date spinner.  See the SpinInt widget manual entry for-
          details on the year component item.

EXAMPLE

          spindate .sd
          pack .sd -padx 10 -pady 10

AUTHOR

     Sue Yockey

     Mark L. Ulferts

KEYWORDS

     spindate, spinint, spinner, entryfield, entry, widget
itcl2.2/html/iwidgets2.2.0/spinint.n.html100666 1751 0 15374 6423554641 17050 0ustar kunkeewheel iwidgets2.2.0 User Commands - spinint

iwidgets2.2.0 User Commands - spinint

NAME

     spinint - Create and manipulate a integer spinner widget

SYNOPSIS

     spinint pathName ?options?

INHERITANCE

     itk::Widget <- Labeledwidget <- Spinner <- Spinint

STANDARD OPTIONS

     background      borderWidth    cursor          exportSelection
     foreground      highlightColor highlightThicknessinsertBackground
     insertBorderWidth              insertOffTime   insertOnTimeinsertWidth
     justify         relief         selectBackgroundselectBorderWidth
     selectForeground               textVariable

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     show            state

     See the "entry" manual entry for details on  the  associated
     options.

INHERITED OPTIONS

     command         childSitePos   fixed           focusCommand
     invalid         textBackground textFont        validate
     width

     See the "entryfield" widget manual entry for details on  the
     above inherited options.

     labelBitmap     labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable

     See the "labeledwidget" widget manual entry for  details  on
     the above inherited options.

     arroworient     decrement      increment       repeatDelay
     repeatInterval

     See the "spinner" widget manual entry  for  details  on  the
     above inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           range
     Class:          Range
     Command-Line Switch:           -range
          Specifies a two element list  of  minimum  and  maximum
          integer values.  The default is no range, {{} {}}.

     Name:           step
     Class:          Step
     Command-Line Switch:           -step

          Specifies the increment/decrement value.   The  default
          is 1.

     Name:           wrap
     Class:          Wrap
     Command-Line Switch:           -wrap

          Specifies whether to wrap the spinner value upon reach-
          ing  the  minimum  or maximum value in any of the forms
          acceptable to Tcl_GetBoolean.  The default is true.

DESCRIPTION

     The spinint command creates a spinint widget.   The  spinint
     allows "spinning" of integer values within a specified range
     with wrap support.  The spinner arrows may be drawn horizon-
     tally or vertically.

METHODS

     The spinint command creates a new Tcl command whose name  is
     pathName.  This command may be used to invoke various opera-
     tions on the widget.  It has the following general form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.  The following commands are possible for spinint widg-
     ets:

ASSOCIATED METHODS

     delete          get            icursor         index
     insert          peek           scan            selection
     xview

     See the "entry" manual entry for details on  the  associated
     methods.

INHERITED METHODS

     childsite       clear


     See the "entryfield" manual entry for details on the associ-
     ated methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the spinint 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  correspond-
          ing  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 spinint command.

     pathName down
          Decrement the spinner value by the value given  in  the
          step option.

     pathName up
          Increment the spinner value by the value given  in  the
          step option.

COMPONENTS

          See the "Spinner" widget manual entry  for  details  on
          the integer spinner component items.

EXAMPLE

           option add *textBackground white

           spinint .si -labeltext "Temperature" -labelpos w \
              -fixed yes -width 5 -range {32 212}

           pack .si -pady 10

AUTHOR

     Sue Yockey

KEYWORDS

     spinint, widget
itcl2.2/html/iwidgets2.2.0/spinner.n.html100666 1751 0 20441 6423554641 17031 0ustar kunkeewheel iwidgets2.2.0 User Commands - spinner

iwidgets2.2.0 User Commands - spinner

NAME

     spinner - Create and manipulate a spinner widget

SYNOPSIS

     spinner pathName ?options?

INHERITANCE

     itk::Widget <- Labeledwidget <- Spinner

STANDARD OPTIONS

     background      borderWidth    cursor          exportSelection
     foreground      highlightColor highlightThicknessinsertBackground
     insertBorderWidth              insertOffTime   insertOnTimeinsertWidth
     justify         relief         selectBackgroundselectBorderWidth
     selectForeground               textVariable

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     show            state

     See the "entry" manual entry for details on  the  associated
     options.

INHERITED OPTIONS

     childSitePos    command        fixed           focusCommand
     invalid         textBackground textFont        validate
     width

     See the "entryfield" widget manual entry for details on  the
     above inherited options.

     labelBitmap     labelFont      labelImage      labelMargin
     labelPos        labelText      labelVariable

     See the "labeledwidget" widget manual entry for  details  on
     the above inherited options.

WIDGET-SPECIFIC OPTIONS

     Name:           arrowOrient
     Class:          Orient
     Command-Line Switch:           -arroworient

          Specifies placement of  arrow  buttons:  horizontal  or
          vertical.  The default is vertical.

     Name:           decrement
     Class:          Command
     Command-Line Switch:           -decrement
          Tcl command to be executed when down arrow is pressed.

     Name:           increment
     Class:          Command
     Command-Line Switch:           -increment

          Tcl command to be executed when up arrow is pressed.

     Name:           repeatDelay
     Class:          RepeatDelay
     Command-Line Switch:           -repeatdelay

          Specifies the initial delay in milliseconds before  the
          spinner  repeat  action  on  the arrow buttons engages.
          The default is 300 milliseconds.

     Name:           repeatInterval
     Class:          RepeatInterval
     Command-Line Switch:           -repeatinterval

          Specifies the  repeat  delay  in  milliseconds  between
          selections of the arrow buttons.  A repeatinterval of 0
          disables  button  repeat.   The  default  is  100  mil-
          liseconds.

DESCRIPTION

     The spinner command creates a spinner widget.   The  spinner
     is  comprised  of  an entryfield plus up and down arrow but-
     tons. Arrows may be drawn horizontally or vertically.

METHODS

     The spinner command creates a new Tcl command whose name  is
     pathName.  This command may be used to invoke various opera-
     tions on the widget.  It has the following general form:

          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand.  The following commands are possible for spinner widg-
     ets:

ASSOCIATED METHODS

     delete          get            icursor         index
     insert          scan           selection       xview

     See the "entry" manual entry for details on  the  associated
     methods.

INHERITED METHODS

     childsite       clear          peek

     See the "entryfield" manual entry for details on the associ-
     ated methods.

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the spinner 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  correspond-
          ing  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 spinner command.

     pathName down
          Derived classes may overload this method to  specialize
          functionality.

     pathName up
          Derived classes may overload this method to  specialize
          functionality.

COMPONENTS

     Name:           downarrow
     Class:          Canvas

          The downarrow component is the downward pointing button
          of  the  spinner.  See the "canvas" widget manual entry
          for details on the downarrow component item.

     Name:           uparrow
     Class:          Canvas

          The uparrow component is the upward pointing button  of
          the  spinner.  See the "canvas" widget manual entry for
          details on the uparrow component item.

EXAMPLE

           option add *textBackground GhostWhite

           set months {January February March April May June July \
                           August September October November December}

           proc blockInput {char} {
               return 0
           }

           proc spinMonth {step} {
               global months

               set index [expr [lsearch $months [.sm get]] + $step]

               if {$index < 0} {set index 11}
               if {$index > 11} {set index 0}

               .sm delete 0 end
               .sm insert 0 [lindex $months $index]
           }

           spinner .sm -labeltext "Month : " -width 10 -fixed 10 -validate blockInput \
                       -decrement {spinMonth -1} -increment {spinMonth 1}
           .sm insert 0 January

           pack .sm -padx 10 -pady 10

ACKNOWLEDGEMENTS:

     Ken Copeland <ken@hilco.com>

          10/18/95 - Added auto-repeat action  to  spinner  arrow
          buttons.

AUTHOR

     Sue Yockey

KEYWORDS

     spinner, widget
itcl2.2/html/iwidgets2.2.0/spintime.n.html100666 1751 0 24172 6423554641 17210 0ustar kunkeewheel iwidgets2.2.0 User Commands - spintime

iwidgets2.2.0 User Commands - spintime

NAME

     spintime - Create and manipulate time spinner widgets

SYNOPSIS

     spintime pathName ?options?

INHERITANCE

     itk::Widget <- Spintime

STANDARD OPTIONS

     background      cursor         foreground      highlightColor
     highlightThickness             relief          selectBackgroundselectBorderWidth
     selectForeground

     See the "options" manual entry for details on  the  standard
     options.

ASSOCIATED OPTIONS

     textBackground  textFont

     See the "entryfield" manual entry for details on  the  above
     associated options.

     labelFont       labelMargin

     See the "labeledwidget" manual  entry  for  details  on  the
     above associated options.

     step

     See the "spinint" manual entry  for  details  on  the  above
     associated options.

     arrowOrient     repeatDelay    repeatInterval

     See the "spinner" manual entry  for  details  on  the  above
     associated options.

WIDGET-SPECIFIC OPTIONS

     Name:           labelPos
     Class:          Position
     Command-Line Switch:           -labelpos

          Specifies the position of the label along the sides  of
          the various spinners: n, e, s, or w.  The default is w.

     Name:           hourLabel
     Class:          Text
     Command-Line Switch:           -hourlabel

          Specifies the text of the label for the  hour  spinner.
          The default is "Hour".

     Name:           hourOn
     Class:          hourOn
     Command-Line Switch:           -houron

          Specifies whether or not to display the hour spinner in
          any  of  the  forms  acceptable to Tcl_GetBoolean.  The
          default is true.

     Name:           hourWidth
     Class:          Width
     Command-Line Switch:           -hourwidth

          Specifies the width of the hour spinner in any  of  the
          forms  acceptable  to  Tcl_GetPixels.  The default is 3
          pixels.

     Name:           militaryOn
     Class:          militaryOn
     Command-Line Switch:           -militaryon

          Specifies use of a 24 hour clock for  hour  display  in
          any  of  the  forms  acceptable to Tcl_GetBoolean.  The
          default is true.

     Name:           minuteLabel
     Class:          Text
     Command-Line Switch:           -minutelabel

          Specifies the text of the label for the minute spinner.
          The default is "Minute".

     Name:           minuteOn
     Class:          minuteOn
     Command-Line Switch:           -minuteon

          Specifies whether or not to display the minute  spinner
          in  any of the forms acceptable to Tcl_GetBoolean.  The
          default is true.

     Name:           minuteWidth
     Class:          Width
     Command-Line Switch:           -minutewidth

          Specifies the width of the minute spinner in any of the
          forms  acceptable  to  Tcl_GetPixels.  The default is 3
          pixels.

     Name:           orient
     Class:          Orient
     Command-Line Switch:           -orient

          Specifies the orientation  of  the  hour,  minute,  and
          second  spinners:  vertical or horizontal.  The default
          is horizontal.

     Name:           secondLabel
     Class:          Text
     Command-Line Switch:           -secondlabel

          Specifies the text of the label for the second spinner.
          The default is "Second"

     Name:           secondOn
     Class:          secondOn
     Command-Line Switch:           -secondon

          Specifies whether or not to display the second  spinner
          in  any of the forms acceptable to Tcl_GetBoolean.  The
          default is true.

     Name:           secondWidth
     Class:          Width
     Command-Line Switch:           -secondwidth

          Specifies the width of the second spinner in any of the
          forms  acceptable  to  Tcl_GetPixels.  The default is 3
          pixels.

     Name:           timeMargin
     Class:          Margin
     Command-Line Switch:           -timemargin

          Specifies the margin space between  the  hour,  minute,
          and  second  spinners is any of the forms accpetable to
          Tcl_GetPixels.  The default is 1 pixel.

DESCRIPTION

     The spintime command creates a set of spinners  for  use  in
     time  value  entry.   The  set includes an hour, minute, and
     second spinner widget.

METHODS

     The spintime command creates a new Tcl command whose name is
     pathName.  This command may be used to invoke various opera-
     tions on the widget. It has the following general form:
          pathName option ?arg arg ...?

     Option and the args determine the exact behavior of the com-
     mand. The following commands are possible for spintime widg-
     ets:

WIDGET-SPECIFIC METHODS

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the spintime command.

     pathName clear
          Delete the contents of all spinner components.

     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  correspond-
          ing  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 spintime command.

     pathName delete component first ?last?
          Delete one or more characters  of  the  specified  com-
          ponent, where component can be hour, minute, or second.
          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.

     pathName get ?component?
          Get returns the  value  for  the  speicifed  component:
          hour,  minute,  or second.  Without parameters the com-
          mand returns the all three values as a list.

     pathName insert component index string
          Inserts the characters of string just before the  char-
          acter  indicated  by index in the component, where com-
          ponent can be hour, minute, or second.

COMPONENTS

     Name:           hour
     Class:          Spinint
          The hour component is the  hour  spinner  of  the  time
          spinner.   See  the  SpinInt  widget  manual  entry for
          details on the hour component item.

     Name:           minute
     Class:          Spinint

          The minute component is the minute spinner of the  time
          spinner.   See  the  SpinInt  widget  manual  entry for
          details on the minute component item.

     Name:           second
     Class:          Spinint

          The second component is the second spinner of the  time
          spinner.   See  the  SpinInt  widget  manual  entry for
          details on the second component item.

EXAMPLE

          spintime .st
          pack .st -padx 10 -pady 10

AUTHOR

     Sue Yockey

     Mark L. Ulferts

KEYWORDS

     spintime, spinint, spinner, entryfield, entry, widget
itcl2.2/html/iwidgets2.2.0/tabnotebook.n.html100666 1751 0 106543 6423554641 17712 0ustar kunkeewheel iwidgets2.2.0 User Commands - tabnotebook

iwidgets2.2.0 User Commands - tabnotebook

NAME

     tabnotebook - create and manipulate tabnotebook widgets

SYNOPSIS

     tabnotebook pathName? options?

INHERITANCE

     itk::Widget <- tabnotebook

STANDARD OPTIONS

     background      disabledForeground             foregroundscrollCommand
     cursor          font           height          width

     See the "options" manual entry for details on  the  standard
     options.

WIDGET-SPECIFIC OPTIONS

     Name:           angle
     Class:          Angle
     Command-Line Switch:           -angle

          Specifes the angle of slope from the inner edge to  the
          outer  edge  of the tab. An angle of 0 specifies square
          tabs. Valid ranges  are  0  to  45  degrees  inclusive.
          Default is 15 degrees. If tabPos is e or w, this option
          is ignored.

     Name:           auto
     Class:          Auto
     Command-Line Switch:           -auto

          Specifies    whether    to    use     the     automatic
          packing/unpacking algorithm of the notebook. A value of
          true indicates that page frames will  be  unpacked  and
          packed  acoording  to  the  algorithm  described in the
          select command. A value of  false  leaves  the  current
          page  packed  and subsequent selects, next, or previous
          commands do not switch pages automatically.  In  either
          case   the  page's  associated  command  (see  the  add
          command's  description  of  the  command   option)   is
          invoked.  The  value may have any of the forms accepted
          by the Tcl_GetBoolean, such as true, false, 0, 1,  yes,
          or no.

     Name:           backdrop
     Class:          Backdrop
     Command-Line Switch:           -backdrop

          Specifies a background color to use when filling in the
          backdrop area behind the tabs.

     Name:           background
     Class:          Background
     Command-Line Switch:           -background

          Specifies a background color to use  for  displaying  a
          page  and its associated tab. This can be thought of as
          the selected tab background color, since the tab  asso-
          ciated with the selected page is the selected tab.

     Name:           bevelAmount
     Class:          BevelAmount
     Command-Line Switch:           -bevelamount

          Specifes the size of tab corners. A  value  of  0  with
          angle set to 0 results in square tabs. A bevelAmount of
          4, means that the tab will be drawn with angled corners
          that  cut  in  4  pixels  from the edge of the tab. The
          default is 0.

     Name:           borderWidth
     Class:          BorderWidth
     Command-Line Switch:           -borderwidth

          Specifies the width of shadowed border to place  around
          the notebook area of the tabnotebook. The default value
          is 2.

     Name:           disabledForeground
     Class:          DisabledForeground
     Command-Line Switch:           -disabledforeground

          Specifies a foreground color to use  for  displaying  a
          tab's label when its state is disabled.

     Name:           equalTabs
     Class:          EqualTabs
     Command-Line Switch:           -equaltabs

          Specifies whether to force tabs to be  equal  sized  or
          not.  A  value of true means constrain tabs to be equal
          sized. A value of false allows each tab to  size  based
          on  the  text label size. The value may have any of the
          forms accepted by the  Tcl_GetBoolean,  such  as  true,
          false, 0, 1, yes, or no.

          For horizontally positioned tabs (tabpos is either s or
          n),  true  forces all tabs to be equal width (the width
          being equal to the longest label plus any  padX  speci-
          fied). Horizontal tabs are always equal in height.

          For vertically positioned tabs (tabpos is either  w  or
          e), true forces all tabs to be equal height (the height
          being equal to the height of the label with the largest
          font).  Vertically  oriented  tabs  are always equal in
          width.

     Name:           foreground
     Class:          Foreground
     Command-Line Switch:           -foreground

          Specifies a foreground color to use  for  displaying  a
          page  and its associated tab label. This can be thought
          of as the selected tab background color, since the  tab
          associated with the selected page is the selected tab.

     Name:           gap
     Class:          Gap
     Command-Line Switch:           -gap

          Specifies the amount of pixel space  to  place  between
          each tab. Value may be any pixel offset value. In addi-
          tion, a special keyword overlap  can  be  used  as  the
          value to achieve a standard overlap of tabs. This value
          may have any of the forms acceptable to Tk_GetPixels.

     Name:           margin
     Class:          Margin
     Command-Line Switch:           -Bmargin

          Specifies the amount of space to place between the out-
          side  edge  of  the tabnotebook and the outside edge of
          its tabs. If tabPos is s, this is the amount  of  space
          between the bottom edge of the tabnotebook and the bot-
          tom edge of the set of tabs. If tabPos is  n,  this  is
          the  amount  of  space between the top edge of the tab-
          notebook and the top edge of the set of tabs. If tabPos
          is  e,  this  is  the amount of space between the right
          edge of the tabnotebook and the right edge of  the  set
          of  tabs.  If  tabPos is w, this is the amount of space
          between the left edge of the tabnotebook and  the  left
          edge of the set of tabs. This value may have any of the
          forms acceptable to Tk_GetPixels.

     Name:           padX
     Class:          PadX
     Command-Line Switch:           -padx

          Specifies a  non-negative  value  indicating  how  much
          extra  space  to  request for a tab around its label in
          the X-direction. When computing how large a  window  it
          needs,  the  tab  will  add this amount to the width it
          would normally need The tab  will  end  up  with  extra
          internal space to the left and right of its text label.
          This value may have any  of  the  forms  acceptable  to
          Tk_GetPixels.

     Name:           padY
     Class:          PadY
     Command-Line Switch:           -pady

          Specifies a  non-negative  value  indicating  how  much
          extra  space  to  request for a tab around its label in
          the Y-direction. When computing how large a  window  it
          needs,  the  tab  will add this amount to the height it
          would normally need The tab  will  end  up  with  extra
          internal space to the top and bottom of its text label.
          This value may have any  of  the  forms  acceptable  to
          Tk_GetPixels.

     Name:           raiseSelect
     Class:          RaiseSelect
     Command-Line Switch:           -raiseselect

          Specifes whether to slightly  raise  the  selected  tab
          from  the rest of the tabs. The selected tab is drawn 2
          pixels closer to the outside of  the  tabnotebook  than
          the  unselected  tabs.  A  value  of true says to raise
          selected tabs, a value of false turns this feature off.
          The  default  is  false.  The value may have any of the
          forms accepted by the  Tcl_GetBoolean,  such  as  true,
          false, 0, 1, yes, or no.

     Name:           start
     Class:          Start
     Command-Line Switch:           -start

          Specifies the amount of space to place between the left
          or top edge of the tabnotebook and the starting edge of
          its tabs. For horizontally positioned tabs, this is the
          amount  of  space between the left edge of the notebook
          and the left edge of  the  first  tab.  For  vertically
          positioned  tabs,  this  is the amount of space between
          the top of the notebook and the top of the  first  tab.
          This  value may change if the user performs a MButton-2
          scroll on the tabs. This value  may  have  any  of  the
          forms acceptable to Tk_GetPixels.

     Name:           state
     Class:          State
     Command-Line Switch:           -state

          Sets the active state of  the  tabnotebook.  Specifying
          normal  allows  all  pages to be selectable. Specifying
          disabled disables the notebook causing all page tabs to
          be drawn in the disabledForeground color.

     Name:           tabBackground
     Class:          TabBackground
     Command-Line Switch:           -tabbackground

          Specifies a background color to use for displaying  tab
          backgrounds  when  they  are in their unselected state.
          This is the background  associated  with  tabs  on  all
          pages other than the selected page.

     Name:           tabBorders
     Class:          TabBorders
     Command-Line Switch:           -tabborders

          Specifies whether to draw the borders of tabs that  are
          not selected. Specifying true (the default) draws these
          borders, specifying false draws only the border  around
          the  selected  tab. The value may have any of the forms
          accepted by the Tcl_GetBoolean, such as true, false, 0,
          1, yes, or no.

     Name:           tabForeground
     Class:          TabForeground
     Command-Line Switch:           -tabforeground

          Specifies a foreground color to use for displaying  tab
          labels when they are in their unselected state. This is
          the foreground associated with tabs on all pages  other
          than the selected page.

     Name:           tabPos
     Class:          TabPos
     Command-Line Switch:           -tabpos

          Specifies the location of the set of tabs  in  relation
          to  the  notebook area. Must be n, s, e, or w. Defaults
          to s.

DESCRIPTION

     The tabnotebook command creates a new window (given  by  the
     pathName  argument)  and makes it into a tabnotebook widget.
     Additional options, described above may be specified on  the
     command  line or in the option database to configure aspects
     of the tabnotebook such as its colors, font, and  text.  The
     tabnotebook  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 tabnotebook is a widget that  contains  a  set  of  tabbed
     pages.  It  displays  one  page from the set as the selected
     page. A Tab displays the label for the page to which  it  is
     attached and serves as a page selector. When a page's tab is
     selected, the page's contents  are  displayed  in  the  page
     area.  The  selected  tab  has a three-dimensional effect to
     make it appear to float above the other tabs. The  tabs  are
     displayed  as  a group along either the left, top, right, or
     bottom edge. When first created a tabnotebook has no  pages.
     Pages   may  be  added  or  deleted  using  widget  commands
     described below.

     A special option may be provided  to  the  tabnotebook.  The
     -auto option specifies whether the tabnotebook will automat-
     ically handle the unpacking and packing of pages when  pages
     are  selected.  A  value of true signifies that the notebook
     will automatically manage it. This is the default  value.  A
     value  of  false  signifies  the  notebook  will not perform
     automatic switching of pages.

NOTEBOOK PAGES

     A tabnotebook's pages area  contains  a  single  child  site
     frame.  When  a  new  page  is created it is a child of this
     frame. The page's child site frame serves as a geometry con-
     tainer  for  applications  to  pack widgets into. It is this
     frame that is automatically unpacked or packed when the auto
     option  is  true.  This creates the effect of one page being
     visible at a time. When a new page is selected,  the  previ-
     ously  selected  page's  child  site  frame is automatically
     unpacked from the tabnotebook's child  site  frame  and  the
     newly   selected  page's  child  site  is  packed  into  the
     tabnotebook's child site frame.

     However, sometimes it is desirable to handle page changes in
     a  different manner. By specifying the auto option as false,
     child site packing can be disabled and done differently. For
     example,  all  widgets might be packed into the first page's
     child site frame. Then when a  new  page  is  selected,  the
     application can reconfigure the widgets and give the appear-
     ance that the page was flipped.

     In both cases the command option for a page specifies a  Tcl
     Command to execute when the page is selected. In the case of
     auto being true, it is between the unpacking of  the  previ-
     ously  selected  page  and the packing of the newly selected
     page.

     Notebook pages can also be controlled with  scroll  bars  or
     other  widgets that obey the scrollcommand protocol. By giv-
     ing a scrollbar a -command to call the tabnotebook's  select
     method, the tabnotebook can be controlled with a scrollbar.

     The notebook area is  implemented  with  the  notebook  mega
     widget.

TABS

     Tabs appear along the edge of the notebook  area.  Tabs  are
     drawn  to  appear  attached to their associated page. When a
     tab is clicked on, the associated page is selected  and  the
     tab  is  drawn as raised above all other tabs and as a seam-
     less part of its notebook page. Tabs can  be  controlled  in
     their  location  along  the  edges,  the angle tab sides are
     drawn with, gap  between  tabs,  starting  margin  of  tabs,
     internal  padding around text labels in a tab, the font, and
     its label.

     The Tab area is implemented with the tabset mega widget. See
     tabset(1).  Tabs  may  be  oriented  along either the north,
     south, east, or west sides with the tabPos option. North and
     south  tabs  may appear as angled, square, or bevelled. West
     and east tabs may appear as square or bevelled. By  changing
     tab  gaps,  tab  angles,  bevelling,  orientations,  colors,
     fonts, start locations, and margins; tabs may  appear  in  a
     wide  variety  of  styles.  For  example,  it is possible to
     implement Microsoft-style tabs, Borland property tab styles,
     or Borland Delphi style tabs all with the same tabnotebook.

WIDGET-SPECIFIC METHODS

     The tabnotebook 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 com-
     mand.

     Many of the widget commands for a notebook take as one argu-
     ment  an  indicator of which page of the notebook to operate
     on. These indicators are called indexes and may be specified
     in any of the following forms:

     number
          Specifies the page numerically, where 0 corresponds  to
          the first page in the notebook, 1 to the second, and so
          on.

     select
          Specifies the currently selected page's  index.  If  no
          page is currently selected, the value -1 is returned.

     end  Specifes the last page in the tabnotebook's  index.  If
          the notebook is empty this will return -1.

     pattern
          If the index doesn't satisfy any of  the  above  forms,
          then  this  form  is  used.  Pattern is pattern-matched
          against the label of each  page  in  the  notebook,  in
          order from the first to the last page, until a matching
          entry is found. The rules of Tcl_StringMatch are  used.
          The  following  commands  are  possible for tabnotebook
          widgets:

     pathName add ?option value option value ...?
          Add a new page at the end of  the  tabnotebook.  A  new
          child  site  frame  is  created. Returns the child site
          pathName. If additional  arguments  are  present,  they
          specify any of the following options:

          -angle value
               Specifes the angle of slope from the inner edge to
               the outer edge of the tab. An angle of 0 specifies
               square tabs. Valid ranges  are  0  to  45  degrees
               inclusive.  Default  is 15 degrees. If this option
               is specified as an  empty  string  (the  default),
               then  the angle option for the overall tabnotebook
               is used. This is generally only set  at  the  tab-
               notebook  level.  Tabs normally will want to share
               the same angle value.

          -background value
               Specifies a background color to use for displaying
               tabs when they are selected and for displaying the
               current page. If this option is  specified  as  an
               empty  string  (the  default), then the background
               option for the overall tabnotebook is used.

          -bevelamount value
               Specifes the size of tab corners.  A  value  of  0
               with  angle  set  to  0  results in square tabs. A
               bevelAmount of 4, means that the tab will be drawn
               with  angled corners that cut in 4 pixels from the
               edge of the tab. The default is 0.  This  is  gen-
               erally  only  set  at  the tabnotebook level. Tabs
               normally will want to share the same bevelAmount.

          -bitmap value
               If label is a non-empty string, specifies a bitmap
               to  display  in  this page's tab. Bitmap may be of
               any of the forms accepted by Tk_GetPixmap.

          -command value
               Specifies a Tcl command to be executed  when  this
               page  is  selected.  This  allows the programmer a
               hook to reconfigure this  page's  widgets  or  any
               other page's widgets.

               If the tabnotebook has  the  auto  option  set  to
               true, when a page is selected this command will be
               called immediately after the  previously  selected
               page  is unpacked and immediately before this page
               is selected. The index value select is valid  dur-
               ing  this  Tcl command. `index select' will return
               this page's page number.

               If the auto option is set to false, when a page is
               selected  the  unpack and pack calls are bypassed.
               This Tcl command is still called.

          -disabledforeground value
               Specifies a foreground color to use for displaying
               tab  labels  when tabs are in their disable state.
               If this option is specified  as  an  empty  string
               (the  default), then the disabledforeground option
               for the overall tabnotebook is used.

          -font value
               Specifies the font to  use  when  drawing  a  text
               label  on  a page tab. If this option is specified
               as an empty string then the font  option  for  the
               overall tabnotebook is used..

          -foreground value
               Specifies a foreground color to use for displaying
               tab  labels when they are selected. If this option
               is specified as an  empty  string  (the  default),
               then  the  foreground  option for the overall tab-
               notebook is used.

          -label value
               Specifies a string to display  as  an  identifying
               label for a notebook page. This label serves as an
               additional identifier used to reference the  page.
               This  label  may  be  used  for the index value in
               widget commands.

          -tabbackground value
               Specifies a background color to use for displaying
               a  tab  when  it is not elected. If this option is
               specified as an empty string (the  default),  then
               the  tabBackground option for the overall tabnote-
               book is used.

          -tabforeground value
               Specifies a foreground color to use for displaying
               the  tab's  text label when it is not selected. If
               this option is specified as an empty  string  (the
               default),  then  the  tabForeground option for the
               overall tabnotebook is used.

          -padx value
               Specifies a non-negative value indicating how much
               extra  space to request for a tab around its label
               in the X-direction. When  computing  how  large  a
               window  it  needs, the tab will add this amount to
               the width it would normally need The tab will  end
               up with extra internal space to the left and right
               of its text label. This value may have any of  the
               forms  acceptable  to Tk_GetPixels. If this option
               is specified as an  empty  string  (the  default),
               then  the  padX option for the overall tabnotebook
               is used

          -pady value
               Specifies a non-negative value indicating how much
               extra  space to request for a tab around its label
               in the Y-direction. When  computing  how  large  a
               window  it  needs, the tab will add this amount to
               the height it would normally need The tab will end
               up with extra internal space to the top and bottom
               of its text label. This value may have any of  the
               forms  acceptable  to Tk_GetPixels. If this option
               is specified as an  empty  string  (the  default),
               then  the  padY option for the overall tabnotebook
               is used

          -state value
               Specifies one of two states for the  page:  normal
               or  disabled.  In normal state unselected tabs are
               displayed using  the  tabforeground  and  tabback-
               ground  option  from  the tabnotebook or the page.
               Selected tabs and pages are  displayed  using  the
               foreground and background option from the tabnote-
               book or the page. The disabled  state  means  that
               the  page  and  its tab is insensitive: it doesn't
               respond to mouse button presses  or  releases.  In
               this state the entry is displayed according to its
               disabledForeground option for the tabnotebook  and
               the  background/tabbackground option from the page
               or the tabnotebook.

     pathName childSite ?index?
          If passed no arguments, returns a list of pathNames for
          all  the  pages in the tabnotebook. If the tab notebook
          is empty, an empty list is returned

          If index is passed, it returns  the  pathName  for  the
          page's  child  site  frame  specified by index. Widgets
          that are created with this pathName will  be  displayed
          when the associated page is selected. If index is not a
          valid index, an empty string is returned.

     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  correspond-
          ing  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 tabnotebook command.

     pathName delete index1 ?index2?
          Delete all of  the  pages  between  index1  and  index2
          inclusive.  If  index2  is  omitted then it defaults to
          index1. Returns an empty string.

     pathName index index
          Returns the numerical index corresponding to index.

     pathName insert index ?option value option value ...?
          Insert a new page in the tabnotebook  before  the  page
          specified  by index. A new child site frame is created.
          The additional arguments are the same as  for  the  add
          command. Returns the child site pathName.

     pathName next
          Advances the selected page to the next page  (order  is
          determined   by  insertion  order).  If  the  currently
          selected page is the last page  in  the  notebook,  the
          selection  wraps  around to the first page in the note-
          book. It behaves as if the user selected the new page.

          For notebooks with auto set to true the current  page's
          child  site  is unpacked from the notebook's child site
          frame. Then the next page's child site is  packed  into
          the  notebook's child site frame. The Tcl command given
          with the command option will be invoked  between  these
          two operations.

          For notebooks with auto set to false  the  Tcl  command
          given with the command option will be invoked.

     pathName pageconfigure index ?option? ?value option value ...?
          This  command  is  similar  to  the  configure command,
          except that it applies to the options for an individual
          page,  whereas configure applies to the options for the
          tabnotebook 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  page index (see Tk_ConfigureInfo
          for information on the format of this list).

     pathName prev
          Moves the selected page to the previous page (order  is
          determined   by  insertion  order).  If  the  currently
          selected page is the first page in  the  notebook,  the
          selection  wraps  around  to the last page in the note-
          book. It behaves as if the user selected the new page.

          For notebooks with auto set to true the current  page's
          child  site  is unpacked from the notebook's child site
          frame. Then the previous page's child  site  is  packed
          into  the  notebook's child site frame. The Tcl command
          given with the command option will be  invoked  between
          these two operations.

          For notebooks with auto set to false  the  Tcl  command
          given with the command option will be invoked.

     pathName select index
          Selects the page specified by index  as  the  currently
          selected  page.  It behaves as if the user selected the
          new page.

          For notebooks with auto set to true the current  page's
          child  site  is unpacked from the notebook's child site
          frame. Then the index page's child site is packed  into
          the  notebook's child site frame. The Tcl command given
          with the command option will be invoked  between  these
          two operations.

          For notebooks with auto set to false  the  Tcl  command
          given with the command option will be invoked.

     pathName view
          Returns the currently selected page.  This  command  is
          for compatibility with the scrollbar widget.

     pathName view index
          Selects the page specified by index  as  the  currently
          selected  page.  This command is for compatibility with
          the scrollbar widget.

     pathName view moveto fraction
          Uses the fraction value to determine the  corresponding
          page to move to. This command is for compatibility with
          the scrollbar widget.

     pathName view scroll num what
          Uses the num value to determine how many pages to  move
          forward  or backward (num can be negative or positive).
          The what argument is ignored. This command is for  com-
          patibility with the scrollbar widget.

COMPONENTS

     Generally all behavior of the  internal  components,  tabset
     and  notebook  are  controlled via the pageconfigure method.
     The following section documents these two components.

     Name:   tabset
     Class:  Tabset

          This is the tabset component. It  implements  the  tabs
          that are associated with the notebook component.

          See the "Tabset" widget manual entry for details on the
          tabset component item.

     Name:   notebook
     Class:  Notebook

          This is the notebook component. It implements the note-
          book that contains the pages of the tabnotebook.

          See the "Notebook" widget manual entry for  details  on
          the notebook component item.

EXAMPLE

     Following is an example that creates a tabnotebook with  two
     pages.

          # Create the tabnotebook widget and pack it.
            tabnotebook .tn -width 100 -height 100
            pack .tn \
                  -anchor nw \
                  -fill both \
                  -expand yes \
                  -side left \
                  -padx 10 \
                  -pady 10

          # Add two pages to the tabnotebook,
          # labelled "Page One" and "Page Two"
            .tn add -label "Page One"
            .tn add -label "Page Two"

          # Get the child site frames of these two pages.
            set page1CS [.tn childsite 0]
            set page2CS [.tn childsite "Page Two"]

          # Create buttons on each page of the tabnotebook.
            button $page1CS.b -text "Button One"
            pack $page1CS.b
            button $page2CS.b -text "Button Two"
            pack $page2CS.b

          # Select the first page of the tabnotebook.
            .tn select 0

AUTHOR

     Bill W. Scott

KEYWORDS

     tab tabset notebook tabnotebook page
itcl2.2/html/iwidgets2.2.0/tabset.n.html100666 1751 0 63211 6423554641 16637 0ustar kunkeewheel iwidgets2.2.0 User Commands - tabset

iwidgets2.2.0 User Commands - tabset

NAME

     tabset - create and manipulate tabs as as set

SYNOPSIS

     tabset pathName ?options?

INHERITANCE

     itk::Widget <- tabset

STANDARD OPTIONS

     background      font           selectBackgroundcursor
     foreground      selectForeground               disabledForegroundheight
     width

     See the "options" manual entry for details on  the  standard
     options.

WIDGET-SPECIFIC OPTIONS

     Name:           angle
     Class:          Angle
     Command-Line Switch:           -angle

          Specifes the angle of slope from the inner edge to  the
          outer  edge  of the tab. An angle of 0 specifies square
          tabs. Valid ranges  are  0  to  45  degrees  inclusive.
          Default is 15 degrees. If tabPos is e or w, this option
          is ignored.

     Name:           backdrop
     Class:          Backdrop
     Command-Line Switch:           -backdrop

          Specifies a background color to use when filling in the
          area behind the tabs.

     Name:           bevelAmount
     Class:          BevelAmount
     Command-Line Switch:           -bevelamount

          Specifes the size of tab corners. A  value  of  0  with
          angle set to 0 results in square tabs. A bevelAmount of
          4, means that the tab will be drawn with angled corners
          that  cut  in  4  pixels  from the edge of the tab. The
          default is 0.

     Name:           command
     Class:          Command
     Command-Line Switch:           -command
     Specifes the prefix of a Tcl command to invoke to change the view in the
     widget associated with the tabset. When a user selects a tab, a Tcl command
     is invoked. The actual command consists of this option followed by a space
     and a number. The number is the numerical index of the tab that has been
     selected.

     Name:           equalTabs
     Class:          EqualTabs
     Command-Line Switch:           -equaltabs

          Specifies whether to force tabs to be  equal  sized  or
          not.  A  value of true means constrain tabs to be equal
          sized. A value of false allows each tab to  size  based
          on  the  text label size. The value may have any of the
          forms accepted by the  Tcl_GetBoolean,  such  as  true,
          false, 0, 1, yes, or no.

          For horizontally positioned tabs (tabPos is either s or
          n),  true  forces all tabs to be equal width (the width
          being equal to the longest label plus any  padX  speci-
          fied). Horizontal tabs are always equal in height.

          For vertically positioned tabs (tabPos is either  w  or
          e), true forces all tabs to be equal height (the height
          being equal to the height of the label with the largest
          font).  Vertically  oriented  tabs  are always equal in
          width.

     Name:           gap
     Class:          Gap
     Command-Line Switch:           -gap

          Specifies the amount of pixel space  to  place  between
          each tab. Value may be any pixel offset value. In addi-
          tion, a special keyword overlap  can  be  used  as  the
          value to achieve a standard overlap of tabs. This value
          may have any of the forms acceptable to Tk_GetPixels.

     Name:           margin
     Class:          Margin
     Command-Line Switch:           -margin

          Specifies the amount of space to place between the out-
          side  edge  of  the  tabset and the outside edge of its
          tabs. If tabPos is s,  this  is  the  amount  of  space
          between  the  bottom  edge of the tabset and the bottom
          edge of the set of tabs. If tabPos is n,  this  is  the
          amount  of space between the top edge of the tabset and
          the top edge of the set of tabs. If tabPos is  e,  this
          is  the  amount  of space between the right edge of the
          tabset and the right edge of the set of tabs. If tabPos
          is w, this is the amount of space between the left edge
          of the tabset and the left edge of  the  set  of  tabs.
          This  value  may  have  any  of the forms acceptable to
          Tk_GetPixels.

     Name:           padX
     Class:          PadX
     Command-Line Switch:           -padx

          Specifies a  non-negative  value  indicating  how  much
          extra  space  to  request for a tab around its label in
          the X-direction. When computing how large a  window  it
          needs,  the  tab  will  add this amount to the width it
          would normally need The tab  will  end  up  with  extra
          internal space to the left and right of its text label.
          This value may have any  of  the  forms  acceptable  to
          Tk_GetPixels.

     Name:           padY
     Class:          PadY
     Command-Line Switch:           -pady

          Specifies a  non-negative  value  indicating  how  much
          extra  space  to  request for a tab around its label in
          the Y-direction. When computing how large a  window  it
          needs,  the  tab  will add this amount to the height it
          would normally need The tab  will  end  up  with  extra
          internal space to the top and bottom of its text label.
          This value may have any  of  the  forms  acceptable  to
          Tk_GetPixels.

     Name:           raiseSelect
     Class:          RaiseSelect
     Command-Line Switch:           -raiseselect

          Specifes whether to slightly  raise  the  selected  tab
          from  the rest of the tabs. The selected tab is drawn 2
          pixels closer to the outside edge of  the  tabset  than
          the  unselected  tabs.  A  value  of true says to raise
          selected tabs, a value of false  turns  this  off.  The
          default  is  false. The value may have any of the forms
          accepted by the Tcl_GetBoolean, such as true, false, 0,
          1, yes, or no.

     Name:           start
     Class:          Start
     Command-Line Switch:           -start

          Specifies the amount of space to place between the left
          or  top edge of the tabset and the starting edge of its
          tabs. For horizontally positioned  tabs,  this  is  the
          amount of space between the left edge of the tabset and
          the left edge of the first tab.  For  vertically  posi-
          tioned  tabs,  this  is the amount of space between the
          top of the tabset and the top of the  first  tab.  This
          value  may  change  if  the  user  performs a MButton-2
          scroll on the tabs. This value  may  have  any  of  the
          forms acceptable to Tk_GetPixels.

     Name:           state
     Class:          State
     Command-Line Switch:           -state

          Sets the active state of the tabset. Specifying  normal
          allows  all  tabs to be selectable. Specifying disabled
          disables the tabset causing all tabs to be drawn in the
          disabledForeground color.

     Name:           tabBorders
     Class:          TabBorders
     Command-Line Switch:           -tabborders

          Specifies whether to draw the borders of tabs that  are
          not selected. Specifying true (the default) draws these
          borders, specifying false draws only the border  around
          the  selected  tab. The value may have any of the forms
          accepted by the Tcl_GetBoolean, such as true, false, 0,
          1, yes, or no.

     Name:           tabPos
     Class:          TabPos
     Command-Line Switch:           -tabpos

          Specifies the location of the set of tabs  in  relation
          to  another  widget. Must be n, s, e, or w. Defaults to
          s. North tabs open downward, South  tabs  open  upward.
          West  tabs  open  to  the  right, east tabs open to the
          left.

DESCRIPTION

     The tabset command creates a new window (given by the  path-
     Name argument) and makes it into a tabset widget. Additional
     options, described above may be  specified  on  the  command
     line  or  in the option database to configure aspects of the
     tabset such as its colors, font, and text. The  tabset  com-
     mand 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 tabset is a widget that contains a set of Tab buttons.  It
     displays  these tabs in a row or column depending on it tab-
     pos. When a tab is clicked on, it becomes the  only  tab  in
     the tab set that is selected. All other tabs are deselected.
     The Tcl command prefix associated with this tab (through the
     command  tab configure option) is invoked with the tab index
     number appended to its argument list. This allows the tabset
     to control another widget such as a Notebook.

TABS

     Tabs are drawn to appear attached  to  another  widget.  The
     tabset  draws  an edge boundary along one of its edges. This
     edge is known as the attachment edge. This edge location  is
     dependent  on the value of tabPos. For example, if tabPos is
     s, the attachment edge wil be on the top side of the  tabset
     (in  order  to  attach  to  the  bottom or south side of its
     attached widget). The selected tab is draw with a 3d  relief
     to  appear  above  the other tabs. This selected tab "opens"
     toward attachment edge.

     Tabs can be controlled in their location  along  the  edges,
     the  angle  that tab sides are drawn with, gap between tabs,
     starting margin of tabs, internal padding around labels in a
     tab, the font, and its text or bitmap.

WIDGET-SPECIFIC METHODS

     The tabset command creates a new Tcl command whose  name  is
     pathName.  This command may be used to invoke various opera-
     tions on the widget. It has the following general form:

          pathName option ?arg arg ...?

     option and the args determine the exact behavior of the com-
     mand.

     Many of the widget commands for a tabset take as  one  argu-
     ment  an indicator of which tab of the tabset to operate on.
     These indicators are called indexes and may be specified  in
     any of the following forms:

     number
          Specifies the tab numerically, where 0  corresponds  to
          the  first  tab in the tab set, 1 to the second, and so
          on.

     select
          Specifies the currently selected tab's index. If no tab
          is currently selected, the value -1 is returned.

     end  Specifes the last tab in the  tabset's  index.  If  the
          tabset is empty this will return -1.

     pattern
          If the index doesn't satisfy any of  the  above  forms,
          then  this  form  is  used.  Pattern is pattern-matched
          against the label of each tab in the tabset,  in  order
          from  the first to the last tab, until a matching entry
          is found. The rules of Tcl_StringMatch are used.

     The following commands are possible for tabset widgets:

          pathName add ?option value option value ...?
               Add a new tab at the end of  the  tabset.  Returns
               the  child  site pathName. If additional arguments
               are present, they specify  any  of  the  following
               options:

               -angle value
                    Specifes the angle of slope  from  the  inner
                    edge  to  the outer edge of the tab. An angle
                    of 0 specifies square tabs. Valid ranges  are
                    0  to  45  degrees  inclusive.  Default is 15
                    degrees. If this option is  specified  as  an
                    empty  string  (the  default), then the angle
                    option for the overall tabset is used.

               -background value
                    Specifies  a  background  color  to  use  for
                    displaying tabs when they are in their normal
                    state (unselected). If this option is  speci-
                    fied  as  an empty string (the default), then
                    the background option for the overall  tabset
                    is used.

               -bevelamount value
                    Specifes the size of tab corners. A value  of
                    0 with angle set to 0 results in square tabs.
                    A bevelAmount of 4, means that the  tab  will
                    be  drawn  with  angled corners that cut in 4
                    pixels from the edge of the tab. The  default
                    is  0. This is generally only set at the tab-
                    set configuration level. Tabs  normally  will
                    want to share the same bevelAmount.

               -bitmap value
                    If label is a non-empty string,  specifies  a
                    bitmap  to  display in the tab. Bitmap may be
                    of any of the forms accepted by Tk_GetBitmap.

               -disabledforeground value
                    Specifies  a  foreground  color  to  use  for
                    displaying  tab labels when tabs are in their
                    disable state. If this option is specified as
                    an empty string (the default), then the disa-
                    bledforeground option for the overall  tabset
                    is used.

               -font value
                    Specifies the font to use  when  drawing  the
                    label  on  a tab. If this option is specified
                    as an empty string then the font  option  for
                    the overall tabset is used.

               -foreground value
                    Specifies  a  foreground  color  to  use  for
                    displaying  tab labels when tabs are in their
                    normal unselected state. If  this  option  is
                    specified  as  an empty string (the default),
                    then the foreground option  for  the  overall
                    tabset is used.

               -image value
                    If label is a non-empty string, specifies  an
                    image  to display in the tab. Image 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.

               -label value
                    Specifies a text string to be placed  in  the
                    tabs  label. If this value is set, the bitmap
                    option is overridden and this option is  used
                    instead.  This  label serves as an additional
                    identifier used to reference  the  tab.  This
                    label  may  be  used  for  the index value in
                    widget commands.

               -selectbackground value
                    Specifies  a  background  color  to  use  for
                    displaying  the  selected tab. If this option
                    is  specified  as  an   empty   string   (the
                    default),  then  the  selectBackground option
                    for the overall tabset is used.

               -selectforeground value
                    Specifies  a  foreground  color  to  use  for
                    displaying  the  selected tab. If this option
                    is  specified  as  an   empty   string   (the
                    default),  then  the  selectForeground option
                    for the overall tabset is used.

               -padx value
                    Specifies a non-negative value indicating how
                    much  extra space to request for a tab around
                    its label in the X-direction. When  computing
                    how large a window it needs, the tab will add
                    this amount to the width  it  would  normally
                    need  The tab will end up with extra internal
                    space to the  left  and  right  of  its  text
                    label.  This  value may have any of the forms
                    acceptable to Tk_GetPixels. If this option is
                    specified  as  an empty string (the default),
                    then the padX option for the  overall  tabset
                    is used

               -pady value
                    Specifies a non-negative value indicating how
                    much  extra space to request for a tab around
                    its label in the Y-direction. When  computing
                    how large a window it needs, the tab will add
                    this amount to the height it  would  normally
                    need  The tab will end up with extra internal
                    space to the  top  and  bottom  of  its  text
                    label.  This  value may have any of the forms
                    acceptable to Tk_GetPixels. If this option is
                    specified  as  an empty string (the default),
                    then the padY option for the  overall  tabset
                    is used

               -state value
                    Sets the state of the tab. Specifying  normal
                    allows  this tab to be selectable. Specifying
                    disabled disables the this  tab  causing  its
                    tab  label  to  be drawn in the disabledFore-
                    ground color. The tab  will  not  respond  to
                    events until the state is set back to normal.

          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  path-
               Name  (see Tk_ConfigureInfo for information on the
               format of this list). If option is specified  with
               no value, then the command returns a list describ-
               ing the one named option (this list will be ident-
               ical  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 tabset command.

          pathName delete index1 ?index2?
               Delete all of the tabs between index1  and  index2
               inclusive.  If  index2 is omitted then it defaults
               to index1. Returns an empty string.

          pathName index index
               Returns  the  numerical  index  corresponding   to
               index.

          pathName insert index ?option value option value ...?
               Insert a new tab in  the  tabset  before  the  tab
               specified  by  index. The additional arguments are
               the same as for the add command. Returns the tab's
               pathName.

          pathName next
               Advances the selected tab to the next  tab  (order
               is   determined   by   insertion  order).  If  the
               currently selected tab is the last tab in the tab-
               set,  the selection wraps around to the first tab.
               It behaves as if the user selected the next tab.

          pathName tabconfigure index ?option? ?value?
               This command is similar to the configure  command,
               except that it applies to the options for an indi-
               vidual  tab,  whereas  configure  applies  to  the
               options  for  the  tabset  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  com-
               mand  returns  an  empty string. If no options are
               specified, returns a list describing  the  current
               options  for  tab  index (see Tk_ConfigureInfo for
               information on the format of this list).

          pathName prev
               Moves the selected tab to the previous tab  (order
               is   determined   by   insertion  order).  If  the
               currently selected tab is the  first  tab  in  the
               tabset, the selection wraps around to the last tab
               in the tabset. It behaves as if the user  selected
               the previous tab.

          pathName select index
               Selects  the  tab  specified  by  index   as   the
               currently  selected tab. It behaves as if the user
               selected the new tab.

EXAMPLE

     Following is an example that creates a tabset with two  tabs
     and a list box that the tabset controls. In addition select-
     ing an item from the list  also  selects  the  corresponding
     tab.

          # Define a proc that knows how to select an item
          # from a list given an index from the tabset -command callback.
            proc selectItem { item } {
              .l selection clear [.l curselection]
              .l selection set $item
              .l see $item

          }

          # Define a proc that knows how to select a tab
          # given a y pixel coordinate from the list..
            proc selectTab { y } {
              set whichItem [.l nearest $y]
              .ts select $whichItem
          }

          # Create a listbox with two items (one and two)
          # and bind button 1 press to the selectTab procedure.
            listbox .l -selectmode single -exportselection false
            .l insert end one
            .l insert end two
            .l selection set 0
            pack .l
            bind .l <ButtonPress-1> { selectTab %y }

          # Create a tabset, set its -command to call selectItem
          # Add two labels to the tabset (one and two).
            tabset .ts -command selectItem
            .ts add -label 1
            .ts add -label 2
            .ts select 0
            pack .ts -fill x -expand no

AUTHOR

     Bill W. Scott

KEYWORDS

     tab tabset notebook tabnotebook
itcl2.2/html/iwidgets2.2.0/toolbar.n.html100666 1751 0 40214 6423554641 17015 0ustar kunkeewheel iwidgets2.2.0 User Commands - toolbar

iwidgets2.2.0 User Commands - toolbar

NAME

     toolbar - Create and manipulate a tool bar

SYNOPSIS

     toolbar pathName ?options?

STANDARD OPTIONS

     activeBackground               font            insertForegroundselectForeground
     activeForeground               foreground      orientstate
     background      highlightBackground            relieftroughColor
     borderWidth     highlightColor selectBackgroundcursor
     highlightThickness             selectBorderWidthdisabledForegroundinsertBackground
     selectColor

     See the "options" manual entry for details on  the  standard
     options.  For  widgets  added  to the toolbar, these options
     will be propogated if the widget supports  the  option.  For
     example,  all  widgets  that  support  a font option will be
     changed if the the toolbar's font option is configured.

WIDGET-SPECIFIC OPTIONS

     Name:           balloonBackground
     Class:          BalloonBackground
     Command-Line Switch:           -ballooonbackground

          Specifies the background  color  of  the  balloon  help
          displayed at the bottom center of a widget on the tool-
          bar that has a non  empty  string  for  its  balloonStr
          option. The default color is yellow.

     Name:           balloonDelay1
     Class:          BalloonDelay1
     Command-Line Switch:           -balloondelay1

          Specifies the length of time (in milliseconds) to  wait
          before  initially  posting  a balloon help hint window.
          This delay is in effect whenever 1)  the  mouse  leaves
          the  toolbar, or 2) a toolbar item is selected with the
          mouse button.

     Name:           balloonDelay2
     Class:          BalloonDelay2
     Command-Line Switch:           -balloondelay2

          Specifies the length of time (in milliseconds) to  wait
          before  continuing  to  post balloon help hint windows.
          This delay is in effect after the first time a  balloon
          hint window is activated. It remains in effect until 1)
          the mouse leaves the toolbar, or 2) a toolbar  item  is
          selected with the mouse button.

     Name:           balloonFont
     Class:          BalloonFont
     Command-Line Switch:           -balloonfont

          Specifies the font of the balloon help  text  displayed
          at  the  bottom  center of a widget on the toolbar that
          has a non empty string for its balloonStr  option.  The
          default font is 6x10.

     Name:           balloonForeground
     Class:          BalloonForeground
     Command-Line Switch:           -ballooonforeground

          Specifies the foreground  color  of  the  balloon  help
          displayed at the bottom center of a widget on the tool-
          bar that has a non  empty  string  for  its  balloonStr
          option. The default color is black.

     Name:           helpVariable
     Class:          HelpVariable
     Command-Line Switch:           -helpvariable

          Specifies the global variable to  update  whenever  the
          mouse  is  in motion over a toolbar widget. This global
          variable is updated  with  the  current  value  of  the
          active widget's helpStr. Other widgets can "watch" this
          variable with the trace command, or as is the case with
          entry or label widgets, they can set their textVariable
          to the same global variable. This allows for  a  simple
          implementation of a help status bar. Whenever the mouse
          leaves a menu entry, the helpVariable  is  set  to  the
          empty string {}.

     Name:           orient
     Class:          Orient
     Command-Line Switch:           -orient

          Specifies the  orientation  of  the  toolbar.  Must  be
          either horizontal or vertical.

DESCRIPTION

     The toolbar command creates a new window (given by the path-
     Name  argument)  and  makes  it into a toolbar widget. Addi-
     tional options, described above may be specified on the com-
     mand  line or in the option database to configure aspects of
     the toolbar such as its colors, font, and  orientation.  The
     toolbar  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 toolbar is a widget that displays a collection of  widgets
     arranged either in a row or a column (depending on the value
     of the -orient option). This collection of widgets  is  usu-
     ally  for  user  convenience to give access to a set of com-
     mands or settings. Any widget may be placed  on  a  toolbar.
     However,  command or value-oriented widgets (such as button,
     radiobutton, etc.) are usually the most useful kind of widg-
     ets to appear on a toolbar.

     In addition, the toolbar adds two new options to all widgets
     that  are  added to it. These are the helpStr and balloonStr
     options. See the  discussion  for  the  widget  command  add
     below.

WIDGET-SPECIFIC METHODS

     The toolbar command creates a new Tcl command whose name  is
     pathName.  This command may be used to invoke various opera-
     tions on the widget. It has the following general form:

          pathName option ?arg arg ...?

     Option and args determine the exact behavior of the command.

     Many of the widget commands for a toolbar take as one  argu-
     ment  an  indicator  of  which widget item of the toolbar to
     operate on. The indicator is called  an  index  and  may  be
     specified in any of the following forms:

     number
          Specifies the widget numerically, where  0  corresponds
          to  the  first widget in the notebook, 1 to the second,
          and so on. (For horizontal,  0  is  the  leftmost;  for
          vertical, 0 is the topmost).

     end  Specifes the last widget in the toolbar's index. If the
          toolbar is empty this will return -1.

     last Same as end.

     pattern
          If the index doesn't satisfy any of  the  above  forms,
          then  this  form  is  used.  Pattern is pattern-matched
          against the widgetName of each widget in  the  toolbar,
          in  order  from  the  first to the last widget, until a
          matching entry is found. An exact match must occur.

     The following commands are possible for toolbar widgets:

     pathName add widgetCommand widgetName ?option value?
          Adds a widget with the command widgetCommand whose name
          is  widgetName  to  the  toolbar.  If  widgetCommand is
          radiobutton or checkbutton,  its  packing  is  slightly
          padded  to  match  the  geometry  of button widgets. In
          addition, the indicatorOn option is  false  by  default
          and  the  selectColor is that of the toolbar background
          by default. This  allows  Radiobutton  and  Checkbutton
          widgets  to  be  added as icons by simply setting their
          bitmap or image options. If  additional  arguments  are
          present, they are the set of available options that the
          widget type of widgetCommand supports. In addition they
          may also be one of the following options:

          -helpstr value
               Specifes the help string  to  associate  with  the
               widget.  When the mouse moves over the widget, the
               variable  denoted  by  helpVariable  is   set   to
               helpStr.  Another widget can bind to the helpVari-
               able and thus track status help.

          -balloonstr value
               Specifes the string to display in a balloon window
               for this widget. A balloon window is a small popup
               window centered at the bottom of the widget.  Usu-
               ally  the balloonStr value is the name of the item
               on the toolbar. It is sometimes known  as  a  hint
               window.

               When the mouse moves into an item on the  toolbar,
               a  timer  is  set based on the value of balloonDe-
               lay1. If the mouse stays inside the item for  bal-
               loonDelay1,   the   balloon  window  will  pop  up
               displaying the balloonStr value. Once the  balloon
               window  is posted, a new timer based on balloonDe-
               lay2 is set. This is typically a shorter timer. If
               the  mouse is moved to another item, the window is
               unposted and a new window will be posted over  the
               item if the shorter delay time is satisfied.

               While the balloon window is posted, it can also be
               unposted if the item is selected. In this case the
               timer is  reset  to  balloonDelay1.  Whenever  the
               mouse  leaves the toolbar, the timer is also reset
               to balloonDelay1.

               This window posting/unposting model  is  the  same
               model used in the Windows95 environment.

     pathName cget option
          Returns the current value of the  configuration  option
          given by option.

     pathName configure ?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  correspond-
          ing  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.

     pathName delete index ?index2?
          This command deletes all items between index and index2
          inclusive.  If  index2  is  omitted then it defaults to
          index. Returns an empty string.

     pathName index index
          Returns the widget's  numerical  index  for  the  entry
          corresponding  to  index.  If index is not found, -1 is
          returned.

value?

     pathName  insert  beforeIndex  widgetCommand  widgetName  ?option

     Insert a new item named widgetName with the
          command widgetCommand  before  the  item  specified  by
          beforeIndex.  If widgetCommand is radiobutton or check-
          button, its packing is slightly  padded  to  match  the
          geometry  of  button  widgets. In addition, the indica-
          torOn option is false by default and the selectColor is
          that  of the toolbar background by default. This allows
          Radiobutton and Checkbutton  widgets  to  be  added  as
          icons  by simply setting their bitmap or image options.
          The set of available options is the same  as  specified
          in the ad command.

     pathName itemcget index option
          Returns the current value of the  configuration  option
          given  by  option  for  index.  The  item type of index
          determines the valid available options.

     pathName itemconfigure index ?option value?
          Query or modify the configuration options of the widget
          of  the  toolbar  specified  by  index. If no option is
          specified, returns a list describing all of the  avail-
          able options for index (see Tk_ConfigureInfo for infor-
          mation on the format of this list). If option is speci-
          fied  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. The item type of  index  determines  the  valid
          available  options. The set of available options is the
          same as specified in the ad command.

EXAMPLE

           toolbar .tb -helpvariable statusVar

           .tb add button item1 \
              -helpstr "Save It" -bitmap @./icons/Tool_32_box.xbm \
              -balloonstr "Save" -command {puts 1}
           .tb add button item2 \
              -helpstr "Save It" -bitmap @./icons/Tool_32_brush.xbm \
              -balloonstr "Save" -command {puts 1}
           .tb add button item3 \
              -helpstr "Save It" -bitmap @./icons/Tool_32_cut.xbm \
              -balloonstr "Save" -command {puts 1}
           .tb add button item4 \
              -helpstr "Save It" -bitmap @./icons/Tool_32_draw.xbm \
              -balloonstr "Save" -command {puts 1}
           .tb add button item5 \
              -bitmap @./icons/Tool_32_erase.xbm -helpstr "Play It" \
              -command {puts 2}
           .tb add frame filler \
              -borderwidth 1 -width 10 -height 10
           .tb add radiobutton item6 \
              -bitmap @./icons/Tool_32_oval.xbm -command {puts 4} \
              -variable result -value OPEN -helpstr "Radio Button # 1" \
              -balloonstr "Radio"
           .tb add radiobutton item7 \
              -bitmap @./icons/Tool_32_line.xbm -command {puts 5} \
              -variable result -value CLOSED
           .tb add checkbutton item8 \
              -bitmap @./icons/Tool_32_text.xbm -command {puts 6} \
              -variable checkit -onvalue yes -offvalue no
           .tb add checkbutton check2 \
              -bitmap @./icons/Tool_32_points.xbm -command {puts 7} \
               -variable checkit2 -onvalue yes -offvalue no

           pack .tb -side top -anchor nw

AUTHOR

     Bill Scott

KEYWORDS

     toolbar, button, radiobutton, checkbutton, iwidgets, widget
itcl2.2/html/tcl7.6/ 40755 1751 0 0 6423554655 12732 5ustar kunkeewheelitcl2.2/html/tcl7.6/CVS/ 40755 1751 0 0 6423570013 13347 5ustar kunkeewheelitcl2.2/html/tcl7.6/CVS/Root100644 1751 0 26 6423554642 14262 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/html/tcl7.6/CVS/Repository100644 1751 0 11 6423674264 15513 0ustar kunkeewheel/usr/cvs itcl2.2/html/tcl7.6/CVS/Entries100644 1751 0 16727 6423570013 15035 0ustar kunkeewheel/@scope.n.html/1.1.1.1/Thu Oct 23 04:59:14 1997// /AddErrInfo.3.html/1.1.1.1/Thu Oct 23 04:59:14 1997// /Alloc.3.html/1.1.1.1/Thu Oct 23 04:59:14 1997// /AllowExc.3.html/1.1.1.1/Thu Oct 23 04:59:14 1997// /AppInit.3.html/1.1.1.1/Thu Oct 23 04:59:14 1997// /AssocData.3.html/1.1.1.1/Thu Oct 23 04:59:14 1997// /Async.3.html/1.1.1.1/Thu Oct 23 04:59:14 1997// /BackgdErr.3.html/1.1.1.1/Thu Oct 23 04:59:14 1997// /Backslash.3.html/1.1.1.1/Thu Oct 23 04:59:14 1997// /CallDel.3.html/1.1.1.1/Thu Oct 23 04:59:14 1997// /CmdCmplt.3.html/1.1.1.1/Thu Oct 23 04:59:14 1997// /Concat.3.html/1.1.1.1/Thu Oct 23 04:59:14 1997// /CrtChannel.3.html/1.1.1.1/Thu Oct 23 04:59:15 1997// /CrtChnlHdlr.3.html/1.1.1.1/Thu Oct 23 04:59:15 1997// /CrtCloseHdlr.3.html/1.1.1.1/Thu Oct 23 04:59:15 1997// /CrtCommand.3.html/1.1.1.1/Thu Oct 23 04:59:15 1997// /CrtFileHdlr.3.html/1.1.1.1/Thu Oct 23 04:59:15 1997// /CrtInterp.3.html/1.1.1.1/Thu Oct 23 04:59:15 1997// /CrtMathFnc.3.html/1.1.1.1/Thu Oct 23 04:59:15 1997// /CrtModalTmt.3.html/1.1.1.1/Thu Oct 23 04:59:15 1997// /CrtSlave.3.html/1.1.1.1/Thu Oct 23 04:59:15 1997// /CrtTimerHdlr.3.html/1.1.1.1/Thu Oct 23 04:59:15 1997// /CrtTrace.3.html/1.1.1.1/Thu Oct 23 04:59:15 1997// /DString.3.html/1.1.1.1/Thu Oct 23 04:59:15 1997// /DetachPids.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /DoOneEvent.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /DoWhenIdle.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /Eval.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /Exit.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /ExprLong.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /FindExec.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /GetFile.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /GetInt.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /GetOpnFl.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /GetStdChan.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /Hash.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /Interp.3.html/1.1.1.1/Thu Oct 23 04:59:16 1997// /LinkVar.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /Notifier.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /OpenFileChnl.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /OpenTcp.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /PkgRequire.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /Preserve.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /PrintDbl.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /RecordEval.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /RegExp.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /SetErrno.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /SetRecLmt.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /SetResult.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /SetVar.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /Sleep.3.html/1.1.1.1/Thu Oct 23 04:59:17 1997// /SplitList.3.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /SplitPath.3.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /StaticPkg.3.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /StrMatch.3.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /Tcl.n.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /Tcl_Main.3.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /TraceVar.3.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /Translate.3.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /UpVar.3.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /after.n.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /append.n.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /array.n.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /bgerror.n.html/1.1.1.1/Thu Oct 23 04:59:18 1997// /break.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /case.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /catch.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /cd.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /clock.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /close.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /code.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /concat.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /continue.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /delete.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /ensemble.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /eof.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /error.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /eval.n.html/1.1.1.1/Thu Oct 23 04:59:19 1997// /exec.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /exit.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /expr.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /fblocked.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /fconfigure.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /file.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /fileevent.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /filename.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /flush.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /for.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /foreach.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /format.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /gets.n.html/1.1.1.1/Thu Oct 23 04:59:20 1997// /glob.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /global.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /history.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /if.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /import.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /incr.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /info.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /interp.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /join.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /lappend.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /library.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /lindex.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /linsert.n.html/1.1.1.1/Thu Oct 23 04:59:21 1997// /list.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /llength.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /load.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /lrange.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /lreplace.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /lsearch.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /lsort.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /namespace.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /open.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /package.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /pid.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /pkgMkIndex.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /private.n.html/1.1.1.1/Thu Oct 23 04:59:22 1997// /proc.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /protected.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /public.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /puts.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /pwd.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /read.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /regexp.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /regsub.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /rename.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /return.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /scan.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /scope.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /seek.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /set.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /socket.n.html/1.1.1.1/Thu Oct 23 04:59:23 1997// /source.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /split.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /string.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /subst.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /switch.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /tcl7.6API.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /tcl7.6UserCmds.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /tclvars.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /tell.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /time.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /trace.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /unknown.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /unset.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /update.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /uplevel.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /upvar.n.html/1.1.1.1/Thu Oct 23 04:59:24 1997// /variable.n.html/1.1.1.1/Thu Oct 23 04:59:25 1997// /vwait.n.html/1.1.1.1/Thu Oct 23 04:59:25 1997// /while.n.html/1.1.1.1/Thu Oct 23 04:59:25 1997// itcl2.2/html/tcl7.6/@scope.n.html100666 1751 0 5746 6423554642 15376 0ustar kunkeewheel tcl7.6 User Commands - @scope

tcl7.6 User Commands - @scope

NAME

     @scope - prefix for scoped values

SYNOPSIS

     @scope namespace varName
     @scope namespace command ?arg arg ...?

DESCRIPTION

     Any command or variable name starting with @scope is treated
     as  a  scoped  value.  The associated namespace is activated
     before the command is executed or the variable is accessed.

     With namespaces, commands and variables are no longer simple
     strings;  they are names with an associated context.  Scoped
     values capture the namespace context of  a  command/variable
     in  a  form  that  can  be passed around at the Tcl language
     level.  They are usually created by wrapping code  fragments
     with  the  code  command,  and variable names with the scope
     command.  They are rarely generated by hand.

     Any variable name  starting  with  @scope  is  automatically
     recognized  as a global variable in the specified namespace.
     Access is allowed from any namespace, even if  the  variable
     is  protected or private.  Scoped variables can be used any-
     where that an ordinary variable  name  is  recognized.   For
     example, the following statements are allowed:

         namespace foo {
             variable mode "1"
         }
         set {@scope ::foo mode} 3
         puts "value = ${@scope ::foo mode}"


     Any command name starting with @scope is automatically  exe-
     cuted  in  the specified namespace.  If additional arg argu-
     ments are included, the command string is built by appending
     the  extra  arg  as  list elements to the end of the command
     string.  This preserves  the  integrity  of  the  arguments,
     while  keeping  the  code fragment command as a flat string.
     For example:

         @scope ::foo {.b configure} -text "Hello World!"

     is equivalent to:

         namespace ::foo {.b configure -text {Hello World!}}

     Since scoped commands are executed in their  namespace  con-
     text,  they  provide  a  way to access protected and private
     commands from any other namespace.  In  effect,  the  @scope
     command  is  a lot like the namespace command, but it allows
     extra arguments to be appended to the command.

KEYWORDS

     @scope, code, scope, namespace, private, protected, public
itcl2.2/html/tcl7.6/AddErrInfo.3.html100666 1751 0 16335 6423554642 16063 0ustar kunkeewheel tcl7.6 C API - AddErrInfo

tcl7.6 C API - AddErrInfo

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 vari-
                                       able.

     char         *element   (in)      String to  record  as  one
                                       element of errorCode vari-
                                       able.  Last element  argu-
                                       ment must be NULL.

DESCRIPTION

     These procedures are used to manipulate two Tcl global vari-
     ables  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 sys-
     tem call) and additional elements in  errorCode  hold  addi-
     tional  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  plat-
     forms (e.g. Windows) where Tcl is linked into an application
     as a shared library, or when the error occurs in  a  dynami-
     cally   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
itcl2.2/html/tcl7.6/Alloc.3.html100666 1751 0 3663 6423554642 15120 0ustar kunkeewheel tcl7.6 C API - Alloc

tcl7.6 C API - 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
itcl2.2/html/tcl7.6/AllowExc.3.html100666 1751 0 3137 6423554642 15600 0ustar kunkeewheel tcl7.6 C API - AllowExc

tcl7.6 C API - AllowExc

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 con-
     verts this into a TCL_ERROR return with an appropriate  mes-
     sage.

     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
itcl2.2/html/tcl7.6/AppInit.3.html100666 1751 0 6516 6423554642 15432 0ustar kunkeewheel tcl7.6 C API - AppInit

tcl7.6 C API - AppInit

NAME

     Tcl_AppInit - perform application-specific initialization

SYNOPSIS

     #include <tcl.h>

     int
     Tcl_AppInit(interp)

ARGUMENTS

     Tcl_Interp   *interp   (in)      Interpreter for the  appli-
                                      cation.

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  per-
          forms 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  tem-
     plate  for Tcl_AppInit that you can modify for your applica-
     tion.

KEYWORDS

     application, argument, command, initialization, interpreter
itcl2.2/html/tcl7.6/AssocData.3.html100666 1751 0 14177 6423554642 15752 0ustar kunkeewheel tcl7.6 C API - AssocData

tcl7.6 C API - AssocData

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 asso-
                                                    ciation  with
                                                    which      to
                                                    store data or
                                                    from which to
                                                    delete     or
                                                    retrieve
                                                    data.   Typi-
                                                    cally     the
                                                    module prefix
                                                    for  a  pack-
                                                    age.

     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 pro-
                                                    cedure    for
                                                    association.
                                                    Ignored    if
                                                    NULL.

     ClientData             clientData    (in)      Arbitrary
                                                    one-word
                                                    value associ-
                                                    ated with the
                                                    given key  in
                                                    this   inter-
                                                    preter.  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 associ-
     ation.

     Storage management is facilitated by storing with each asso-
     ciation 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  argu-
     ments 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
itcl2.2/html/tcl7.6/Async.3.html100666 1751 0 20431 6423554642 15153 0ustar kunkeewheel tcl7.6 C API - Async

tcl7.6 C API - Async

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   asyn-
                                               chronous     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 pro-
     gress 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 com-
     pletion code returned by that command.  The command's result
     will be present in interp->result.  When proc returns, what-
     ever  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  inter-
     preter is active.  This can happen, for example, if an asyn-
     chronous 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 argu-
     ments to Tcl_AsyncInvoke have the same meaning as for  proc:
     they  identify  the active interpreter, if any, and the com-
     pletion 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, repeat-
     ing  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 asynchro-
     nous  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 argu-
     ment.

KEYWORDS

     asynchronous event, handler, signal
itcl2.2/html/tcl7.6/BackgdErr.3.html100666 1751 0 5321 6423554642 15703 0ustar kunkeewheel tcl7.6 C API - BackgdErr

tcl7.6 C API - BackgdErr

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
itcl2.2/html/tcl7.6/Backslash.3.html100666 1751 0 3167 6423554642 15760 0ustar kunkeewheel tcl7.6 C API - Backslash

tcl7.6 C API - 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  com-
     mands.   It parses a backslash sequence and returns the sin-
     gle 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
itcl2.2/html/tcl7.6/CallDel.3.html100666 1751 0 6113 6423554642 15357 0ustar kunkeewheel tcl7.6 C API - CallDel

tcl7.6 C API - CallDel

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 per-
     form 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
itcl2.2/html/tcl7.6/CmdCmplt.3.html100666 1751 0 2156 6423554642 15565 0ustar kunkeewheel tcl7.6 C API - CmdCmplt

tcl7.6 C API - CmdCmplt

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 complete-
                             ness.

DESCRIPTION

     Tcl_CommandComplete takes a Tcl command string  as  argument
     and determines whether it contains one or more complete com-
     mands (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
itcl2.2/html/tcl7.6/Concat.3.html100666 1751 0 4213 6423554642 15265 0ustar kunkeewheel tcl7.6 C API - Concat

tcl7.6 C API - 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 dif-
     ferently 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
itcl2.2/html/tcl7.6/CrtChannel.3.html100666 1751 0 67246 6423554643 16137 0ustar kunkeewheel tcl7.6 C API - CrtChannel

tcl7.6 C API - CrtChannel

NAME

     Tcl_CreateChannel,               Tcl_GetChannelInstanceData,
     Tcl_GetChannelType,  Tcl_GetChannelName, Tcl_GetChannelFile,
     Tcl_GetChannelMode,                Tcl_GetChannelBufferSize,
     Tcl_SetDefaultTranslation,  Tcl_SetChannelBufferSize  - pro-
     cedures 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 struc-
                                               ture    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 asso-
                                               ciated  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 plat-
     form.  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  func-
     tions   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 com-
     mand  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 chan-
     nel  driver, and Tcl_OpenTcpClient opens a channel that uses
     the TCP network protocol.  These  creation  functions  typi-
     cally 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 opera-
     tions 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 associ-
     ated  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  chan-
     nel  if  direction is TCL_READABLE, or the outFile if direc-
     tion 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 chan-
     nel is open for input and output.

     Tcl_SetDefaultTranslation  sets  the  default  end  of  line
     translation  mode. This mode will be installed as the trans-
     lation 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 chan-
     nel 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 getOp-
     tionProc, 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 imple-
     mented.

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  follow-
     ing 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 block-
     ing 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 func-
     tion should release any storage maintained  by  the  channel
     driver for this channel, and close the input and output dev-
     ices 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 pro-
     vided by the generic layer. If an error occurs, the function
     should set the variable to a POSIX error code  that  identi-
     fies the error that occurred.

     The function should read data from the input device encapsu-
     lated  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 argu-
     ment, 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 inter-
     nal 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 pro-
     vided by the generic layer. If an error occurs, the function
     should set this variable to a POSIX error code that  identi-
     fies the error.

     The function should write the data at buf to the output dev-
     ice  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 sub-
     sequent 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 pro-
     vided  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 instance-
     Data is the same as the  value  given  to  Tcl_CreateChannel
     when  this channel was created. The function should do what-
     ever channel type specific action is required  to  implement
     the new value of the option.

     Some options are handled by the generic code and this  func-
     tion  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  func-
     tion  is  never called to retrieve their value, e.g. -block-
     mode. 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  func-
     tion  called  by  the  generic layer to initialize the event
     notification mechanism to notice events of interest on  this
     channel.  WatchChannelProc should match the following proto-
     type:

          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  mechan-
     isms  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  func-
     tion  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 chan-
     nel. It may invoke Tcl_FileReady if the channel  implementa-
     tion 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 direc-
     tion  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
itcl2.2/html/tcl7.6/CrtChnlHdlr.3.html100666 1751 0 12436 6423554643 16254 0ustar kunkeewheel tcl7.6 C API - CrtChnlHdlr

tcl7.6 C API - CrtChnlHdlr

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    tem-
                                              porarily disable an
                                              existing handler.

     Tcl_FileProc      *proc        (in)      Procedure to invoke
                                              whenever  the chan-
                                              nel  indicated   by
                                              channel  meets  the
                                              conditions   speci-
                                              fied 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. Typi-
     cally, 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  identi-
     fied  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 exam-
     ple, if there are two handlers for TCL_READABLE on the  same
     channel,  the  first handler could consume all of the avail-
     able 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.
itcl2.2/html/tcl7.6/CrtCloseHdlr.3.html100666 1751 0 5026 6423554643 16412 0ustar kunkeewheel tcl7.6 C API - CrtCloseHdlr

tcl7.6 C API - CrtCloseHdlr

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 call-
                                              back.

     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  fol-
     lowing 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
itcl2.2/html/tcl7.6/CrtCommand.3.html100666 1751 0 27247 6423554643 16142 0ustar kunkeewheel tcl7.6 C API - CrtCommand

tcl7.6 C API - CrtCommand

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 com-
                                                     mand.

     Tcl_CmdProc         *proc             (in)      Implementation
                                                     of  new com-
                                                     mand:   proc
                                                     will      be
                                                     called when-
                                                     ever cmdName
                                                     is   invoked
                                                     as   a  com-
                                                     mand.

     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   inter-
                                                     preter;
                                                     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  asso-
     ciates  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  inter-
     preter,  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 pro-
     vides 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 pro-
     cedure,  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  any-
     where  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  inter-
     preter.  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 com-
     mand, an application-specific command, or a Tcl procedure.

     Tcl_GetCommandInfo checks to see whether its  cmdName  argu-
     ment  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  com-
     mand does not exist then Tcl_SetCommandInfo returns 0.  Oth-
     erwise, 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  dele-
     tion  procedure  to  be  given  a  different  value than the
     ClientData for its command procedure.

     Tcl_GetCommandName provides a mechanism  for  tracking  com-
     mands  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
itcl2.2/html/tcl7.6/CrtFileHdlr.3.html100666 1751 0 11650 6423554643 16244 0ustar kunkeewheel tcl7.6 C API - CrtFileHdlr

tcl7.6 C API - CrtFileHdlr

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   tem-
                                           porarily   disable   a
                                           handler.

     Tcl_FileProc   *proc        (in)      Procedure  to   invoke
                                           whenever  the  file or
                                           device  indicated   by
                                           file  meets the condi-
                                           tions   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 excep-
     tional 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  struc-
     ture  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
itcl2.2/html/tcl7.6/CrtInterp.3.html100666 1751 0 17504 6423554643 16020 0ustar kunkeewheel tcl7.6 C API - CrtInterp

tcl7.6 C API - CrtInterp

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 inter-
     preter   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 distin-
     guish between when only the memory the callback is responsi-
     ble 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 inter-
     preter   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 pro-
          tection. Thus, when you write an  extension  consisting
          of  new Tcl commands, no special code is needed to pro-
          tect 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. Other-
          wise, 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)
itcl2.2/html/tcl7.6/CrtMathFnc.3.html100666 1751 0 11541 6423554643 16072 0ustar kunkeewheel tcl7.6 C API - CrtMathFnc

tcl7.6 C API - CrtMathFnc

NAME

     Tcl_CreateMathFunc - Define a new math function for  expres-
     sions

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  func-
                                            tion.

     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 permissi-
                                            ble  types  for  each
                                            argument to function.

     Tcl_MathProc    *proc        (in)      Procedure that imple-
                                            ments 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
itcl2.2/html/tcl7.6/CrtModalTmt.3.html100666 1751 0 7573 6423554643 16265 0ustar kunkeewheel tcl7.6 C API - CrtModalTmt

tcl7.6 C API - CrtModalTmt

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    mil-
                                               liseconds  to wait
                                               before    invoking
                                               proc.

     Tcl_TimerProc    *proc          (in)      Procedure       to
                                               invoke  after mil-
                                               liseconds     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
itcl2.2/html/tcl7.6/CrtSlave.3.html100666 1751 0 31243 6423554643 15625 0ustar kunkeewheel tcl7.6 C API - CrtSlave

tcl7.6 C API - CrtSlave

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 inter-
                                                     preter    to
                                                     create    or
                                                     manipulate.

     int                    isSafe         (in)      Zero   means
                                                     the   inter-
                                                     preter   may
                                                     have all Tcl
                                                     functions.
                                                     Non-zero
                                                     means    the
                                                     new
                                                     interpreter's
                                                     functional-
                                                     ity   should
                                                     be   limited
                                                     to  make  it
                                                     safe.

     Tcl_Interp             *slaveInterp   (in)      Interpreter
                                                     to  use  for
                                                     creating the
                                                     source  com-
                                                     mand for  an
                                                     alias   (see
                                                     below).

     char                   *srcCmd        (in)      Name      of
                                                     source  com-
                                                     mand     for
                                                     alias.

     Tcl_Interp             *targetInterp  (in)      Interpreter
                                                     that    con-
                                                     tains    the
                                                     target  com-
                                                     mand for  an
                                                     alias.

     char                   *targetCmd     (in)      Name of tar-
                                                     get  command
                                                     for alias in
                                                     targetIn-
                                                     terp.

     int                    argc           (in)      Count     of
                                                     additional
                                                     arguments to
                                                     pass  to the
                                                     alias   com-
                                                     mand.

     char                   **argv         (in)      Vector    of
                                                     strings, the
                                                     additional
                                                     arguments to
                                                     pass to  the
                                                     alias   com-
                                                     mand.   This
                                                     storage   is
                                                     owned by the
                                                     caller.

     Tcl_Interp             **targetInterpPtr(in)    Pointer   to
                                                     location  to
                                                     store    the
                                                     address   of
                                                     the   inter-
                                                     preter 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     addi-
                                                     tional argu-
                                                     ments  to be
                                                     passed    to
                                                     the   alias.
                                                     The location
                                                     is        in
                                                     storage
                                                     owned by the
                                                     caller.

     char                   ***argvPtr     (out)     Pointer   to
                                                     location  to
                                                     store a vec-
                                                     tor       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 func-
                                                     tion.

DESCRIPTION

     These procedures are intended for  access  to  the  multiple
     interpreter  facility  from  inside  C programs. They enable
     managing multiple interpreters in a  hierarchical  relation-
     ship,  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  remov-
     ing 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 inter-
     preter. 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 mas-
     ter (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 computa-
     tion 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  speci-
     fied  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 indi-
     cated 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  inter-
     preters, see interp(n).

KEYWORDS

     alias, command, interpreter, master, slave
itcl2.2/html/tcl7.6/CrtTimerHdlr.3.html100666 1751 0 10076 6423554643 16446 0ustar kunkeewheel tcl7.6 C API - CrtTimerHdlr

tcl7.6 C API - CrtTimerHdlr

NAME

     Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler - call a pro-
     cedure at a given time

SYNOPSIS

     #include <tcl.h>

     Tcl_TimerToken
     Tcl_CreateTimerHandler(milliseconds, proc, clientData)

     Tcl_DeleteTimerHandler(token)

ARGUMENTS

     int              milliseconds   (in)      How   many    mil-
                                               liseconds  to wait
                                               before    invoking
                                               proc.

     Tcl_TimerProc    *proc          (in)      Procedure       to
                                               invoke  after mil-
                                               liseconds     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  com-
     mands  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  struc-
     ture  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
itcl2.2/html/tcl7.6/CrtTrace.3.html100666 1751 0 16676 6423554643 15626 0ustar kunkeewheel tcl7.6 C API - CrtTrace

tcl7.6 C API - CrtTrace

NAME

     Tcl_CreateTrace, Tcl_DeleteTrace - arrange for command  exe-
     cution 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 com-
                                                   mands or those
                                                   that       are
                                                   invoked     as
                                                   immediate
                                                   consequences
                                                   of   executing
                                                   top-level com-
                                                   mands    (pro-
                                                   cedure bodies,
                                                   bracketed com-
                                                   mands,   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.  Client-
     Data typically points to an application-specific data struc-
     ture  that describes what to do when proc is invoked.  Level
     gives the nesting level of the command (1 for top-level com-
     mands  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 parame-
     ter 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 substitu-
     tion,  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 com-
     mand procedure associated with a command name, then no trac-
     ing  will  occur  for  that  command.  If a string passed to
     Tcl_Eval contains multiple commands (bracketed, or  on  dif-
     ferent  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
itcl2.2/html/tcl7.6/DString.3.html100666 1751 0 16702 6423554643 15457 0ustar kunkeewheel tcl7.6 C API - DString

tcl7.6 C API - 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 charac-
                                         ter.

     int           newLength   (in)      New length  for  dynamic
                                         string,   not  including
                                         null terminating charac-
                                         ter.

     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  arbi-
     trarily 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  struc-
     ture.

     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 char-
     acter  ``{'',  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
itcl2.2/html/tcl7.6/DetachPids.3.html100666 1751 0 6007 6423554644 16073 0ustar kunkeewheel tcl7.6 C API - DetachPids

tcl7.6 C API - 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 responsibil-
     ity  for  one  or  more processes whose process ids are con-
     tained 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 automati-
     cally 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.  How-
     ever, 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
itcl2.2/html/tcl7.6/DoOneEvent.3.html100666 1751 0 12224 6423554644 16107 0ustar kunkeewheel tcl7.6 C API - DoOneEvent

tcl7.6 C API - 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 res-
     tricts  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  pro-
     cessed.   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
itcl2.2/html/tcl7.6/DoWhenIdle.3.html100666 1751 0 7750 6423554644 16053 0ustar kunkeewheel tcl7.6 C API - DoWhenIdle

tcl7.6 C API - 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  previ-
     ous  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 com-
     mand 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
itcl2.2/html/tcl7.6/Eval.3.html100666 1751 0 13020 6423554644 14763 0ustar kunkeewheel tcl7.6 C API - Eval

tcl7.6 C API - Eval

NAME

     Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval  -  exe-
     cute 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 exe-
     cutes 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  vari-
     ables  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 condi-
     tionals, loops, and procedures are implemented).  If a  code
     other than TCL_OK is returned from a nested Tcl_Eval invoca-
     tion, 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 con-
     verts 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
itcl2.2/html/tcl7.6/Exit.3.html100666 1751 0 6350 6423554644 14775 0ustar kunkeewheel tcl7.6 C API - Exit

tcl7.6 C API - 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 appli-
                                           cation.

     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 pro-
     vides 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  struc-
     ture  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
itcl2.2/html/tcl7.6/ExprLong.3.html100666 1751 0 12555 6423554644 15646 0ustar kunkeewheel tcl7.6 C API - ExprLong

tcl7.6 C API - 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  return-
                                          ing).

     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 initial-
     ized  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 pro-
     cedure 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 con-
     verted 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
itcl2.2/html/tcl7.6/FindExec.3.html100666 1751 0 3460 6423554644 15550 0ustar kunkeewheel tcl7.6 C API - FindExec

tcl7.6 C API - FindExec

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
itcl2.2/html/tcl7.6/GetFile.3.html100666 1751 0 20551 6423554644 15422 0ustar kunkeewheel tcl7.6 C API - GetFile

tcl7.6 C API - 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  associ-
                                                  ated  with  the
                                                  generic    file
                                                  handle.     See
                                                  below   for   a
                                                  list  of  valid
                                                  types.

     Tcl_File           handle          (in)      Generic    file
                                                  handle  associ-
                                                  ated       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 han-
                                                  dle 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  descrip-
                           tor.

     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  par-
     ticular  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 deallo-
     cated  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 func-
     tion 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 asso-
     ciate  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
itcl2.2/html/tcl7.6/GetInt.3.html100666 1751 0 10231 6423554644 15267 0ustar kunkeewheel tcl7.6 C API - GetInt

tcl7.6 C API - 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 con-
                                         verted.

     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  pro-
     cedures  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 *doub-
     lePtr 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 spel-
     lings are also acceptable.

KEYWORDS

     boolean, conversion, double, floating-point, integer
itcl2.2/html/tcl7.6/GetOpnFl.3.html100666 1751 0 6114 6423554644 15540 0ustar kunkeewheel tcl7.6 C API - GetOpnFl

tcl7.6 C API - GetOpnFl

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 chan-
                                         nel,  such  as  stdin or
                                         file4.

     int          write        (in)      Non-zero means the  file
                                         will  be  used for writ-
                                         ing, 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 argu-
     ment  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
itcl2.2/html/tcl7.6/GetStdChan.3.html100666 1751 0 7543 6423554644 16055 0ustar kunkeewheel tcl7.6 C API - GetStdChan

tcl7.6 C API - GetStdChan

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 speci-
                                       fied 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  chan-
     nel  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 chan-
     nel with the newly created channel.  If more than one  stan-
     dard  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
itcl2.2/html/tcl7.6/Hash.3.html100666 1751 0 27421 6423554644 14771 0ustar kunkeewheel tcl7.6 C API - Hash

tcl7.6 C API - 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 pre-
                                             vious    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 key-
                                             Type  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 consist-
     ing  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 hash-
                              ing 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 associ-
     ated  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  unadvis-
     able 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
itcl2.2/html/tcl7.6/Interp.3.html100666 1751 0 15041 6423554644 15342 0ustar kunkeewheel tcl7.6 C API - Interp

tcl7.6 C API - 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.  Inter-
     preter 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 pro-  |
     cedure 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 argu-
     ment 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 com-
     mand 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  ini-
     tialized  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  exe-
     cuted  when  the error occurred.  The line numbers are rela-
     tive 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  con-
     junction  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
itcl2.2/html/tcl7.6/LinkVar.3.html100666 1751 0 14037 6423554645 15454 0ustar kunkeewheel tcl7.6 C API - LinkVar

tcl7.6 C API - 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  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
     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 vari-
     able are invoked.

KEYWORDS

     boolean, integer, link,  read-only,  real,  string,  traces,
     variable
itcl2.2/html/tcl7.6/Notifier.3.html100666 1751 0 60522 6423554645 15665 0ustar kunkeewheel tcl7.6 C API - Notifier

tcl7.6 C API - Notifier

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  speci-
                                                 fied    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 for-
                                                 ever  if  neces-
                                                 sary.

     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 possi-
          ble 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 possi-
          ble 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  sup-
     port  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  addi-
     tional  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  infor-
     mation  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;  oth-
     erwise, 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 dynam-
     ically allocated structure containing the event  (see  below
     for  more  information  on  memory management issues).  Each
     event source can define its own event structure  with  what-
     ever 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  posi-
     tions, 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  syn-
                             thesized 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 can-
     not  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  argu-
     ment.  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 notif-
     ier;   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  pro-
     cedures  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 informa-
     tion  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 for-
     ever,  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
itcl2.2/html/tcl7.6/OpenFileChnl.3.html100666 1751 0 113462 6423554645 16436 0ustar kunkeewheel tcl7.6 C API - OpenFileChnl

tcl7.6 C API - OpenFileChnl

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 chan-
     nels

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 report-
                                                    ing  and   to
                                                    look   up   a
                                                    channel
                                                    registered in
                                                    it.

     char              *fileName          (in)      The name of a
                                                    local or net-
                                                    work 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 permis-
                                                    sions 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  argu-
                                                    ments  to the
                                                    Tcl exec com-
                                                    mand.

     int               flags              (in)      Specifies the
                                                    disposition
                                                    of the  stdio
                                                    handles    in
                                                    pipeline:
                                                    OR-ed  combi-
                                                    nation     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  stan-
                                                    dard 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 redirec-
                                                    tions   cause
                                                    an error.

     ClientData        inOsFile           (in)      Operating
                                                    system
                                                    specific han-
                                                    dle for input
                                                    from a  file.
                                                    For Unix this
                                                    is   a   file
                                                    descriptor,
                                                    for   Windows
                                                    it  is a HAN-
                                                    DLE, etc.

     ClientData        outOsFile          (in)      Operating
                                                    system
                                                    specific han-
                                                    dle  for out-
                                                    put   to    a
                                                    file.

     int               readOrWrite        (in)      OR-ed  combi-
                                                    nation     of
                                                    TCL_READABLE
                                                    and
                                                    TCL_WRITABLE
                                                    to   indicate
                                                    which      of
                                                    inOsFile  and
                                                    outOsFile
                                                    contains    a
                                                    valid value.

     int               *modePtr           (out)     Points at  an
                                                    integer vari-
                                                    able     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  pro-
                                                    cedure   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 initial-
                                                    ized  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 chan-
                                                    nel at  which
                                                    the      next
                                                    input or out-
                                                    put 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 chan-
                                                    nel.    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  fconfig-
                                                    ure 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 initial-
                                                    ized  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 dev-
     ice types.  The channel mechanism is extensible to new chan-
     nel 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 communi-
     cate with these subprocesses.  The flags argument  indicates
     what sort of communication will exist with the command pipe-
     line.

     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 subpro-
     cess can be read from the channel; otherwise it goes to this
     application's  standard output.  If TCL_STDERR is set, stan-
     dard 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 execut-
     ing 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 exe-
     cuting 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 destroy-
     ing 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 out-
     put  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 back-
     ground and the channel will be closed once all of  the  buf-
     fered  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 documen-
     tation 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  indi-
     cated  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 con-
     dition. Use Tcl_Eof and Tcl_InputBlocked to  tell  which  of
     these conditions actually occurred.

     Tcl_Read translates platform-specific end-of-line  represen-
     tations   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 char-
     acters 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 una-
     vailability.

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 every-
     thing up to the NULL.

     The return value of Tcl_Write is a count of how many charac-
     ters 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  immedi-
     ately  if the channel is nonblocking; it starts a background
     flush that will write the buffered data to the channel even-
     tually, 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 seek-
     ing.

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 iden-
     tifies  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 chan-
     nel.   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
itcl2.2/html/tcl7.6/OpenTcp.3.html100666 1751 0 27705 6423554645 15464 0ustar kunkeewheel tcl7.6 C API - OpenTcp

tcl7.6 C API - OpenTcp

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    inter-
                                                    preter 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   connec-
                                                    tion.      If
                                                    NULL,       a
                                                    default
                                                    interface  is
                                                    chosen.

     int               async              (in)      If   nonzero,
                                                    the    client
                                                    socket     is
                                                    connected
                                                    asynchro-
                                                    nously to the
                                                    server.

     ClientData        sock               (in)      Platform-
                                                    specific han-
                                                    dle       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  com-
     pletes successfully or fails. If the channel is in nonblock-
     ing mode, the input or output operation will return  immedi-
     ately and a subsequent call to Tcl_InputBlocked on the chan-
     nel 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 spe-
     cial 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 connec-
     tions 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
itcl2.2/html/tcl7.6/PkgRequire.3.html100666 1751 0 6024 6423554645 16141 0ustar kunkeewheel tcl7.6 C API - PkgRequire

tcl7.6 C API - 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  con-
                                           sisting 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 suc-
     cessfully 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
itcl2.2/html/tcl7.6/Preserve.3.html100666 1751 0 12253 6423554645 15677 0ustar kunkeewheel tcl7.6 C API - Preserve

tcl7.6 C API - Preserve

NAME

     Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree - avoid  free-
     ing 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.   Usu-
                                           ally   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  informa-
     tion 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  pro-
     cedure 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.   Unfor-
     tunately,  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 argu-
     ment 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  client-
     Data  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  inter-
     nal  structure  of  the  objects  being freed;  it keeps the
     reference counts in a separate structure.

KEYWORDS

     free, reference count, storage
itcl2.2/html/tcl7.6/PrintDbl.3.html100666 1751 0 3762 6423554645 15607 0ustar kunkeewheel tcl7.6 C API - PrintDbl

tcl7.6 C API - PrintDbl

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 unde-
     fined then 6 significant digits are printed.

KEYWORDS

     conversion, double-precision, floating-point, string
itcl2.2/html/tcl7.6/RecordEval.3.html100666 1751 0 4653 6423554645 16117 0ustar kunkeewheel tcl7.6 C API - RecordEval

tcl7.6 C API - RecordEval

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
itcl2.2/html/tcl7.6/RegExp.3.html100666 1751 0 16035 6423554645 15300 0ustar kunkeewheel tcl7.6 C API - RegExp

tcl7.6 C API - RegExp

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   expres-
                                      sion.    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  charac-
                                      ter 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  com-
     mand.   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  pro-
     vide  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 charac-
     ters 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
itcl2.2/html/tcl7.6/SetErrno.3.html100666 1751 0 3534 6423554645 15627 0ustar kunkeewheel tcl7.6 C API - SetErrno

tcl7.6 C API - 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
itcl2.2/html/tcl7.6/SetRecLmt.3.html100666 1751 0 4530 6423554645 15725 0ustar kunkeewheel tcl7.6 C API - SetRecLmt

tcl7.6 C API - SetRecLmt

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 argu-
     ment   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 over-
     flows    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
itcl2.2/html/tcl7.6/SetResult.3.html100666 1751 0 17223 6423554645 16040 0ustar kunkeewheel tcl7.6 C API - SetResult

tcl7.6 C API - 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 exist-
     ing 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  applica-
     tions  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 com-
     mand procedure was just invoked or Tcl_ResetResult was  just
     called),  then  Tcl_AppendResult sets the result to the con-
     catenation 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  ele-
     ment.  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 dynami-
     cally allocated.  It leaves the result in  its  normal  ini-
     tialized  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, inter-
     preter
itcl2.2/html/tcl7.6/SetVar.3.html100666 1751 0 20012 6423554645 15300 0ustar kunkeewheel tcl7.6 C API - SetVar

tcl7.6 C API - 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 vari-
                                        able or an element of  an
                                        array  variable.   If the
                                        name references  an  ele-
                                        ment 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   opera-
                                        tion. 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 vari-
     able structure.  Tcl keeps a private copy of the  variable's
     value,  so  the  caller may change newValue after these pro-
     cedures 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 combina-
     tion of any of the following bits:

     TCL_GLOBAL_ONLY
          Under normal circumstances the procedures look up vari-
          ables  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  pro-
          cedure 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 vari-
          able 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 sin-
          gle 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  vari-
     able), then NULL is returned.

     Tcl_UnsetVar and Tcl_UnsetVar2 may be used to remove a vari-
     able,  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  speci-
     fied without an index, then the entire array is removed.

SEE ALSO

     Tcl_TraceVar

KEYWORDS

     array, interpreter, scalar, set, unset, variable
itcl2.2/html/tcl7.6/Sleep.3.html100666 1751 0 2553 6423554645 15136 0ustar kunkeewheel tcl7.6 C API - Sleep

tcl7.6 C API - Sleep

NAME

     Tcl_Sleep - delay execution  for  a  given  number  of  mil-
     liseconds

SYNOPSIS

     #include <tcl.h>

     Tcl_Sleep(ms)

ARGUMENTS

     int          ms                 (in)      Number   of   mil-
                                               liseconds       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 applica-
     tion needn't do anything while it waits.  For longer  delays
     where  the application needs to respond to other events dur-
     ing the delay, the procedure  Tcl_CreateTimerHandler  should
     be used instead of Tcl_Sleep.

KEYWORDS

     sleep, time, wait
itcl2.2/html/tcl7.6/SplitList.3.html100666 1751 0 23032 6423554646 16031 0ustar kunkeewheel tcl7.6 C API - SplitList

tcl7.6 C API - 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 mes-  |
                                         sage 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 con-
                                         tain  enough  characters
                                         to     hold    converted
                                         string.

     int          flags        (in)      Information  about  src.
                                         Must  be  value returned
                                         by  previous   call   to
                                         Tcl_ScanElement,  possi-
                                         bly      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 consti-
     tuent elements, returning an array of pointers to  the  ele-
     ments using argcPtr and argvPtr.  While extracting the argu-
     ments, 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  col-
     lection  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 result-
     ing 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
itcl2.2/html/tcl7.6/SplitPath.3.html100666 1751 0 12034 6423554646 16012 0ustar kunkeewheel tcl7.6 C API - SplitPath

tcl7.6 C API - 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  ini-
                                          tialized 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 gen-
     erates 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
itcl2.2/html/tcl7.6/StaticPkg.3.html100666 1751 0 14004 6423554646 15772 0ustar kunkeewheel tcl7.6 C API - StaticPkg

tcl7.6 C API - StaticPkg

NAME

     Tcl_StaticPackage - make a statically linked package  avail-
     able 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
                                                     initializa-
                                                     tion    pro-
                                                     cedure).
                                                     NULL   means
                                                     the  package
                                                     hasn't   yet
                                                     been  incor-
                                                     porated into
                                                     any   inter-
                                                     preter.

     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
                                                     inter-
                                                     preters.

DESCRIPTION

     This procedure may be invoked to announce that a package has
     been  linked  statically with a Tcl application and, option-
     ally, 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 fol-
     lowing 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  initiali-
     zation procedure to be invoked.

KEYWORDS

     initialization procedure, package, static linking
itcl2.2/html/tcl7.6/StrMatch.3.html100666 1751 0 3064 6423554646 15612 0ustar kunkeewheel tcl7.6 C API - StrMatch

tcl7.6 C API - StrMatch

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  spe-
                                               cial    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
itcl2.2/html/tcl7.6/Tcl.n.html100666 1751 0 21441 6423554646 14721 0ustar kunkeewheel tcl7.6 User Commands - Tcl

tcl7.6 User Commands - 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  com-
          mands.  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  com-
          mand  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  brack-
          ets,  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 sub-
          stitution  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  interpre-
          tation.   The  word will consist of exactly the charac-
          ters 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  charac-
          ters  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.  Com-
          mand substitution is not performed on words enclosed in
          braces.

     [7]  If a word contains a dollar-sign (``$'') then Tcl  per-
          forms  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  under-
                         score.

          $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  substi-
                         tutions, 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  fol-
          lowing  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  pro-
          cessing.   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 new-
                line.  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  charac-
          ters  that  follow it, up through the next newline, are
          treated as a comment and ignored.  The comment  charac-
          ter only has significance when it appears at the begin-
          ning 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  verba-
          tim.   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 sub-
          stitutions  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.
itcl2.2/html/tcl7.6/Tcl_Main.3.html100666 1751 0 6264 6423554646 15560 0ustar kunkeewheel tcl7.6 C API - Tcl_Main

tcl7.6 C API - 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   ele-
                                                ments in argv.

     char              *argv[]        (in)      Array of  strings
                                                containing
                                                command-line
                                                arguments.

     Tcl_AppInitProc   *appInitProc   (in)      Address   of   an
                                                application-
                                                specific initial-
                                                ization      pro-
                                                cedure.       The
                                                value   for  this
                                                argument is  usu-
                                                ally Tcl_AppInit.

DESCRIPTION

     Tcl_Main acts as the main program for most Tcl-based  appli-
     cations.   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  applica-
     tion.

     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 initializa-
     tion, 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
itcl2.2/html/tcl7.6/TraceVar.3.html100666 1751 0 51724 6423554646 15622 0ustar kunkeewheel tcl7.6 C API - TraceVar

tcl7.6 C API - TraceVar

NAME

     Tcl_TraceVar,         Tcl_TraceVar2,         Tcl_UntraceVar,
     Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 - moni-
     tor 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  vari-
                                                   able.      May
                                                   refer   to   a
                                                   scalar   vari-
                                                   able,  to   an
                                                   array variable
                                                   with no index,
                                                   or to an array
                                                   variable  with
                                                   a
                                                   parenthesized
                                                   index.  If the
                                                   name    refer-
                                                   ences  an ele-
                                                   ment   of   an
                                                   array, then it
                                                   must   be   in
                                                   writable
                                                   memory:    Tcl
                                                   will make tem-
                                                   porary
                                                   modifications
                                                   to  it   while
                                                   looking up the
                                                   name.

     int                flags            (in)      OR-ed combina-
                                                   tion   of  the
                                                   values
                                                   TCL_TRACE_READS,
                                                   TCL_TRACE_WRITES,
                                                   and
                                                   TCL_TRACE_UNSETS,
                                                   and
                                                   TCL_GLOBAL_ONLY.
                                                   Not  all flags
                                                   are  used   by
                                                   all       pro-
                                                   cedures.   See
                                                   below for more
                                                   information.

     Tcl_VarTraceProc   *proc            (in)      Procedure   to
                                                   invoke   when-
                                                   ever  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 vari-
                                                   able  (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   vari-
                                                   ables  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  infor-
                                                   mation   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 set-
     ting 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  vari-
          ables  are automatically unset) or when the interpreter
          is deleted (all variables are automatically unset).

     Whenever one of the specified operations occurs on the vari-
     able,  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  combi-
     nation 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  struc-
     tures  (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  vari-
     able 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 partic-
     ular  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  pro-
     cedures,  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  pro-
     cedures).   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 con-
     taining 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  pro-
     cedures  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  dam-
     age 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 inter-
     preter, 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  pro-
     cedures  from  misusing  the  interpreter during traces with
     TCL_INTERP_DESTROYED set.

KEYWORDS

     clientData, trace, variable
itcl2.2/html/tcl7.6/Translate.3.html100666 1751 0 6470 6423554646 16026 0ustar kunkeewheel tcl7.6 C API - Translate

tcl7.6 C API - Translate

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 con-
     verts network names into native form and does tilde  substi-
     tution.

     If Tcl_TranslateFileName has to  do  tilde  substitution  or
     translate  the name then it uses the dynamic string at *buf-
     ferPtr  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  informa-
     tion 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
itcl2.2/html/tcl7.6/UpVar.3.html100666 1751 0 16101 6423554646 15136 0ustar kunkeewheel tcl7.6 C API - UpVar

tcl7.6 C API - 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  report-
                                                   ing.

     char               *frameName       (in)      Identifies the
                                                   stack    frame
                                                   containing
                                                   source   vari-
                                                   able.      May
                                                   have   any  of
                                                   the      forms
                                                   accepted    by
                                                   the upvar com-
                                                   mand,  such as
                                                   #0 or 1.

     char               *sourceName      (in)      Name of source
                                                   variable,   in
                                                   the      frame
                                                   given       by
                                                   frameName.
                                                   May refer to a
                                                   scalar   vari-
                                                   able  or to an
                                                   array variable
                                                   with         a
                                                   parenthesized
                                                   index.

     char               *destName        (in)      Name of desti-
                                                   nation   vari-
                                                   able, which is
                                                   to  be  linked
                                                   to      source
                                                   variable    so
                                                   that    refer-
                                                   ences to dest-
                                                   Name 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   vari-
                                                   able;   other-
                                                   wise  it  is a
                                                   local  to  the
                                                   current   pro-
                                                   cedure     (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   vari-
                                                   ables,      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  desti-
     nation  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
itcl2.2/html/tcl7.6/after.n.html100666 1751 0 13236 6423554646 15303 0ustar kunkeewheel tcl7.6 User Commands - after

tcl7.6 User Commands - 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 mil-
          liseconds 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 com-
          mand.  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 iden-
          tifier 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 exist-
          ing  handler;  id  must have been the return value from
          some previous call to after and it must not have  trig-
          gered  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
itcl2.2/html/tcl7.6/append.n.html100666 1751 0 2154 6423554646 15426 0ustar kunkeewheel tcl7.6 User Commands - append

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/array.n.html100666 1751 0 14370 6423554646 15320 0ustar kunkeewheel tcl7.6 User Commands - array

tcl7.6 User Commands - array

NAME

     array - Manipulate array variables

SYNOPSIS

     array option arrayName ?arg arg ...?

DESCRIPTION

     This command performs one of several operations on the vari-
     able  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 invoca-
          tion 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 vari-
          able.

     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  ele-
          ments  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)  ele-
          ments  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 invoca-
          tions 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  nextele-
          ment  and array donesearch commands; it allows multiple
          searches to be underway  simultaneously  for  the  same
          array.

KEYWORDS

     array, element names, search
itcl2.2/html/tcl7.6/bgerror.n.html100666 1751 0 6315 6423554646 15624 0ustar kunkeewheel tcl7.6 User Commands - bgerror

tcl7.6 User Commands - 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 bger-
     ror 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 applica-
     tion.  For example, if an error  occurs  while  executing  a
     command specified with the after command, then it is a back-
     ground 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 pro-
     cedure 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
itcl2.2/html/tcl7.6/break.n.html100666 1751 0 2155 6423554647 15245 0ustar kunkeewheel tcl7.6 User Commands - break

tcl7.6 User Commands - break

NAME

     break - Abort looping command

SYNOPSIS

     break

DESCRIPTION

     This command is typically invoked inside the body of a loop-
     ing  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  com-
     mand,  Tk  event bindings, and the outermost scripts of pro-
     cedure bodies.

KEYWORDS

     abort, break, loop
itcl2.2/html/tcl7.6/case.n.html100666 1751 0 6204 6423554647 15073 0ustar kunkeewheel tcl7.6 User Commands - case

tcl7.6 User Commands - 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  con-
     tain 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  argu-
     ments.   The  first uses a separate argument for each of the
     patterns and commands; this form is convenient if  substitu-
     tions  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
itcl2.2/html/tcl7.6/catch.n.html100666 1751 0 3263 6423554647 15244 0ustar kunkeewheel tcl7.6 User Commands - catch

tcl7.6 User Commands - catch

NAME

     catch - Evaluate script and trap exceptional returns

SYNOPSIS

     catch script ?varName?

DESCRIPTION

     The catch command may be used to prevent errors from  abort-
     ing 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 exe-
     cuting 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 gen-
     erated by break and continue as well as errors.

KEYWORDS

     catch, error
itcl2.2/html/tcl7.6/cd.n.html100666 1751 0 1350 6423554647 14543 0ustar kunkeewheel tcl7.6 User Commands - cd

tcl7.6 User Commands - 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 vari-
     able) if dirName is not given.  Returns an empty string.

KEYWORDS

     working directory
itcl2.2/html/tcl7.6/clock.n.html100666 1751 0 20647 6423554647 15302 0ustar kunkeewheel tcl7.6 User Commands - clock

tcl7.6 User Commands - 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  rela-
          tive 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:

          %%   Insert a %.

          %a   Abbreviated weekday name (Mon, Tue, etc.).

          %A   Full weekday name (Monday, Tuesday, etc.).

          %b   Abbreviated month name (Jan, Feb, etc.).

          %B   Full month name.

          %c   Locale specific date and time.

          %d   Day of month (01 - 31).

          %H   Hour in 24-hour format (00 - 23).

          %I   Hour in 12-hour format (00 - 12).

          %j   Day of year (001 - 366).

          %m   Month number (01 - 12).

          %M   Minute (00 - 59).

          %p   AM/PM indicator.

          %S   Seconds (00 - 59).

          %U   Week of year (01 - 52), Sunday is the first day of
               the week.

          %w   Weekday number (Sunday = 0).

          %W   Week of year (01 - 52), Monday is the first day of
               the week.

          %x   Locale specific date format.

          %X   Locale specific time format.

          %y   Year without century (00 - 99).

          %Y   Year with century (e.g. 1990)

          %Z   Time zone name.

          In addition, the following  field  descriptors  may  be
          supported on some systems (e.g. Unix but not Windows):

          %D   Date as %m/%d/%y.

          %e   Day of month (1 - 31), no leading zeros.

          %h   Abbreviated month name.

          %n   Insert a newline.

          %r   Time as %I:%M:%S %p.

          %R   Time as %H:%M.

          %t   Insert a tab.

          %T   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 speci-
          fied, 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 speci-
               fied 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  follow-
          ing  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  speci-
          fied,  and  no absolute or relative time is given, mid-
          night 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
itcl2.2/html/tcl7.6/close.n.html100666 1751 0 4551 6423554647 15270 0ustar kunkeewheel tcl7.6 User Commands - close

tcl7.6 User Commands - 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 dis-
     carded, the underlying file or device is closed,  and  chan-
     nelId 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 descrip-  |
     tion 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
itcl2.2/html/tcl7.6/code.n.html100666 1751 0 7732 6423554647 15101 0ustar kunkeewheel tcl7.6 User Commands - code

tcl7.6 User Commands - code

NAME

     code - capture the namespace context for a code fragment

SYNOPSIS

     code ?-namespace name? command ?arg arg ...?

DESCRIPTION

     Creates a scoped value for the  specified  command  and  its
     associated  arg  arguments.   A  scoped value is a list with
     three elements:  the "@scope" keyword, a namespace  context,
     and a value string.  For example, the command

         namespace foo {
             code puts "Hello World!"
         }

     produces the scoped value:

         @scope ::foo {puts {Hello World!}}

     Note that the code command captures  the  current  namespace
     context.   If  the  -namespace  flag  is specified, then the
     current context is ignored, and the name string is  used  as
     the namespace context.

     Extensions like Tk execute ordinary code  fragments  in  the
     global  namespace.   A scoped value captures a code fragment
     together with its namespace context in a way that allows  it
     to  be  executed properly later.  It is needed, for example,
     to wrap up code fragments when a Tk widget is used within  a
     namespace:

         namespace foo {
             private proc report {mesg} {
                 puts "click: $mesg"
             }

             button .b1 -text "Push Me"         -command [code report "Hello World!"]
             pack .b1
         }

     The code fragment associated  with  button  .b1  only  makes
     sense  in  the context of namespace "foo".  Furthermore, the
     "report" procedure is private,  and  can  only  be  accessed
     within  that  namespace.  The code command wraps up the code
     fragment in a way that allows it  to  be  executed  properly
     when the button is pressed.

     Also, note that the code command preserves the integrity  of
     arguments  on  the  command  line.   This makes it a natural
     replacement for the list command, which  is  often  used  to
     format Tcl code fragments.  In other words, instead of using
     the list command like this:

         after 1000 [list puts "Hello $name!"]

     use the code command like this:

         after 1000 [code puts "Hello $name!"]

     This not only formats the command correctly, but  also  cap-
     tures its namespace context.

     Scoped commands can be invoked like ordinary code fragments,
     with  or without the eval command.  For example, the follow-
     ing statements work properly:

         set cmd {@scope ::foo .b1}
         $cmd configure -background red

         set opts {-bg blue -fg white}
         eval $cmd configure $opts

     Note that  scoped  commands  by-pass  the  usual  protection
     mechanisms; the command:

         @scope ::foo {report {Hello World!}}

     can be used  to  access  the  "foo::report"  proc  from  any
     namespace context, even though it is private.

KEYWORDS

     @scope, scope, namespace, private, protected, public
itcl2.2/html/tcl7.6/concat.n.html100666 1751 0 2463 6423554647 15432 0ustar kunkeewheel tcl7.6 User Commands - concat

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/continue.n.html100666 1751 0 2210 6423554647 15775 0ustar kunkeewheel tcl7.6 User Commands - continue

tcl7.6 User Commands - continue

NAME

     continue - Skip to the next iteration of a loop

SYNOPSIS

     continue

DESCRIPTION

     This command is typically invoked inside the body of a loop-
     ing  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
itcl2.2/html/tcl7.6/delete.n.html100666 1751 0 2721 6423554647 15422 0ustar kunkeewheel tcl7.6 User Commands - delete

tcl7.6 User Commands - delete

NAME

     delete - delete things in the interpreter

SYNOPSIS

     delete option ?arg arg ...?

DESCRIPTION

     The delete command is used to delete things  in  the  inter-
     preter.  It is implemented as an ensemble, so extensions can
     add their own options and extend the behavior of  this  com-
     mand.   By  default, the delete command handles the destruc-
     tion of namespaces.

     The option argument determines what action is carried out by
     the  command.   The legal options (which may be abbreviated)
     are:

     delete namespace name ?name...?
          Deletes one  or  more  namespaces  called  name.   This
          deletes  all  commands  and variables in the namespace,
          and deletes all  child  namespaces  as  well.   When  a
          namespace  is deleted, it is automatically removed from
          the import lists of all other namespaces.

KEYWORDS

     namespace, proc, variable, ensemble
itcl2.2/html/tcl7.6/ensemble.n.html100666 1751 0 11640 6423554647 15772 0ustar kunkeewheel tcl7.6 User Commands - ensemble

tcl7.6 User Commands - ensemble

NAME

     ensemble - create or modify a composite command

SYNOPSIS

     ensemble name {
         option optName args body
         option optName args body
         ...
         ensemble optName {
             option subOptName args body
             option subOptName args body
         }
     }

DESCRIPTION

     The ensemble command is used to create or modify a composite
     command.   Many  Tcl  commands, like the usual info command,
     are composite commands with option  parts.   These  commands
     are  usually  implemented  by  tediously checking the option
     strings and handling the appropriate case.  New options can-
     not be added without modifying the underlying C code.

     With  the  ensemble  facility,  composite  commands  can  be
     created and extended in an automatic way.  The ensemble com-
     mand finds an existing ensemble name and adds options to it,
     or  creates  an  ensemble  name  and  installs a Tcl command
     called name to access it.  Within the ensemble definition, a
     series of option statements define the allowed options.  The
     syntax of the option statement is identical to the usual Tcl
     proc  command.   Ensemble definitions can also be nested, so
     options themselves can have sub-option parts.

     The ensemble facility not only automates the construction of
     composite commands, it automates the error handling as well.
     For example, the usual Tcl info command is  now  implemented
     as  an  ensemble.   When the info command is invoked without
     any arguments, the following error message is generated:

         wrong # args: should be one of...
           info args procname
           info body procname
           info cmdcount
           info commands ?pattern?
           info complete command
           info context
           info default procname arg varname
           info exists varName
           info globals ?pattern?
           info level ?number?
           info library
           info locals ?pattern?
           info namespace option ?arg arg ...?
           info patchlevel
           info procs ?pattern?
           info protection ?-command? ?-variable? name
           info script
           info tclversion
           info vars ?pattern?
           info which ?-command? ?-variable? ?-namespace? name

     When new options are integrated  into  the  ensemble,  their
     usage  information  will be included in the error message as
     well.

     When the ensemble name command is invoked, the  first  argu-
     ment  on  the  command  line  is matched against the list of
     available options.   The  ensemble  facility  also  supports
     option  abbreviations,  so that "info comm" works as well as
     "info commands".   The  minimum  number  of  characters  for
     unique  abbreviations  is  automatically  determined  as new
     options are added to the ensemble.

     If an option is ambiguous or  not  recognized  at  all,  the
     ensemble facility looks for an option named "@error", and if
     it is found, passes control to it.  This option will receive
     all  of  the arguments on the command line starting with the
     offending option name.  It can find another way of resolving
     the  command,  or  generate  its  own error message.  If the
     "@error" option is not found, the ensemble facility automat-
     ically generates an error message with the usage information
     for all known options.

EXAMPLE

     The  delete  command  is  an  ensemble  supporting   various
     "delete"  operations.   By  default,  only namespaces can be
     deleted.  When the [incr Tcl] extension is  added,  "object"
     and "class" options are added to the delete command.  We can
     use this same command to provide a uniform way  of  deleting
     all  kinds  of system resources.  For example, we can add an
     option to delete Tk widgets:

         ensemble delete {
             option widget {name args} {
                 eval destroy $name $args
             }
         }
         button .b -text "Testing"
         delete widget .b

KEYWORDS

     proc, option, info, delete
itcl2.2/html/tcl7.6/eof.n.html100666 1751 0 1333 6423554647 14727 0ustar kunkeewheel tcl7.6 User Commands - eof

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/error.n.html100666 1751 0 5121 6423554647 15306 0ustar kunkeewheel tcl7.6 User Commands - error

tcl7.6 User Commands - error

NAME

     error - Generate an error

SYNOPSIS

     error message ?info? ?code?

DESCRIPTION

     Returns a TCL_ERROR code, which causes  command  interpreta-
     tion 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 con-
     taining the error command will not appear in  errorInfo;  in
     its place will be info.  This feature is most useful in con-
     junction 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
itcl2.2/html/tcl7.6/eval.n.html100666 1751 0 1726 6423554647 15113 0ustar kunkeewheel tcl7.6 User Commands - eval

tcl7.6 User Commands - 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 concaten-
     ates all its arguments in the same  fashion  as  the  concat
     command,  passes  the  concatenated string to the Tcl inter-
     preter recursively, and returns the result of  that  evalua-
     tion (or any error generated by it).

KEYWORDS

     concatenate, evaluate, script
itcl2.2/html/tcl7.6/exec.n.html100666 1751 0 51530 6423554650 15120 0ustar kunkeewheel tcl7.6 User Commands - exec

tcl7.6 User Commands - 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 sub-
     process.

     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 fol-
                  lowing  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 previ-
                    ous 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 pipe-
                    line   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 pipe-
                    line   is   redirected   to  the  file  named
                    fileName,  appending  to   it   rather   than
                    overwriting it.

     >&gt;& 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 previ-
                    ous 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 previ-
                    ous 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 previ-
                    ous 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 termi-
     nations (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.  How-
     ever, 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  stan-  |
          dard  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 execut-  |
          ing 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 appli-  |
          cation 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, cryp-  |
          tic, 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  sub-  |
          directory /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.                                     |


     Win-  |
          dows 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 appli-  |
          cation  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 applica-  |
          tion 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 out-  |
          put 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  synchro-  |
          nously;  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 com-  |
          pletely read up to its end.  This is slightly different  |
          than  under  Windows 95 or NT, where the child applica-  |
          tion consumes from the open file only  as  much  as  it  |
          wants.   Redirecting  to  an  open file is supported as  |
          normal.                                                  |

     Macin-  |
          tosh                                                  |
          |                                                        |
          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
itcl2.2/html/tcl7.6/exit.n.html100666 1751 0 1300 6423554650 15113 0ustar kunkeewheel tcl7.6 User Commands - exit

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/expr.n.html100666 1751 0 36055 6423554650 15157 0ustar kunkeewheel tcl7.6 User Commands - expr

tcl7.6 User Commands - 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  expres-
     sions  in  the  way  that operands are specified.  Also, Tcl
     expressions support non-numeric  operands  and  string  com-
     parisons.

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 speci-
     fied  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 possi-
     ble.  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 per-
     mitted in most installations).  For example, all of the fol-
     lowing 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 expres-
     sion processor was called.  As discussed below, it  is  usu-
     ally  best  to  enclose expressions in braces to prevent the
     command parser from performing  substitutions  on  the  con-
     tents.

     For some examples of simple expressions, suppose  the  vari-
     able  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  com-
                         parison 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 invok-
     ing the expr command.

MATH FUNCTIONS

     Tcl supports the following mathematical functions in expres-
     sions:

          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 func-
     tions 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 con-
          verts arg to floating and returns the converted value.

     int(arg)
          If arg is an integer value, returns arg, otherwise con-
          verts arg to integer by truncation and returns the con-
          verted value.

     round(arg)
          If arg is an integer value, returns arg, otherwise con-
          verts  arg  to integer by rounding and returns the con-
          verted 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  con-
     verting  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  con-
     verted  to  string with 17 digits of precision and then con-
     verted 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
itcl2.2/html/tcl7.6/fblocked.n.html100666 1751 0 2175 6423554650 15726 0ustar kunkeewheel tcl7.6 User Commands - fblocked

tcl7.6 User Commands - 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 char-
     acters 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
itcl2.2/html/tcl7.6/fconfigure.n.html100666 1751 0 24375 6423554650 16332 0ustar kunkeewheel tcl7.6 User Commands - fconfigure

tcl7.6 User Commands - 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  chan-
     nels.   ChannelId identifies the channel for which to set or
     query an option.  If no name or  value  arguments  are  sup-
     plied,  the  command  returns  a list containing alternating
     option names and values for the channel.  If  name  is  sup-
     plied  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 indefin-
          itely.  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 automati-
          cally 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  con-
          venience,  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  exam-
          ple,  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 char-
          acters.  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 representa-
               tion 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  informa-
               tion.

          cr   The end of a line in the underlying file or device
               is represented by a single carriage return charac-
               ter.  As the input translation mode, cr mode  con-
               verts  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 fol-
               lowed 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 typi-
               cally 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
itcl2.2/html/tcl7.6/file.n.html100666 1751 0 35275 6423554650 15123 0ustar kunkeewheel tcl7.6 User Commands - file

tcl7.6 User Commands - 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 speci-
          fied.   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 speci-
          fied, 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  path-
          name  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 speci-
          fied,  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 rela-
          tive 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 includ-
          ing 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  dif-
          ferent  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 tar-
          getDir.  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 com-
          ponent 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  com-
          mands  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
itcl2.2/html/tcl7.6/fileevent.n.html100666 1751 0 13625 6423554650 16160 0ustar kunkeewheel tcl7.6 User Commands - fileevent

tcl7.6 User Commands - 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 pro-
     cess on an event-driven basis, so that the receiver can con-
     tinue 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  chan-
     nel, 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  non-
     blocking 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 inter-
     preter 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.
itcl2.2/html/tcl7.6/filename.n.html100666 1751 0 25552 6423554650 15761 0ustar kunkeewheel tcl7.6 User Commands - filename

tcl7.6 User Commands - 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 plat-
     form.  In addition, on all platforms, Tcl supports  a  Unix-
     like  syntax  intended  to  provide a convenient way of con-
     structing 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: abso-
     lute, 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 rela-
     tive to the root directory on the current volume,  or  rela-
     tive  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 char-
               acter 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 direc-
               tory.  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  direc-
                              tory.

               /etc/passwd    Absolute path  to  the  file  named
                              passwd  in the directory etc in the
                              root directory.

               .              Relative path to the current direc-
                              tory.

               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 direc-
                              tory 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 vari-
     able 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  substitu-
     tion.

     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
itcl2.2/html/tcl7.6/flush.n.html100666 1751 0 2423 6423554650 15272 0ustar kunkeewheel tcl7.6 User Commands - flush

tcl7.6 User Commands - 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 nonblock-
     ing mode, the command may return before all buffered  output
     has been flushed; the remainder will be flushed in the back-
     ground 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
itcl2.2/html/tcl7.6/for.n.html100666 1751 0 3477 6423554650 14751 0ustar kunkeewheel tcl7.6 User Commands - for

tcl7.6 User Commands - 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; pro-
     cessing 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
itcl2.2/html/tcl7.6/foreach.n.html100666 1751 0 6417 6423554650 15567 0ustar kunkeewheel tcl7.6 User Commands - foreach

tcl7.6 User Commands - 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 associ-
     ated with a list of loop variables (e.g., varlist1 and  var-
     list2).   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 vari-
     ables in each iteration, empty values are used for the miss-
     ing 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
itcl2.2/html/tcl7.6/format.n.html100666 1751 0 25410 6423554650 15462 0ustar kunkeewheel tcl7.6 User Commands - format

tcl7.6 User Commands - 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 imple-
     mentation).   FormatString  indicates  how  to  format   the
     result, using % conversion specifiers as in sprintf, and the
     additional arguments, if any, provide values to  be  substi-
     tuted  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 char-
     acter  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 par-
     ticular  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 para-
     graphs 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 suc-
     cessive arguments are used, starting with the argument given
     by  the number.  This follows the XPG3 conventions for posi-
     tional specifiers.  If there are any  positional  specifiers
     in  formatString  then  all  of the specifiers must be posi-
     tional.

     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 guaran-
               tees 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 giv-
     ing  a minimum field width for this conversion.  It is typi-
     cally 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,  respec-
     tively.  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  modif-
     ier, 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 per-
     form.  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 out-
               put.

     e or e    Convert floating-point number to scientific  nota-
               tion  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 correspond-
          ing 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 conver-
          sion.

KEYWORDS

     conversion specifier, format, sprintf, string, substitution
itcl2.2/html/tcl7.6/gets.n.html100666 1751 0 3764 6423554650 15124 0ustar kunkeewheel tcl7.6 User Commands - gets

tcl7.6 User Commands - 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 speci-
     fied  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, nonblock-
     ing, read
itcl2.2/html/tcl7.6/glob.n.html100666 1751 0 6744 6423554651 15107 0ustar kunkeewheel tcl7.6 User Commands - glob

tcl7.6 User Commands - 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 pat-
                    tern even if it starts with a -.

     The pattern arguments may contain any of the following  spe-
     cial 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 char-
               acter 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 com-
     mand 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
itcl2.2/html/tcl7.6/global.n.html100666 1751 0 5112 6423554651 15410 0ustar kunkeewheel tcl7.6 User Commands - global

tcl7.6 User Commands - 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  dura-
     tion  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.

     Global variables are  found  with  respect  to  the  current  |
     namespace  context.   To  access global variables in another  |
     namespace, simply include namespace qualifiers in  the  var-  |
     name arguments.  For example,                                 |

         set x "ignored"                                           |
         set y 1                                                   |

         namespace foo {                                           |
             variable x 0                                          |
             variable y "ignored"                                  |

             proc checkx {} {                                      |
                 global x                                          |
                 return $x                                         |
             }                                                     |
             proc checky {} {                                      |
                 global ::y                                        |
                 return $y                                         |
             }                                                     |
         }                                                         |

     The command "foo::checkx" will return the value of  "foo::x"  |
     which  is  "0".   The  command "foo::checky" will return the  |
     value of "::y" which is "1".

KEYWORDS

     global, procedure, variable
itcl2.2/html/tcl7.6/history.n.html100666 1751 0 22453 6423554651 15700 0ustar kunkeewheel tcl7.6 User Commands - history

tcl7.6 User Commands - 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  charac-
          ters  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 his-
          tory  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 print-
          ing 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 his-
          tory 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.  Other-
          wise selector is treated as a pattern; all words match-
          ing  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:
               Comman_
                 Resul______

               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 Type_
                 Command Recorde________________

          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
itcl2.2/html/tcl7.6/if.n.html100666 1751 0 3706 6423554651 14555 0ustar kunkeewheel tcl7.6 User Commands - if

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/import.n.html100666 1751 0 12323 6423554651 15504 0ustar kunkeewheel tcl7.6 User Commands - import

tcl7.6 User Commands - import

NAME

     import - change the "import" list for a namespace

SYNOPSIS

     import option ?arg arg ...?

DESCRIPTION

     The import command is used to query  or  modify  the  import
     list  for  the current namespace context.  Command, variable
     and  namespace  names  are  sought  first  in  the   current
     namespace  context,  then  in all imported namespaces.  This
     means  that  commands/variables  can  be  referenced  in  an
     imported  namespace  without the usual namespace qualifiers.
     When a namespace is added to the import list, it acts as  if
     it were a part of the namespace that imports it.

     By default, each namespace imports its parent.  This  allows
     commands  and  variables  at the global scope to be accessed
     transparently   in   child   namespaces.     Frequently-used
     libraries  can also be added to the import list, but it is a
     good idea to import namespaces sparingly.  If each namespace
     imported  all  of  the  others,  there  would be very little
     advantage to using namespaces.

     By default, namespaces are  imported  in  a  "public"  mode.
     This  means  that  public commands/variables can be accessed
     transparently, but protected  and  private  elements  remain
     hidden.   Namespaces  can  also be imported in a "protected"
     mode.    This    means    that    public    and    protected
     commands/variables   can   be  accessed  transparently,  but
     private elements remain hidden.  There is no way  to  import
     in  a "private" mode, so private elements always remain hid-
     den from other namespaces.

     The option argument determines what action is carried out by
     the  command.   The legal options (which may be abbreviated)
     are:

     import add name ?name...? ?-where pos...?
          Adds one or  more  namespace  name  references  to  the
          import  list  in  the  current namespace context.  Each
          name reference may be a namespace name, or a list  with
          two elements:  the first element is the namespace name,
          and the second is the import protection  level,  either
          "public" or "protected".

          The -where flag can be used to specify where  the  list
          of name's should be added in the existing import list:
          -after pos ?pos...?
               Namespace name's are inserted after  the  position
               of  namespace  pos  on the list.  If more than one
               pos  namespace  is  specified,  the   name's   are
               inserted  after  the  pos  nearest  the end of the
               list.

          -before pos ?pos...?
               Namespace name's are inserted before the  position
               of  namespace  pos  on the list.  If more than one
               pos  namespace  is  specified,  the   name's   are
               inserted  before  the pos nearest the start of the
               list.

     import all ?name?
          Returns   the   namespace   search   path   used    for
          command/variable  resolution  in  namespace name, or in
          the current namespace context if name is not specified.
          This is the list of namespaces found by starting at the
          target namespace, and  following  its  tree  of  import
          references.   Each element on the return list is itself
          a list containing a namespace name and its import  pro-
          tection level (public or protected).

     import list ?importList?
          Returns the import list in the current  namespace  con-
          text.  Each element on the return list is itself a list
          containing a namespace name and its  import  protection
          level  (public  or  protected).  If a new importList is
          specified, then the import list is set  to  this.   The
          elements of importList can be simple namespace names or
          two-element lists with a namespace name and its  import
          protection level.

     import remove name ?name...?
          Removes one or more namespace name's  from  the  import
          list  in  the  current  namespace  context.   Each name
          reference can be simple namespace name or a two-element
          list  with  a  namespace name and its import protection
          level.

KEYWORDS

     namespace, import, private, protected, public
itcl2.2/html/tcl7.6/incr.n.html100666 1751 0 2010 6423554651 15075 0ustar kunkeewheel tcl7.6 User Commands - incr

tcl7.6 User Commands - 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;  other-
     wise 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
itcl2.2/html/tcl7.6/info.n.html100666 1751 0 33407 6423554651 15133 0ustar kunkeewheel tcl7.6 User Commands - info

tcl7.6 User Commands - info

NAME

     info - Return information about the state of the Tcl  inter-
     preter

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 in the current namespace context,  |
          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 pat-
          tern  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 typi-
          cally 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 context
          Returns  the  fully-qualified  name  for  the   current  |
          namespace  context.   The  global  namespace  ("::") is  |
          represented as a null string, making it easy  to  build  |
          namespace names like "[info context]::foo".

     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 pro-
          cedure.  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  in the  |
          current namespace context.  If  pattern  is  specified,
          only those names matching pattern are returned.  Match-
          ing is determined using the same rules  as  for  string
          match.

     info hostname
          Returns the name of the computer on which this  invoca-
          tion is being executed.

     info level ?number?
          If number is not  specified,  this  command  returns  a
          number  giving  the  stack  level  of the invoking pro-
          cedure, or 0 if the command is  invoked  at  top-level.
          If  number is specified, then the result is a list con-
          sisting of the name and  arguments  for  the  procedure
          call  at level number on the stack.  If number is posi-
          tive 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 pro-
          cedure, -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 namespace option ?arg arg ...?
          A collection  of  queries  regarding  namespaces.   The  |
          option argument should be one of the following:

          info namespace all ?pattern?
               Returns a list of  all  child  namespaces  in  the  |
               current  namespace  context.   This  includes  the  |
               direct children of the current namespace and other  |
               children  that  are  visible  because their parent  |
               namespace was imported.  The direct children  have  |
               simple  names  and  appear  first on the list; the  |
               imported children have fully-qualified  names  and  |
               appear at the end of the list.

          info namespace children ?name?
               Returns a list of  all  child  namespaces  in  the  |
               namespace  name.   If  name is not specified, then  |
               children are reported  in  the  current  namespace  |
               context.  Unlike the "info namespace all" command,  |
               this command reports only  the  children  directly  |
               contained  within  the  namespace,  and it reports  |
               them with fully-qualified names.

          info namespace parent ?name?
               Returns the fully-qualified name of the parent for  |
               namespace  name.   If  name is not specified, then  |
               the parent of the  current  namespace  context  is  |
               reported.

          info namespace qualifiers string
               Returns the leading namespace qualifiers  for  the  |
               specified  string.  Qualifiers are namespace names  |
               separated by the  "::"  string.   For  the  string  |
               "::foo::bar::x",   this   command   would   return  |
               "::foo::bar".

          info namespace tail string
               Returns the simple name at the  end  of  qualified  |
               string.   Qualifiers are namespace names separated  |
               by   the   "::"   string.     For    the    string  |
               "::foo::bar::x", this command would return "x".

     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  in  the  current  |
          namespace context.  If pattern is specified, only those
          names  matching  pattern  are  returned.   Matching  is
          determined using the same rules as for string match.

     info protection ?-command? ?-variable? name
          Returns the current protection level (public, protected  |
          or  private)  for  the  specified name.  The protection  |
          level is set using the public,  protected  and  private  |
          commands  when  a  command or variable is created.  The  |
          protection level indicates whether or not a command  or  |
          variable can be accessed from other namespace contexts.  |
          See  the  documentation  on  namespace  for  the  rules  |
          regarding  command/variable access.  If no flags speci-  |
          fied, or if the -command  flag  is  included,  name  is  |
          treated  as  a  command name.  If the -variable flag is  |
          included, name is treated as a variable name.

     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 exam-
          ple, .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.

     info which ?-command? ?-variable? ?-namespace? name
          Resolves the specified name in  the  current  namespace  |
          context   and  returns  a  fully-qualified  name  which  |
          uniquely  identifies  it.   See  the  documentation  on  |
          namespace  for the rules regarding name resolution.  If  |
          no  flags  specified,  or  if  the  -command  flag   is  |
          included,  name  is  treated as a command name.  If the  |
          -variable flag is included, name is treated as a  vari-  |
          able name.  If the -namespace flag is included, name is  |
          treated as a namespace name.

KEYWORDS

     command, information, interpreter, level,  procedure,  vari-
     able
itcl2.2/html/tcl7.6/interp.n.html100666 1751 0 55012 6423554651 15475 0ustar kunkeewheel tcl7.6 User Commands - interp

tcl7.6 User Commands - 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 mas-
     ter 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 vari-
     ables.  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 inter-
     preter or in another slave interpreter.  The only other con-
     nections  between interpreters are through environment vari-
     ables (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 com-
     mand)  is  no  longer  shared between interpreters. Explicit
     commands are provided to share files and to transfer  refer-
     ences to open files from one interpreter to another.

     The interp command also provides  support  for  safe  inter-
     preters.  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 inter-
     preters or the application's environment. For  example,  all
     IO  channel  creation  commands and subprocess creation com-
     mands are removed from safe interpreters.  See  SAFE  INTER-
     PRETERS  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  contain-
     ing  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 com-
          mand, 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 ele-
          ments 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 inter-
          preter.  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 inter-
          preter identified by the path ``a b''.  The slave  com-
          mand  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  speci-
          fied 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 inter-
          preters  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  des-
          troyed.

     interp slaves ?path?
          Returns a Tcl list of the names of all the slave inter-
          preters  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 inter-
          preter 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 invok-
          ing  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 com-
          mands, 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  other-
          wise.

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  mas-
     ter.   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  inter-
     preter, the usual Tcl substitutions are performed when pars-
     ing 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  ``tar-
     getCmd 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  inter-
     preters,  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 inter-
     preter which check their  arguments  carefully  and  provide
     restricted access to a safe subset of facilities.  For exam-
     ple, file creation might be allowed  in  a  particular  sub-
     directory  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 environ-
     ment variable. For example, the PGP manual recommends  stor-
     ing  the PGP private key protection password in the environ-
     ment 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  imple-
     mented by Nathaniel Borenstein and Marshall Rose.

SEE ALSO

     load(n), package(n) Tcl_CreateSlave(3)

KEYWORDS

     alias, master interpreter, safe  interpreter,  slave  inter-
     preter
itcl2.2/html/tcl7.6/join.n.html100666 1751 0 1615 6423554651 15113 0ustar kunkeewheel tcl7.6 User Commands - join

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/lappend.n.html100666 1751 0 2715 6423554651 15601 0ustar kunkeewheel tcl7.6 User Commands - lappend

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/library.n.html100666 1751 0 22116 6423554651 15637 0ustar kunkeewheel tcl7.6 User Commands - library

tcl7.6 User Commands - 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  applica-
     tions.   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  nor-
     mally  given  by  the value of the $app_library global vari-
     able, where app is the name of the application.   For  exam-
     ple,  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 automati-
     cally.  The code in init.tcl will define  the  unknown  pro-
     cedure  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  con-
          sists  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 informa-
          tion is out of date).  If an error  occurs  while  pro-
          cessing  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 com-
          mand 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
itcl2.2/html/tcl7.6/lindex.n.html100666 1751 0 2276 6423554651 15443 0ustar kunkeewheel tcl7.6 User Commands - lindex

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/linsert.n.html100666 1751 0 2263 6423554651 15634 0ustar kunkeewheel tcl7.6 User Commands - linsert

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/list.n.html100666 1751 0 3627 6423554652 15135 0ustar kunkeewheel tcl7.6 User Commands - list

tcl7.6 User Commands - 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  com-
     mand  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 com-
     mand
          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
itcl2.2/html/tcl7.6/llength.n.html100666 1751 0 1244 6423554652 15610 0ustar kunkeewheel tcl7.6 User Commands - llength

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/load.n.html100666 1751 0 13460 6423554652 15115 0ustar kunkeewheel tcl7.6 User Commands - load

tcl7.6 User Commands - 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 pro-
     cedure 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  pack-
     age,  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  inter-
     preter 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 pack-
     ageName 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 proto-
     type:
          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 speci-
     fied.

     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 sys-
     tems may detect the redundant loads, others may not).

SEE ALSO

     info sharedlibextension, Tcl_StaticPackage

KEYWORDS

     binary code, loading, shared library
itcl2.2/html/tcl7.6/lrange.n.html100666 1751 0 3210 6423554652 15416 0ustar kunkeewheel tcl7.6 User Commands - lrange

tcl7.6 User Commands - 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, how-
     ever,  produce  exactly  the  same results as ``list [lindex
     list first]''

KEYWORDS

     element, list, range, sublist
itcl2.2/html/tcl7.6/lreplace.n.html100666 1751 0 3465 6423554652 15751 0ustar kunkeewheel tcl7.6 User Commands - lreplace

tcl7.6 User Commands - 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 sim-
     ply deleted.

KEYWORDS

     element, list, replace
itcl2.2/html/tcl7.6/lsearch.n.html100666 1751 0 3251 6423554652 15574 0ustar kunkeewheel tcl7.6 User Commands - lsearch

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/lsort.n.html100666 1751 0 4416 6423554652 15322 0ustar kunkeewheel tcl7.6 User Commands - lsort

tcl7.6 User Commands - 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 con-
     trol  the  sorting   process   (unique   abbreviations   are
     accepted):

     -ascii               Use string comparison with ASCII colla-
                         tion 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
itcl2.2/html/tcl7.6/namespace.n.html100666 1751 0 31425 6423554652 16133 0ustar kunkeewheel tcl7.6 User Commands - namespace

tcl7.6 User Commands - namespace

NAME

     namespace - evaluate scripts in a particular namespace  con-
     text

SYNOPSIS

     namespace name ?-local? ?-enforced state? ?--? script?

DESCRIPTION

     The namespace command finds or creates a namespace name  and
     executes  an  optional  script  code string in that context.
     This command is usually used to add commands and  variables,
     or to redefine commands and variables, in a namespace.  When
     the script is executed, the namespace command  adds  a  call
     frame  to  the  stack,  so  the  namespace command counts as
     another level for the uplevel and upvar commands.

     If the -local flag is included, the namespace name  will  be
     found or created in the local namespace context.  Otherwise,
     name could reference any namespace found  by  following  the
     import list (see below for rules regarding name resolution).
     The -local flag allows a child namespace to be created  even
     if another namespace can be found with the same name.

     If the -enforced flag is included, its argument state  is  a
     boolean  value  enabling  or  disabling  special  rules  for
     command/variable name resolution.  This makes it possible to
     create "safe" namespaces with restricted access to commands.
     See the section on safe namespaces below for more details.

     The optional "--" marks the end of  the  option  list.   The
     next  argument  is  treated  as a command script, even if it
     starts with a "-" character.

OVERVIEW

     A namespace is a collection of commands and global variables
     that is kept apart from the usual global scope.  This allows
     Tcl code libraries to be packaged in a well-defined  manner,
     and  prevents unwanted interactions with other libraries.  A
     namespace can also have child namespaces within it,  so  one
     library  can  contain  its  own  private  copy of many other
     libraries.  The  global  scope  (named  "::")  is  the  root
     namespace  for an interpreter; all other namespaces are con-
     tained within it.

     Commands and variables local to a namespace  can  be  refer-
     enced  using  simple  names  within  the  namespace.  But in
     another context, they must be  qualified  by  the  namespace
     name.  Namespace qualifiers leading up to a command or vari-
     able name are separated by the "::" string.

     If a command, variable or namespace name is absolutely qual-
     ified  (i.e.,  it  starts  with  "::")  then  it is accessed
     directly.  For example, the name "::foo::bar::x"  refers  to
     the  variable "x", which is in the namespace "bar", which is
     in the namespace "foo", which is in  the  global  namespace.
     If the name does not start with "::", it is treated relative
     to the current namespace  context.   Lookup  starts  in  the
     current   namespace,   then   continues  through  all  other
     namespaces included on the "import" list.  The "info  which"
     command can be used to check the results of name resolution.
     Whenever a name is resolved, the result is  cached  to  keep
     namespace performance on par with vanilla Tcl.

     By default, the import list for each namespace includes  the
     parent  namespace,  so  commands  at the global scope can be
     accessed transparently.  The import list can be modified  by
     using the import command within a namespace.

     By default, commands and variables are "public" and  can  be
     accessed  from  any  other  namespace context.  The commands
     "protected" and "private" can be used when defining commands
     and  variables  to  restrict access to them.  These commands
     designate which parts of a library are meant to be  accessed
     by users, and which parts are not.

     A namespace can be deleted using the "delete namespace" com-
     mand.   This  deletes  all  commands  and  variables  in the
     namespace, and deletes all child namespaces as well.

EXAMPLE

     The following namespace implements a simple  counter  facil-
     ity:

         namespace counter {
             variable x 0

             proc restart {{by 1}} {
                 global x
                 set x 0
                 next $by
             }

             proc next {{by 1}} {
                 global x
                 incr x $by
                 return $x
             }
         }
         puts "Count up by 2..."
         puts "  count: [counter::next 2]"
         puts "  count: [counter::next 2]"
         puts "  count: [counter::next 2]"
         puts "restart: [counter::restart 2]"
         puts "  count: [counter::next 2]"


     The counter namespace contains  two  commands  (restart  and
     next)  and  one  global variable (x).  All of these elements
     are protected by the namespace, so there is no conflict, for
     example, between "counter::x" and another variable named "x"
     in the global namespace.

     Procedures execute in the context of the namespace that con-
     tains  them.  Within counter::restart and counter::next, the
     variable  name  "x"  refers   to   "::counter::x".    Within
     counter::restart,    the    command    "next"    refers   to
     "::counter::next".  Outside of the  namespace,  these  names
     must  be explicitly qualified with the "counter::" namespace
     path.

SAFE NAMESPACES

     Namespaces include a special enforcement feature that can be
     activated  using  the  -enforced  flag.  When enforcement is
     turned on, command and variable  references  can  be  inter-
     cepted,  and  the  usual lookup rules can be modified.  This
     supports the construction of "safe" namespaces, which inter-
     pret  code  from an untrusted source and deny access to com-
     mands which could damage the system.

     Whenever a command name is encountered, the namespace facil-
     ity  checks  to  see  if  the  current  namespace context is
     enforced.  If it is not, the usual name resolution rules are
     carried  out.  If it is, the namespace facility executes the
     following command in that context:

         enforce_cmd name

     If this procedure returns an error, access to  that  command
     is  denied.   If  it  returns a null string, name resolution
     continues according  to  the  usual  rules.   Otherwise,  it
     should  return  the same string name, or the name of another
     command to be substituted in its place.  This  procedure  is
     only  invoked  the first time a command name is encountered.
     The results are cached in the  name  resolution  tables,  so
     performance is not adversely affected.

     Variable references are handled the same  way,  except  that
     the following command is invoked to resolve the reference:

         enforce_var name

     Note that enforcement is carried out before any of the usual
     name resolution rules come into play.  Because of this, even
     absolute references like "::exec" or  "::counter::next"  can
     be intercepted and dealt with.

     Because the enforcement  procedures  apply  to  all  of  the
     command/variable references in a namespace, it can be diffi-
     cult to define procedures in an enforced namespace and  have
     them  work correctly.  If you deny access to the "proc" com-
     mand, for example, you will not be able to define  any  pro-
     cedures  in  the namespace.  To avoid problems like this, it
     is usually better to use  enforced  namespaces  as  follows.
     Set   up   a   namespace   containing  the  enforce_cmd  and
     enforce_var procedures, along with any other code needed  to
     enforce  the  namespace.   Within  that namespace, include a
     child namespace that is empty, but  has  enforcement  turned
     on.   Commands can be fed to the child namespace, which will
     automatically look to its parent for  the  enforcement  pro-
     cedures and all other commands/variables.  Procedures may be
     referenced from the child, but they will actually execute in
     the parent namespace, which is not enforced.

     In the following example, a "safe" namespace is  constructed
     which  will  interpret  any  command  string, but will guard
     access to commands like "exec" and  "open"  which  are  con-
     sidered  harmful.   Calls to "exec" are intercepted and sent
     to "safe_exec" for execution.  This logs the offending  com-
     mand  in  a file "security.log" and returns the null string.
     Calls to "open" are intercepted  and  sent  to  "safe_open".
     This  allows read access to ordinary files, but blocks write
     operations and execution of processes.  Note that the inter-
     ception  and  redirection of commands happens only when com-
     mands are interpreted in the namespace "safe::isolated".  In
     procedures  like  "safe_exec"  and  "safe_open",  which  are
     interpreted in namespace "safe", access to "exec" and "open"
     is allowed.

         namespace safe {

             proc interpret {cmds} {
                 namespace isolated $cmds
             }

             proc safe_exec {args} {
                 set mesg "access denied: $args"
                 puts stderr $mesg
                 catch {
                     set fid [open "security.log" a]
                     puts $fid $mesg
                     close $fid

                 }
             }

             proc safe_open {args} {
                 set file [lindex $args 0]
                 if {[string match |* $file]} {
                     error "cannot open process: $file"
                 }
                 set access [lindex $args 1]
                 if {$access == "r"} {
                     return [eval open $args]
                 }
                 error "cannot open with write access: [lindex $args 0]"
             }

             proc enforce_cmd {name} {
                 global commands
                 if {[info exists commands($name)]} {
                     return $commands($name)
                 }
                 return $name
             }
             set commands(exec) safe_exec
             set commands(::exec) safe_exec
             set commands(open) safe_open
             set commands(::open) safe_open

             proc enforce_var {name} {
                 if {[string match *::* $name]} {
                     error "variable access denied: $name"
                 }
                 return $name
             }

             namespace isolated -local -enforced yes
         }

         #
         # Use this to interpret a nasty script:
         #
         safe::interpret {
             #
             # Files can be read but not written.
             #
             set cmd {
                 set fid [open "/etc/passwd" r]
                 set info [read $fid]
                 close $fid
             }
             puts "read: [catch $cmd result] => $result"

             set cmd {
                 set fid [open "$env(HOME)/.cshrc" w]
                 puts $fid "# ha! ha!
                 puts $fid "# make the user think his files have been erased"
                 puts $fid "alias ls 'echo "total 0"'
                 close $fid
             }
             puts "write: [catch $cmd result] => $result"

             #
             # Kill all of the jobs we can find!
             #
             set processInfo [lrange [split [exec ps -gx] 0 1 end]
             foreach line $processInfo {
                 set pid [lindex $line 0]
                 exec kill -9 $pid
             }
         }

KEYWORDS

     delete, import, private, protected, public, variable
itcl2.2/html/tcl7.6/open.n.html100666 1751 0 30672 6423554652 15143 0ustar kunkeewheel tcl7.6 User Commands - open

tcl7.6 User Commands - 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.  Trun-
                    cate  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 posi-
                    tioned 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 control-
                    ling 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 nonblock-
                    ing 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 remain-
     ing  characters  of  fileName are treated as a list of argu-
     ments 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 pipe-
     line is directed to the current standard output unless over-
     ridden  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 execut-  |
          ing 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  pipe-  |
          line  does  not  use  standard  input or output, but is  |
          redirected from or to a file, then the  above  problems  |
          do not occur.                                            |

     Win-  |
          dows 95                                               |
          |                                                        |
          A command pipeline that executes a 16-bit DOS  applica-  |
          tion  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  exe-  |
          cute 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  keys-  |
          trokes  entered at the console will be sent to the com-  |
          mand pipeline and some will be sent to the Tcl  evalua-  |
          tor.   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 pipe-  |
          line 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  com-  |
          mand  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  fin-  |
          ished  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 immedi-  |
          ate 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  Win-  |
          dows  3.X,  there  are  no interactions between command  |
          pipelines and the console.                               |

     Macin-  |
          tosh                                                  |
          |                                                        |
          Opening a  command  pipeline  is  not  supported  under  |
          Macintosh,  since  applications do not support the con-  |
          cept 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  stan-  |
          dard  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,  per-
     missions, pipeline, process
itcl2.2/html/tcl7.6/package.n.html100666 1751 0 30105 6423554652 15564 0ustar kunkeewheel tcl7.6 User Commands - package

tcl7.6 User Commands - 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  avail-
     able 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.  Typi-
     cally, 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  inter-
          preter,  including information provided by both package
          ifneeded and package provide.

     package ifneeded package version ?script?
          This command typically appears only  in  system  confi-
          guration  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 pro-
          vide  to  indicate  that the package is present.  There
          may be information in the  database  for  several  dif-
          ferent  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 ver-
          sion  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  ver-
          sion  of  package  package is now present in the inter-
          preter.  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 whatso-
          ever  is  acceptable.   If  a  version  of  package has
          already been provided (by invoking the package  provide
          command), then its version number must satisfy the cri-
          teria given by - exact  and  version  and  the  command
          returns  immediately.   Otherwise, the command searches
          the database of information provided by previous  pack-
          age  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 pack-
          age ifneeded database does not  contain  an  acceptable
          version  of  the  package and a package unknown command
          has been specified for the interpreter then  that  com-
          mand  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  data-
          base.  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  sup-
          plied  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:   ver-
     sion  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 documenta-
     tion for pkg_mkIndex for details.

KEYWORDS

     package, version
itcl2.2/html/tcl7.6/pid.n.html100666 1751 0 2240 6423554652 14724 0ustar kunkeewheel tcl7.6 User Commands - pid

tcl7.6 User Commands - 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  ele-
     ments  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  iden-
     tifier  of the current process.  All process identifiers are
     returned as decimal strings.

KEYWORDS

     file, pipeline, process identifier
itcl2.2/html/tcl7.6/pkgMkIndex.n.html100666 1751 0 20260 6423554652 16233 0ustar kunkeewheel tcl7.6 User Commands - pkgMkIndex

tcl7.6 User Commands - pkgMkIndex

NAME

     pkg_mkIndex - Build an index for automatic loading of  pack-
     ages

SYNOPSIS

     pkg_mkIndex dir pattern ?pattern pattern ...?

DESCRIPTION

     Pkg_mkIndex is a utility procedure that is part of the stan-
     dard  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 pack-  |
          ages (e.g., those that contain only Tcl scripts) should  |
          be installed under the second directory.  The subdirec-  |
          tory 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 subdirec-  |
          tory 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 expli-
          citly 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 ver-
          sion 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  inter-
          preter,  based  on  the  first call to package require.
          Different versions of a package may be loaded  in  dif-
          ferent 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 pack-
     age 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  ver-
     sion  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 initializa-
     tion 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 actu-
     ally  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
itcl2.2/html/tcl7.6/private.n.html100666 1751 0 3435 6423554652 15631 0ustar kunkeewheel tcl7.6 User Commands - private

tcl7.6 User Commands - private

NAME

     private - create commands/variables with "private" access

SYNOPSIS

     private command ?arg arg ...?

DESCRIPTION

     Sets the protection  level  for  new  commands/variables  to
     "private"  and then evaluates the remaining arguments.  Note
     that the default protection level for commands/variables  is
     "public".  Commands and variables can also be "protected".

     The command argument may be a  command  name  like  proc  or
     variable, or a script full of command/variable declarations.
     Any command that creates another command or variable can  be
     used  in conjunction with the private command.  For example,
     if widget commands are executed via  "private",  the  widget
     access commands will be private.

     Private  commands/variables  are  only  accessible  in   the
     namespace where they are defined.

EXAMPLE

         namespace foo {
             private {
                 variable x 0
                 variable y 1
             }
             private proc check {} {
                 global x y
                 return "$x $y"
             }
         }

         namespace foo {  ;# access allowed
             check
         }
         foo::check       ;# access denied

KEYWORDS

     import, namespace,  private,  protected,  public,  variable,
     proc
itcl2.2/html/tcl7.6/proc.n.html100666 1751 0 6466 6423554653 15132 0ustar kunkeewheel tcl7.6 User Commands - proc

tcl7.6 User Commands - 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 sin-
     gle field in the specifier then it is the name of the  argu-
     ment;  if  there are two fields, then the first is the argu-
     ment 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  invoca-
     tion.   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 spe-
     cial 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  argu-
     ments  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 com-
     mand.

     The proc command returns an empty string.  When a  procedure
     is invoked, the procedure's return value is the value speci-
     fied 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
itcl2.2/html/tcl7.6/protected.n.html100666 1751 0 3710 6423554653 16145 0ustar kunkeewheel tcl7.6 User Commands - protected

tcl7.6 User Commands - protected

NAME

     protected  -  create  commands/variables  with   "protected"
     access

SYNOPSIS

     protected command ?arg arg ...?

DESCRIPTION

     Sets the protection  level  for  new  commands/variables  to
     "protected"  and  then  evaluates  the  remaining arguments.
     Note    that    the    default    protection    level    for
     commands/variables  is "public".  Commands and variables can
     also be "private".

     The command argument may be a  command  name  like  proc  or
     variable, or a script full of command/variable declarations.
     Any command that creates another command or variable can  be
     used  in  conjunction with the protected command.  For exam-
     ple, if widget commands are executed  via  "protected",  the
     widget access commands will be protected.

     Protected commands/variables are accessible in the namespace
     where  they  are  defined,  and  in any other namespace that
     imports the defining namespace in a "protected"  mode.   See
     the import command for details concerning the import list.

EXAMPLE

         namespace foo {
             protected {
                 variable x 0
                 variable y 1
             }
             protected proc check {} {
                 global x y
                 return "$x $y"
             }
         }
         import add {foo protected}
         foo::check

KEYWORDS

     import, namespace,  private,  protected,  public,  variable,
     proc
itcl2.2/html/tcl7.6/public.n.html100666 1751 0 3222 6423554653 15430 0ustar kunkeewheel tcl7.6 User Commands - public

tcl7.6 User Commands - public

NAME

     public - create commands/variables with "public" access

SYNOPSIS

     public command ?arg arg ...?

DESCRIPTION

     Sets the protection  level  for  new  commands/variables  to
     "public"  and  then evaluates the remaining arguments.  Note
     that the default protection level for commands/variables  is
     "public".   Other  protection  levels  are  "protected"  and
     "private".

     The command argument may be a  command  name  like  proc  or
     variable, or a script full of command/variable declarations.
     Any command that creates another command or variable can  be
     used  in  conjunction with the public command.  For example,
     if widget commands are executed  via  "public",  the  widget
     access commands will be public.

     Public commands/variables are accessible from any namespace.

EXAMPLE

         namespace foo {
             public {
                 variable x 0
                 variable y 1
             }
             public proc check {} {
                 global x y
                 return "$x $y"
             }
         }
         foo::check

KEYWORDS

     namespace, private, protected, public, variable, proc
itcl2.2/html/tcl7.6/puts.n.html100666 1751 0 6337 6423554653 15157 0ustar kunkeewheel tcl7.6 User Commands - puts

tcl7.6 User Commands - 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 speci-
     fied 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 fcon-
     figure manual entry for a discussion of end-of-line transla-
     tions.

     Tcl buffers output internally, so  characters  written  with
     puts  may  not appear immediately on the output file or dev-
     ice;  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  nor-
     mally  block  until  all the buffered data has been accepted
     for output by the operating system.  If channelId is in non-
     blocking  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 out-
     put 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  chan-
     nel  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
itcl2.2/html/tcl7.6/pwd.n.html100666 1751 0 1120 6423554653 14737 0ustar kunkeewheel tcl7.6 User Commands - pwd

tcl7.6 User Commands - pwd

NAME

     pwd - Return the current working directory

SYNOPSIS

     pwd

DESCRIPTION

     Returns the path name of the current working directory.

KEYWORDS

     working directory
itcl2.2/html/tcl7.6/read.n.html100666 1751 0 3713 6423554653 15072 0ustar kunkeewheel tcl7.6 User Commands - read

tcl7.6 User Commands - 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 -nonew-
     line switch is ignored if the command returns before  reach-
     ing the end of the file.

     Read translates end-of-line sequences in the input into new-
     line 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
itcl2.2/html/tcl7.6/regexp.n.html100666 1751 0 17177 6423554653 15502 0ustar kunkeewheel tcl7.6 User Commands - regexp

tcl7.6 User Commands - regexp

NAME

     regexp - Match a regular expression against a string

SYNOPSIS

     regexp ?switches? exp string  ?matchVar?  ?subMatchVar  sub-
     MatchVar ...?

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 subexpres-
     sion within exp, the next subMatchVar will contain the char-
     acters  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 follow-
               ing  this  one  will  be treated as exp even if it
               starts with a -.

     If there are more subMatchVar's  than  parenthesized  subex-
     pressions  within  exp,  or if a particular subexpression in
     exp doesn't match the string (e.g. because it was in a  por-
     tion  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 fol-
     lowed 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 charac-
     ter), 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  char-
     acter  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 (follow-
     ing 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  poten-
     tial  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
itcl2.2/html/tcl7.6/regsub.n.html100666 1751 0 6441 6423554653 15447 0ustar kunkeewheel tcl7.6 User Commands - regsub

tcl7.6 User Commands - 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.  Addi-
     tional 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 match-
               ing  range  is  found and substituted.  If -all is
               specified, then ``&''  and  ``\n''  sequences  are
               handled  for  each substitution using the informa-
               tion from the corresponding match.

     -nocase    Upper-case characters in string will be converted
               to  lower-case  before matching against exp;  how-
               ever, substitutions specified by subSpec  use  the
               original unconverted form of string.

     --          Marks the end of switches.  The argument follow-
               ing  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  expres-
     sions.

KEYWORDS

     match, pattern, regular expression, substitute
itcl2.2/html/tcl7.6/rename.n.html100666 1751 0 1514 6423554653 15423 0ustar kunkeewheel tcl7.6 User Commands - rename

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/return.n.html100666 1751 0 7537 6423554653 15506 0ustar kunkeewheel tcl7.6 User Commands - return

tcl7.6 User Commands - 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 han-
               dling of errorInfo and  errorCode  variables  (see
               below).

     return    The current procedure will return with  a  comple-
               tion  code  of  TCL_RETURN,  so that the procedure
               that invoked it will return also.

     break     The current procedure will return with  a  comple-
               tion  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  comple-
               tion  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
itcl2.2/html/tcl7.6/scan.n.html100666 1751 0 15500 6423554653 15120 0ustar kunkeewheel tcl7.6 User Commands - scan

tcl7.6 User Commands - 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  conver-
     sion  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  stan-
               dard  in that the input field always consists of a
               single character and no field width may be  speci-
               fied.

     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  charac-
               ters  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  charac-
               ters  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  conver-
     sion is the largest number that makes sense for that partic-
     ular 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 max-
     imum field width has been reached,  whichever  comes  first.
     If  a * is present in the conversion specifier then no vari-
     able 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  sup-
          ported.

     [2]  For %c conversions a single  character  value  is  con-
          verted  to  a decimal string, which is then assigned to
          the corresponding varName; no field width may be speci-
          fied 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
itcl2.2/html/tcl7.6/scope.n.html100666 1751 0 5101 6423554653 15261 0ustar kunkeewheel tcl7.6 User Commands - scope

tcl7.6 User Commands - scope

NAME

     scope - capture the namespace context for a variable

SYNOPSIS

     scope string

DESCRIPTION

     Creates a scoped value for the specified  string,  which  is
     usually  a  variable  name.   A  scoped value is a list with
     three elements:  the "@scope" keyword, a namespace  context,
     and the value string.  For example, the command

         namespace foo {
             scope "x"
         }

     produces the scoped value:

         @scope ::foo x

     Note that the scope command captures the  current  namespace
     context.   If  the string is itself a scoped value, then the
     current context  is  ignored  and  the  string  is  returned
     directly.

     Ordinary variable names refer to  variables  in  the  global
     namespace.  A scoped value captures a variable name together
     with its namespace context in a way that  allows  it  to  be
     referenced  properly  later.   It is needed, for example, to
     wrap up variable names when a Tk widget  is  used  within  a
     namespace:

         namespace foo {
             private variable mode 1

             radiobutton .rb1 -text "Mode #1"         -variable [scope mode] -value 1
             pack .rb1

             radiobutton .rb2 -text "Mode #2"         -variable [scope mode] -value 2
             pack .rb2
         }

     Radiobuttons .rb1 and .rb2 interact via the variable  "mode"
     contained in the namespace "foo".  The scope command guaran-
     tees this by creating the variable name "@scope ::foo mode".

     Scoped variables can be used anywhere that an ordinary vari-
     able   name  is  recognized.   For  example,  the  following
     statements are allowed:

         set {@scope ::foo mode} 3
         puts "value = ${@scope ::foo mode}"

     Note that scoped  variables  by-pass  the  usual  protection
     mechanisms;  the name "@scope ::foo mode" can be used in any
     namespace context to access the "foo::mode"  variable,  even
     though it is private.

KEYWORDS

     @scope, code, namespace, private, protected, public
itcl2.2/html/tcl7.6/seek.n.html100666 1751 0 4425 6423554653 15107 0ustar kunkeewheel tcl7.6 User Commands - seek

tcl7.6 User Commands - seek

NAME

     seek - Change the access position for an open channel

SYNOPSIS

     seek channelId offset ?origin?

DESCRIPTION

     Changes the current access position  for  channelId.   Chan-
     nelId  must  be a channel identifier such as returned from a
     previous invocation of open or socket.  The offset and  ori-
     gin 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 fol-
     lowing:

     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  under-
               lying 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 non-
     blocking 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 underly-
     ing file or device does not support seeking.

KEYWORDS

     access position, file, seek
itcl2.2/html/tcl7.6/set.n.html100666 1751 0 2656 6423554653 14757 0ustar kunkeewheel tcl7.6 User Commands - set

tcl7.6 User Commands - set

NAME

     set - Read and write variables

SYNOPSIS

     set varName ?value?

DESCRIPTION

     Returns the value of variable varName.  If value  is  speci-
     fied, 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  pro-
     cedure unless the global command has been invoked to declare
     varName to be global.

KEYWORDS

     read, write, variable
itcl2.2/html/tcl7.6/socket.n.html100666 1751 0 14734 6423554653 15474 0ustar kunkeewheel tcl7.6 User Commands - socket

tcl7.6 User Commands - 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 com-
     mands 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 connec-
     tion, 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  con-
          nected  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 automati-
     cally accept connections to the given port.  For  each  con-
     nection  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;   how-
     ever, 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 com-
     mand or calling the C procedure Tcl_DoOneEvent, then no con-
     nections 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
itcl2.2/html/tcl7.6/source.n.html100666 1751 0 3656 6423554654 15466 0ustar kunkeewheel tcl7.6 User Commands - source

tcl7.6 User Commands - 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 nor-
     mally with the result from the return command.

     The -rsrc and -rsrcid forms of this command are only  avail-
     able  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
itcl2.2/html/tcl7.6/split.n.html100666 1751 0 3450 6423554654 15311 0ustar kunkeewheel tcl7.6 User Commands - split

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/string.n.html100666 1751 0 15573 6423554654 15515 0ustar kunkeewheel tcl7.6 User Commands - string

tcl7.6 User Commands - 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  argu-
          ment.   A charIndex of 0 corresponds to the first char-
          acter 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  charac-
          ters 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  pro-
                    vides a way of avoiding the special interpre-
                    tation 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  trail-
          ing 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 con-
          sidered 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
itcl2.2/html/tcl7.6/subst.n.html100666 1751 0 4027 6423554654 15317 0ustar kunkeewheel tcl7.6 User Commands - subst

tcl7.6 User Commands - subst

NAME

     subst - Perform backslash, command, and  variable  substitu-
     tions

SYNOPSIS

     subst ?-nobackslashes? ?-nocommands? ?-novariables? string

DESCRIPTION

     This command performs variable substitutions,  command  sub-
     stitutions,  and backslash substitutions on its string argu-
     ment and returns the fully-substituted result.  The  substi-
     tutions  are  performed  in  exactly the same way as for Tcl
     commands.  As a result, the string argument is actually sub-
     stituted  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 interpre-
     tation.

     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  sub-
     stitution
itcl2.2/html/tcl7.6/switch.n.html100666 1751 0 11766 6423554654 15510 0ustar kunkeewheel tcl7.6 User Commands - switch

tcl7.6 User Commands - 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 pat-
     tern  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  follow-
               ing  this one will be treated as string even if it
               starts with a -.

     Two syntaxes are provided for the  pattern  and  body  argu-
     ments.   The  first uses a separate argument for each of the
     patterns and commands; this form is convenient if  substitu-
     tions  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
itcl2.2/html/tcl7.6/tcl7.6API.html100666 1751 0 7423 6423554654 15275 0ustar kunkeewheel
tcl7.6 C API
tcl7.6 C API
itcl2.2/html/tcl7.6/tcl7.6UserCmds.html100666 1751 0 12546 6423554654 16433 0ustar kunkeewheel
tcl7.6 User Commands
tcl7.6 User Commands
itcl2.2/html/tcl7.6/tclvars.n.html100666 1751 0 33355 6423554654 15663 0ustar kunkeewheel tcl7.6 User Commands - tclvars

tcl7.6 User Commands - 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 addi-
          tional 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 ter-
               minate;  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 mes-
               sage 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  iden-
               tifier  (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 mes-
               sage 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 sin-
               gle 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  pro-
          cedures 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 pro-
          cedures 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.

     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 instruc-
          tion 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 addi-
          tional 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  run-
               ning  on  this machine.  On UNIX machines, this is
               the value returned by uname -r.

          platform
               Either windows, macintosh, or unix.  This  identi-
               fies  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 vari-
          able is returned by the info tclversion command.

KEYWORDS

     arithmetic, error, environment,  POSIX,  precision,  subpro-
     cess, variables
itcl2.2/html/tcl7.6/tell.n.html100666 1751 0 1355 6423554654 15120 0ustar kunkeewheel tcl7.6 User Commands - tell

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/time.n.html100666 1751 0 1766 6423554654 15124 0ustar kunkeewheel tcl7.6 User Commands - time

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/trace.n.html100666 1751 0 20264 6423554654 15276 0ustar kunkeewheel tcl7.6 User Commands - trace

tcl7.6 User Commands - 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 con-
          text  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 vari-
          able  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 vari-
          able.

          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  pro-
          cedure  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
itcl2.2/html/tcl7.6/unknown.n.html100666 1751 0 12706 6423554654 15701 0ustar kunkeewheel tcl7.6 User Commands - unknown

tcl7.6 User Commands - 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 typ-
     ically  does  things  like  searching through library direc-
     tories 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 execut-
     able  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 sub-
     stitution in the same way that  csh  would  for  these  con-
     structs.   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.

     Many extensions redefine  the  unknown  command  to  include
     their  own  special  command  processing.   If more than one
     extension tries to do this, however, the  results  conflict.
     The  standard  unknown  command is now set up to handle this
     correctly.  Each extension  can  register  its  own  command
     handler using the following command:
          unknown_handler name command ?arg arg ...?
     Here, name is a symbolic name identifying the handler.   The
     command  string  and  any extra arg arguments are integrated
     into the unknown command.

     Each time an unknown command is  encountered,  the  list  of
     handlers  is  consulted  to determine how to handle the com-
     mand.  If a handler recognizes the command, then  it  should
     load,  define,  or  otherwise handle the command and return.
     Otherwise, it should return "-code  continue",  which  tells
     the  unknown  facility  to  continue  with  another handler.
     Handlers registered first are  consulted  last.   This  way,
     extensions  that  are  loaded later have higher priority for
     handling special cases.

     Usually command is the name of a  handling  procedure.   But
     extra  arg  arguments  can  be specified when the handler is
     registered, and these will be kept as part of  the  handler.
     The  actual  unknown  command and its arguments are appended
     after these when the handler is invoked.

KEYWORDS

     error, non-existent command
itcl2.2/html/tcl7.6/unset.n.html100666 1751 0 2262 6423554654 15314 0ustar kunkeewheel tcl7.6 User Commands - unset

tcl7.6 User Commands - 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 vari-
     ables after the non-existent one are not deleted.

KEYWORDS

     remove, variable
itcl2.2/html/tcl7.6/update.n.html100666 1751 0 4137 6423554654 15443 0ustar kunkeewheel tcl7.6 User Commands - update

tcl7.6 User Commands - 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
itcl2.2/html/tcl7.6/uplevel.n.html100666 1751 0 6763 6423554654 15644 0ustar kunkeewheel tcl7.6 User Commands - uplevel

tcl7.6 User Commands - 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 pro-
     cedure  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  com-
     mand 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  disap-
     pear  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  con-
     structs  as  Tcl  procedures  (for example, uplevel could be
     used to implement the while construct as a Tcl procedure).

KEYWORDS

     context, stack frame, variables
itcl2.2/html/tcl7.6/upvar.n.html100666 1751 0 7764 6423554654 15327 0ustar kunkeewheel tcl7.6 User Commands - upvar

tcl7.6 User Commands - 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 pro-
     cedure 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) accessi-
     ble in the current  procedure  by  the  name  given  in  the
     corresponding  myVar argument.  The variable named by other-
     Var 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  vari-
     able,  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 vari-  |
     able 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
itcl2.2/html/tcl7.6/variable.n.html100666 1751 0 3440 6423554655 15743 0ustar kunkeewheel tcl7.6 User Commands - variable

tcl7.6 User Commands - variable

NAME

     variable - create or modify a global variable

SYNOPSIS

     variable varName ?value?

DESCRIPTION

     Creates a global  variable  named  varName  in  the  current
     namespace  context  and  sets  its protection to the current
     level.  If the variable already exists,  it  is  updated  to
     have  the  current  protection level.  If the optional value
     string is specified, the variable  is  set  to  that  value.
     This command is usually used in conjunction with the public,
     protected and private commands to declare a variable with  a
     certain protection level within a namespace.

     The varName string cannot reference  an  element  within  an
     array.   Instead, varName should reference the entire array,
     and the initialization value should be left off.  After  the
     variable has been declared, elements within the array can be
     set using ordinary set statements or the array command.

     If the variable command is used within a procedure, it  will
     still  create  or  modify  a global variable, but unlike the
     global command, it will not install an alias to the variable
     in the local call frame.

KEYWORDS

     global, namespace, private, protected, public
itcl2.2/html/tcl7.6/vwait.n.html100666 1751 0 2777 6423554655 15324 0ustar kunkeewheel tcl7.6 User Commands - vwait

tcl7.6 User Commands - 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 contin-
     ues 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  exam-
     ple,  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
itcl2.2/html/tcl7.6/while.n.html100666 1751 0 2662 6423554655 15273 0ustar kunkeewheel tcl7.6 User Commands - while

tcl7.6 User Commands - 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 inter-
     preter.  Once body has been executed then test is  evaluated
     again,  and the process repeats until eventually test evalu-
     ates 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
itcl2.2/html/tk4.2/ 40755 1751 0 0 6423554674 12560 5ustar kunkeewheelitcl2.2/html/tk4.2/CVS/ 40755 1751 0 0 6423570013 13174 5ustar kunkeewheelitcl2.2/html/tk4.2/CVS/Root100644 1751 0 26 6423554655 14113 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/html/tk4.2/CVS/Repository100644 1751 0 11 6423674264 15340 0ustar kunkeewheel/usr/cvs itcl2.2/html/tk4.2/CVS/Entries100644 1751 0 14270 6423570013 14651 0ustar kunkeewheel/3DBorder.3.html/1.1.1.1/Thu Oct 23 04:59:25 1997// /BindTable.3.html/1.1.1.1/Thu Oct 23 04:59:25 1997// /CanvPsY.3.html/1.1.1.1/Thu Oct 23 04:59:25 1997// /CanvTkwin.3.html/1.1.1.1/Thu Oct 23 04:59:25 1997// /CanvTxtInfo.3.html/1.1.1.1/Thu Oct 23 04:59:25 1997// /Clipboard.3.html/1.1.1.1/Thu Oct 23 04:59:25 1997// /ClrSelect.3.html/1.1.1.1/Thu Oct 23 04:59:26 1997// /ConfigWidg.3.html/1.1.1.1/Thu Oct 23 04:59:26 1997// /ConfigWind.3.html/1.1.1.1/Thu Oct 23 04:59:26 1997// /CoordToWin.3.html/1.1.1.1/Thu Oct 23 04:59:26 1997// /CrtErrHdlr.3.html/1.1.1.1/Thu Oct 23 04:59:26 1997// /CrtGenHdlr.3.html/1.1.1.1/Thu Oct 23 04:59:26 1997// /CrtImgType.3.html/1.1.1.1/Thu Oct 23 04:59:26 1997// /CrtItemType.3.html/1.1.1.1/Thu Oct 23 04:59:26 1997// /CrtPhImgFmt.3.html/1.1.1.1/Thu Oct 23 04:59:26 1997// /CrtSelHdlr.3.html/1.1.1.1/Thu Oct 23 04:59:26 1997// /CrtWindow.3.html/1.1.1.1/Thu Oct 23 04:59:26 1997// /DeleteImg.3.html/1.1.1.1/Thu Oct 23 04:59:27 1997// /DrawFocHlt.3.html/1.1.1.1/Thu Oct 23 04:59:27 1997// /EventHndlr.3.html/1.1.1.1/Thu Oct 23 04:59:27 1997// /FindPhoto.3.html/1.1.1.1/Thu Oct 23 04:59:27 1997// /FreeXId.3.html/1.1.1.1/Thu Oct 23 04:59:27 1997// /GeomReq.3.html/1.1.1.1/Thu Oct 23 04:59:27 1997// /GetAnchor.3.html/1.1.1.1/Thu Oct 23 04:59:27 1997// /GetBitmap.3.html/1.1.1.1/Thu Oct 23 04:59:27 1997// /GetCapStyl.3.html/1.1.1.1/Thu Oct 23 04:59:27 1997// /GetClrmap.3.html/1.1.1.1/Thu Oct 23 04:59:27 1997// /GetColor.3.html/1.1.1.1/Thu Oct 23 04:59:27 1997// /GetCursor.3.html/1.1.1.1/Thu Oct 23 04:59:27 1997// /GetFontStr.3.html/1.1.1.1/Thu Oct 23 04:59:28 1997// /GetGC.3.html/1.1.1.1/Thu Oct 23 04:59:28 1997// /GetImage.3.html/1.1.1.1/Thu Oct 23 04:59:28 1997// /GetJoinStl.3.html/1.1.1.1/Thu Oct 23 04:59:28 1997// /GetJustify.3.html/1.1.1.1/Thu Oct 23 04:59:28 1997// /GetOption.3.html/1.1.1.1/Thu Oct 23 04:59:28 1997// /GetPixels.3.html/1.1.1.1/Thu Oct 23 04:59:28 1997// /GetPixmap.3.html/1.1.1.1/Thu Oct 23 04:59:28 1997// /GetRelief.3.html/1.1.1.1/Thu Oct 23 04:59:28 1997// /GetRootCrd.3.html/1.1.1.1/Thu Oct 23 04:59:28 1997// /GetScroll.3.html/1.1.1.1/Thu Oct 23 04:59:29 1997// /GetSelect.3.html/1.1.1.1/Thu Oct 23 04:59:31 1997// /GetUid.3.html/1.1.1.1/Thu Oct 23 04:59:31 1997// /GetVRoot.3.html/1.1.1.1/Thu Oct 23 04:59:32 1997// /GetVisual.3.html/1.1.1.1/Thu Oct 23 04:59:32 1997// /HandleEvent.3.html/1.1.1.1/Thu Oct 23 04:59:32 1997// /IdToWindow.3.html/1.1.1.1/Thu Oct 23 04:59:32 1997// /ImgChanged.3.html/1.1.1.1/Thu Oct 23 04:59:32 1997// /InternAtom.3.html/1.1.1.1/Thu Oct 23 04:59:32 1997// /MainLoop.3.html/1.1.1.1/Thu Oct 23 04:59:32 1997// /MainWin.3.html/1.1.1.1/Thu Oct 23 04:59:32 1997// /MaintGeom.3.html/1.1.1.1/Thu Oct 23 04:59:32 1997// /ManageGeom.3.html/1.1.1.1/Thu Oct 23 04:59:32 1997// /MapWindow.3.html/1.1.1.1/Thu Oct 23 04:59:32 1997// /MoveToplev.3.html/1.1.1.1/Thu Oct 23 04:59:32 1997// /Name.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /NameOfImg.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /OwnSelect.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /ParseArgv.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /QWinEvent.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /Restack.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /RestrictEv.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /SetAppName.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /SetClass.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /SetGrid.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /SetVisual.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /StrictMotif.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /Tk_Init.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /Tk_Main.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /WindowId.3.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /bell.n.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /bind.n.html/1.1.1.1/Thu Oct 23 04:59:33 1997// /bindtags.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /bitmap.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /button.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /canvas.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /checkbutton.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /chooseColor.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /clipboard.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /destroy.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /dialog.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /entry.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /event.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /focus.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /focusNext.n.html/1.1.1.1/Thu Oct 23 04:59:34 1997// /frame.n.html/1.1.1.1/Thu Oct 23 04:59:35 1997// /getOpenFile.n.html/1.1.1.1/Thu Oct 23 04:59:35 1997// /grab.n.html/1.1.1.1/Thu Oct 23 04:59:35 1997// /grid.n.html/1.1.1.1/Thu Oct 23 04:59:35 1997// /image.n.html/1.1.1.1/Thu Oct 23 04:59:35 1997// /label.n.html/1.1.1.1/Thu Oct 23 04:59:35 1997// /listbox.n.html/1.1.1.1/Thu Oct 23 04:59:35 1997// /lower.n.html/1.1.1.1/Thu Oct 23 04:59:35 1997// /menu.n.html/1.1.1.1/Thu Oct 23 04:59:36 1997// /menubar.n.html/1.1.1.1/Thu Oct 23 04:59:36 1997// /menubutton.n.html/1.1.1.1/Thu Oct 23 04:59:36 1997// /message.n.html/1.1.1.1/Thu Oct 23 04:59:36 1997// /messageBox.n.html/1.1.1.1/Thu Oct 23 04:59:36 1997// /option.n.html/1.1.1.1/Thu Oct 23 04:59:36 1997// /optionMenu.n.html/1.1.1.1/Thu Oct 23 04:59:36 1997// /options.n.html/1.1.1.1/Thu Oct 23 04:59:36 1997// /pack-old.n.html/1.1.1.1/Thu Oct 23 04:59:36 1997// /pack.n.html/1.1.1.1/Thu Oct 23 04:59:37 1997// /palette.n.html/1.1.1.1/Thu Oct 23 04:59:37 1997// /photo.n.html/1.1.1.1/Thu Oct 23 04:59:37 1997// /place.n.html/1.1.1.1/Thu Oct 23 04:59:37 1997// /popup.n.html/1.1.1.1/Thu Oct 23 04:59:37 1997// /radiobutton.n.html/1.1.1.1/Thu Oct 23 04:59:37 1997// /raise.n.html/1.1.1.1/Thu Oct 23 04:59:37 1997// /scale.n.html/1.1.1.1/Thu Oct 23 04:59:37 1997// /scrollbar.n.html/1.1.1.1/Thu Oct 23 04:59:38 1997// /selection.n.html/1.1.1.1/Thu Oct 23 04:59:38 1997// /send.n.html/1.1.1.1/Thu Oct 23 04:59:38 1997// /text.n.html/1.1.1.1/Thu Oct 23 04:59:39 1997// /tk.n.html/1.1.1.1/Thu Oct 23 04:59:39 1997// /tk4.2API.html/1.1.1.1/Thu Oct 23 04:59:39 1997// /tk4.2UserCmds.html/1.1.1.1/Thu Oct 23 04:59:39 1997// /tkerror.n.html/1.1.1.1/Thu Oct 23 04:59:39 1997// /tkvars.n.html/1.1.1.1/Thu Oct 23 04:59:39 1997// /tkwait.n.html/1.1.1.1/Thu Oct 23 04:59:39 1997// /toplevel.n.html/1.1.1.1/Thu Oct 23 04:59:40 1997// /winfo.n.html/1.1.1.1/Thu Oct 23 04:59:40 1997// /wm.n.html/1.1.1.1/Thu Oct 23 04:59:40 1997// itcl2.2/html/tk4.2/3DBorder.3.html100666 1751 0 50337 6423554655 15343 0ustar kunkeewheel tk4.2 C API - 3DBorder

tk4.2 C API - 3DBorder

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  pre-
                                           viously  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  rec-
                                           tangle  given by x, y,
                                           width,  height,  nega-
                                           tive  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 tra-
                                           jectory.   If  leftRe-
                                           lief                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  rela-
                                           tive     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  bot-
                                           tom  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  bot-
                                           tom  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 con-
                                           texts   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 bord-
     ers  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 allocat-
     ing 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 indi-
     cates 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 rectan-
     gle,  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 com-
     plex   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 pro-
     cedures 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  rec-
     tangular 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  back-
     ground 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
itcl2.2/html/tk4.2/BindTable.3.html100666 1751 0 24737 6423554655 15570 0ustar kunkeewheel tk4.2 C API - BindTable

tk4.2 C API - BindTable

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 bind-
                                                ing  table.  Also
                                                used for  return-
                                                ing  results  and
                                                errors from bind-
                                                ing 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 bind-
                                                ing  is   associ-
                                                ated.

     char              *eventString   (in)      String describing
                                                event sequence.

     char              *script        (in)      Tcl   script   to
                                                invoke when bind-
                                                ing 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 col-
     lection 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 struc-
     ture.  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 use-
     ful 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 bindingT-
     able 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  bin-
     dingTable 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  par-
     ticular  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
itcl2.2/html/tk4.2/CanvPsY.3.html100666 1751 0 17476 6423554655 15271 0ustar kunkeewheel tk4.2 C API - CanvPsY

tk4.2 C API - CanvPsY

NAME

     Tk_CanvasPsY,      Tk_CanvasPsBitmap,      Tk_CanvasPsColor,
     Tk_CanvasPsFont, Tk_CanvasPsPath, Tk_CanvasPsStipple - util-
     ity 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 iden-
                                               tifies   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 out-
                                               put, 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  coordi-
                                               nates for  one  or
                                               more points speci-
                                               fied   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  can-
     vas.    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 map-
     ping 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
itcl2.2/html/tk4.2/CanvTkwin.3.html100666 1751 0 25423 6423554655 15641 0ustar kunkeewheel tk4.2 C API - CanvTkwin

tk4.2 C API - CanvTkwin

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 identi-
                                             fies     a    canvas
                                             widget.

     Tcl_Interp    *interp         (in/out)  Interpreter  to  use
                                             for error reporting.

     char          *string         (in)      Textual  description
                                             of  a canvas coordi-
                                             nate.

     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  loca-
                                             tion   in  which  to
                                             store an  x  coordi-
                                             nate in the space of
                                             the         drawable
                                             currently being used
                                             to   redisplay   the
                                             canvas.

     short         *drawableYPtr   (out)     Pointer to  a  loca-
                                             tion   in  which  to
                                             store a y coordinate
                                             in  the space of the
                                             drawable   currently
                                             being     used    to
                                             redisplay  the  can-
                                             vas.

     GC            gc              (out)     Graphics context  to
                                             modify.

     short         *screenXPtr     (out)     Points to a location
                                             in  which  to  store
                                             the  screen  coordi-
                                             nate  in  the canvas
                                             window          that
                                             corresponds to x.

     short         *screenYPtr     (out)     Points to a location
                                             in  which  to  store
                                             the  screen  coordi-
                                             nate  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  coor-
                                             dinate  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 coordi-
                                             nate  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  per-
     form various utility functions.

     Tk_CanvasTkwin returns the Tk_Window associated with a  par-
     ticular canvas.

     Tk_CanvasGetCoord translates a  string  specification  of  a
     coordinate (such as 2p or 1.6c) into a double-precision can-
     vas coordinate.  If string is a valid coordinate description
     then Tk_CanvasGetCoord stores the corresponding canvas coor-
     dinate 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  com-
     pensate  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 exam-
     ple  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  pro-
     cedures  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
itcl2.2/html/tk4.2/CanvTxtInfo.3.html100666 1751 0 12204 6423554655 16131 0ustar kunkeewheel tk4.2 C API - CanvTxtInfo

tk4.2 C API - CanvTxtInfo

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.  sel-
     BorderWidth 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 exam-
     ple,  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 selI-
     temPtr, selectFirst,  selectLast,  and  selectAnchor.   Type
     managers  may  change selectFirst, selectLast, and selectAn-
     chor 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
itcl2.2/html/tk4.2/Clipboard.3.html100666 1751 0 10463 6423554655 15632 0ustar kunkeewheel tk4.2 C API - Clipboard

tk4.2 C API - Clipboard

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 clip-
                                           board 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 clip-
     board  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  clip-
     board.   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
itcl2.2/html/tk4.2/ClrSelect.3.html100666 1751 0 2720 6423554656 15571 0ustar kunkeewheel tk4.2 C API - ClrSelect

tk4.2 C API - ClrSelect

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 selec-
     tion need not be in tkwin itself or even in tkwin's applica-
     tion.  If there is a window anywhere on tkwin's display that
     owns selection, the window will be notified and  the  selec-
     tion will be cleared.  If there is no owner for selection on
     the display, then the procedure has no effect.

KEYWORDS

     clear, selection
itcl2.2/html/tk4.2/ConfigWidg.3.html100666 1751 0 112175 6423554656 15777 0ustar kunkeewheel tk4.2 C API - ConfigWidg

tk4.2 C API - ConfigWidg

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  mes-
                                          sages.

     Tk_Window       tkwin      (in)      Window     used      to
                                          represent        widget
                                          (needed  to  set  up  X
                                          resources).

     Tk_ConfigSpec   *specs     (in)      Pointer to table speci-
                                          fying  legal configura-
                                          tion 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 com-
                                          bination of flags  that
                                          control  the processing
                                          of configuration infor-
                                          mation.
                                          TK_CONFIG_ARGV_ONLY
                                          causes the option data-
                                          base 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  com-
                                          mand).   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 com-
     mand is invoked for a widget.  Although  intended  primarily
     for  widgets, Tk_ConfigureWidget can be used in other situa-
     tions 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  confi-
     guration 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  indi-
     cates  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  data-
     base.  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  con-
     tains  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 informa-
     tion  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 tar-
          get  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 correspond-
          ing  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 tar-
          get  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  sec-
          tion 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 tar-
          get.  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 correspond-
          ing  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 justif-
          ication   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 con-
          verted 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  cal-
          ling  Tk_GetRelief and the result is stored in the tar-
          get.

     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 tar-
          get.  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  modify-
     ing  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 dif-
     ferent 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  con-
          sidered  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 typ-
          ically 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 tar-
          get location.  This flag provides a performance optimi-
          zation  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 mono-
     chrome 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  con-
     figuration  options for all the widget types.  When process-
     ing 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  infor-
     mation  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  informa-
     tion  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 con-
     tain either two or five values.  If the corresponding  entry
     in specs has type TK_CONFIG_SYNONYM, then the list will con-
     tain 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 con-
     figuration 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  struc-
     ture 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 data-
     base  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  argu-
     ment,  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  pro-
     cedure    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,  confi-
     guration  options,  cursor,  custom,  double, font, integer,
     join style, justify, millimeters, pixels,  relief,  synonym,
     uid
itcl2.2/html/tk4.2/ConfigWind.3.html100666 1751 0 30656 6423554656 15771 0ustar kunkeewheel tk4.2 C API - ConfigWind

tk4.2 C API - ConfigWind

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 confi-
     guration 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 CWBor-
                                                    derPixel,
                                                    indicating
                                                    which  fields
                                                    of  *valuePtr
                                                    or   *attsPtr
                                                    to use.

     XWindowChanges         *valuePtr     (in)      Points  to  a
                                                    structure
                                                    containing
                                                    new    values
                                                    for the  con-
                                                    figuration
                                                    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  (inte-
                                                    rior,     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     back-
                                                    ground     or
                                                    border  color
                                                    for window.

     Pixmap                 pixmap        (in)      New pixmap to
                                                    use for back-
                                                    ground     or
                                                    border     of
                                                    tkwin.  WARN-
                                                    ING:   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 cur-
                                                    sor;  it will
                                                    use  the cur-
                                                    sor  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 informa-
     tion in Tk's local structure for the window;  when the  win-
     dow  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
itcl2.2/html/tk4.2/CoordToWin.3.html100666 1751 0 4020 6423554656 15733 0ustar kunkeewheel tk4.2 C API - CoordToWin

tk4.2 C API - CoordToWin

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  identi-
                                   fies 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
itcl2.2/html/tk4.2/CrtErrHdlr.3.html100666 1751 0 22174 6423554656 15751 0ustar kunkeewheel tk4.2 C API - CrtErrHdlr

tk4.2 C API - CrtErrHdlr

NAME

     Tk_CreateErrorHandler, Tk_DeleteErrorHandler - handle X pro-
     tocol 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 documenta-
     tion  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 follow-
     ing 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  struc-
     ture  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 sub-
     sequent (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 pro-
     tocol     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
itcl2.2/html/tk4.2/CrtGenHdlr.3.html100666 1751 0 10153 6423554656 15724 0ustar kunkeewheel tk4.2 C API - CrtGenHdlr

tk4.2 C API - CrtGenHdlr

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  origi-
     nally 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  struc-
     ture  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 han-
     dled  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 esta-
     blished.

     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  argu-
     ments.      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
itcl2.2/html/tk4.2/CrtImgType.3.html100666 1751 0 24770 6423554656 15771 0ustar kunkeewheel tk4.2 C API - CrtImgType

tk4.2 C API - CrtImgType

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  pro-
     vided 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 sub-
     sections 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 com-
     mand.  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 possi-
     ble  for a single image to appear simultaneously in multiple
     widgets, or even multiple times in the same widget.   Furth-
     ermore,  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  usu-
     ally 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  pro-
     cedure.   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 *master-
     DataPtr, 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  pro-
     totype:
          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 pix-
     map  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  exam-
     ple, 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 proto-
     type:
          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
itcl2.2/html/tk4.2/CrtItemType.3.html100666 1751 0 73213 6423554656 16147 0ustar kunkeewheel tk4.2 C API - CrtItemType

tk4.2 C API - CrtItemType

NAME

     Tk_CreateItemType, Tk_GetItemTypes - define new kind of can-
     vas 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 struc-
     ture  must  be  in permanent memory (either statically allo-
     cated 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 stan-
     dard 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 pro-
     cedures 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 itemconfig-
     ure  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 can-
     vas widget, and itemPtr is a pointer to the item being  con-
     figured.   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 con-
     tains 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  pro-
     cedure  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 stan-
     dard  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 fol-
     lowing prototype:
          typedef void Tk_ItemDeleteProc(
            Tk_Canvas canvas,
            Tk_Item *itemPtr,
            Display *display);
     The canvas and itemPtr arguments have the usual  interpreta-
     tions,  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  ren-
     dered; 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  find-
     ing  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 dis-
     tance  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 relation-
     ship  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 mes-
     sage;  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 generat-
     ing 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  can-
     vas 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 dur-
     ing 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  char-
     acter 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  proto-
     type:
          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
itcl2.2/html/tk4.2/CrtPhImgFmt.3.html100666 1751 0 30172 6423554656 16057 0ustar kunkeewheel tk4.2 C API - CrtPhImgFmt

tk4.2 C API - CrtPhImgFmt

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 sup-
     port 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 con-
     tains 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 pro-
     cedures.   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 pro-
     cedure, 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 format-
     String 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  pro-
     cedure 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 report-
     ing 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  coor-
     dinates  (destX,destY) using the Tk_PhotoPutBlock procedure.
     The return value is a standard Tcl return value.

STRINGREADPROC

     formatPtr->stringReadProc provides the  address  of  a  pro-
     cedure  for  Tk  to  call  to read data from a string into a
     photo image.  formatPtr->stringReadProc must match the  fol-
     lowing 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 report-
     ing 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 -for-
     mat 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  stan-
     dard Tcl return value.

STRINGWRITEPROC

     formatPtr->stringWriteProc provides the address  of  a  pro-
     cedure  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 appropri-
     ate, 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
itcl2.2/html/tk4.2/CrtSelHdlr.3.html100666 1751 0 17152 6423554656 15744 0ustar kunkeewheel tk4.2 C API - CrtSelHdlr

tk4.2 C API - CrtSelHdlr

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 informa-
                                               tion.

     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     com-
                                               mands.

     Tk_SelectionProc   *proc        (in)      Procedure       to
                                               invoke    whenever
                                               the  selection  is
                                               owned by tkwin and
                                               the selection con-
                                               tents          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, client-
     Data points to  a  data  structure  containing  application-
     specific  information  that is needed to retrieve the selec-
     tion.  Offset specifies an offset position into  the  selec-
     tion,  buffer specifies a location at which to copy informa-
     tion 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 addi-
     tional 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 argu-
     ment  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  con-
     tents 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
itcl2.2/html/tk4.2/CrtWindow.3.html100666 1751 0 20643 6423554656 15655 0ustar kunkeewheel tk4.2 C API - CrtWindow

tk4.2 C API - CrtWindow

NAME

     Tk_CreateWindow, Tk_CreateWindowFromPath,  Tk_DestroyWindow,
     Tk_MakeWindowExist - create or delete window

SYNOPSIS

     #include <tk.h>

     Tk_Window
     Tk_CreateWindow(interp, parent, name, topLevScreen)

     Tk_Window
     Tk_CreateWindowFromPath(interp, tkwin, pathName, topLevScreen)

     Tk_DestroyWindow(tkwin)

     Tk_MakeWindowExist(tkwin)

ARGUMENTS

     Tcl_Interp   *interp         (out)     Tcl  interpreter   to
                                            use for error report-
                                            ing.   If  no   error
                                            occurs,  then *interp
                                            isn't modified.

     Tk_Window    parent          (in)      Token for the  window
                                            that  is  to serve as
                                            the logical parent of
                                            the new window.

     char         *name           (in)      Name to use for  this
                                            window.     Must   be
                                            unique   among    all
                                            children  of the same
                                            parent.

     char         *topLevScreen   (in)      Has  same  format  as
                                            screenName.  If NULL,
                                            then  new  window  is
                                            created  as an inter-
                                            nal window.  If  non-
                                            NULL,  new  window is
                                            created  as  a   top-
                                            level    window    on
                                            screen  topLevScreen.
                                            If topLevScreen is an
                                            empty  string  (``'')
                                            then  new  window  is
                                            created as  top-level
                                            window   of  parent's
                                            screen.

     Tk_Window    tkwin           (in)      Token for window.

     char         *pathName       (in)      Name of  new  window,
                                            specified   as   path
                                            name within  applica-
                                            tion (e.g. .a.b.c).

DESCRIPTION

     The procedures Tk_CreateWindow  and  Tk_CreateWindowFromPath  |
     are  used to create new windows for use in Tk-based applica-  |
     tions.  Each of the procedures returns a token that  can  be  |
     used  to  manipulate  the  window  in  other calls to the Tk  |
     library.  If the window couldn't  be  created  successfully,  |
     then NULL is returned and interp->result is modified to hold  |
     an error message.                                             |

     Tk supports two different kinds of windows:   internal  win-  |
     dows  and top-level windows.  An internal window is an inte-
     rior window of a Tk application, such as a scrollbar or menu
     bar or button.  A top-level window is one that is created as
     a child of a screen's root window, rather than as  an  inte-
     rior  window,  but  which is logically part of some existing
     main window.  Examples of top-level windows are pop-up menus
     and dialog boxes.

     New windows may be created by calling  Tk_CreateWindow.   If
     the  topLevScreen argument is NULL, then the new window will
     be an internal window.  If topLevScreen  is  non-NULL,  then
     the  new  window  will  be  a top-level window: topLevScreen
     indicates the name of a screen and the new  window  will  be
     created  as  a child of the root window of topLevScreen.  In
     either case Tk will consider the new window to be the  logi-
     cal  child  of  parent:   the  new  window's  path name will
     reflect this fact, options may be specified for the new win-
     dow  under  this assumption, and so on.  The only difference
     is that new X window for a top-level window will  not  be  a
     child of parent's X window.  For example, a pull-down menu's
     parent would be the button-like window used  to  invoke  it,
     which  would  in  turn be a child of the menu bar window.  A
     dialog box might have the application's main window  as  its
     parent.

     Tk_CreateWindowFromPath offers an alternate way of  specify-
     ing  new windows.  In Tk_CreateWindowFromPath the new window
     is specified with a token  for  any  window  in  the  target
     application  (tkwin),  plus  a path name for the new window.
     It produces the same effect as  Tk_CreateWindow  and  allows
     both top-level and internal windows to be created, depending
     on   the   value   of    topLevScreen.     In    calls    to
     Tk_CreateWindowFromPath, as in calls to Tk_CreateWindow, the
     parent of the new window must exist at the time of the call,
     but the new window must not already exist.

     The window creation procedures don't actually issue the com-
     mand  to X to create a window.  Instead, they create a local
     data structure associated with  the  window  and  defer  the
     creation  of  the  X  window.   The  window will actually be
     created by the first call to Tk_MapWindow.  Deferred  window
     creation  allows  various aspects of the window (such as its
     size, background color, etc.) to be modified after its crea-
     tion  without  incurring any overhead in the X server.  When
     the window is finally mapped all of  the  window  attributes
     can be set while creating the window.

     The value returned by a window-creation procedure is not the
     X  token  for  the  window (it can't be, since X hasn't been
     asked to create the window yet).  Instead, it is a token for
     Tk's  local  data  structure for the window.  Most of the Tk
     library procedures take  Tk_Window  tokens,  rather  than  X
     identifiers.    The   actual  X  window  identifier  can  be
     retrieved  from  the  local   data   structure   using   the
     Tk_WindowId macro;  see the manual entry for Tk_WindowId for
     details.

     Tk_DestroyWindow deletes a window and all  the  data  struc-
     tures  associated  with  it,  including  any  event handlers
     created   with    Tk_CreateEventHandler.     In    addition,
     Tk_DestroyWindow  will  delete  any children of tkwin recur-
     sively (where children are defined in the Tk sense, consist-
     ing  of  all windows that were created with the given window
     as parent).  If tkwin was created by Tk_CreateInternalWindow
     then event handlers interested in destroy events are invoked
     immediately.  If tkwin is a top-level or main  window,  then
     the  event  handlers will be invoked later, after X has seen
     the request and returned an event for it.

     If a window has been created but hasn't been mapped, so no X
     window exists, it is possible to force the creation of the X
     window by calling Tk_MakeWindowExist.  This procedure issues
     the X commands to instantiate the window given by tkwin.

KEYWORDS

     create, deferred creation, destroy, display,  internal  win-
     dow, screen, top-level window, window
itcl2.2/html/tk4.2/DeleteImg.3.html100666 1751 0 2140 6423554657 15545 0ustar kunkeewheel tk4.2 C API - DeleteImg

tk4.2 C API - DeleteImg

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
itcl2.2/html/tk4.2/DrawFocHlt.3.html100666 1751 0 3373 6423554657 15714 0ustar kunkeewheel tk4.2 C API - DrawFocHlt

tk4.2 C API - DrawFocHlt

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  dou-
                                       ble 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
itcl2.2/html/tk4.2/EventHndlr.3.html100666 1751 0 10272 6423554657 16004 0ustar kunkeewheel tk4.2 C API - EventHndlr

tk4.2 C API - EventHndlr

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     But-
                                            tonPressMask)     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  struc-
     ture  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 client-
     Data  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
itcl2.2/html/tk4.2/FindPhoto.3.html100666 1751 0 32565 6423554657 15636 0ustar kunkeewheel tk4.2 C API - FindPhoto

tk4.2 C API - 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  iden-
     tify  a particular photo image to the other procedures.  The
     parameter is the name of the image, that is, the name speci-
     fied  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  coordi-
     nates  (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  pixel-
     Size field specifies the address difference between two hor-
     izontally 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  coordi-
     nates  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 subsam-
     pleX 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 sub-
     sequent 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
itcl2.2/html/tk4.2/FreeXId.3.html100666 1751 0 4616 6423554657 15206 0ustar kunkeewheel tk4.2 C API - FreeXId

tk4.2 C API - 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, cur-
                                    sor,  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 iden-
     tifiers  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
itcl2.2/html/tk4.2/GeomReq.3.html100666 1751 0 7116 6423554657 15255 0ustar kunkeewheel tk4.2 C API - GeomReq

tk4.2 C API - GeomReq

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  Con-
     figureNotify  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  informa-
     tion 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 outer-
     most 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
itcl2.2/html/tk4.2/GetAnchor.3.html100666 1751 0 6344 6423554657 15572 0ustar kunkeewheel tk4.2 C API - GetAnchor

tk4.2 C API - 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
itcl2.2/html/tk4.2/GetBitmap.3.html100666 1751 0 25155 6423554657 15615 0ustar kunkeewheel tk4.2 C API - GetBitmap

tk4.2 C API - GetBitmap

NAME

     Tk_GetBitmap,       Tk_DefineBitmap,        Tk_NameOfBitmap,
     Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData - main-
     tain 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  for-
                                           mat.  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 bit-
                                           map was allocated.

     Pixmap          bitmap      (in)      Identifier for a  bit-
                                           map    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  possi-
     ble,  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 con-
                         taining  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  pro-
     cedures 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  argu-
     ment  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 dif-
     ferent file.

KEYWORDS

     bitmap, pixmap
itcl2.2/html/tk4.2/GetCapStyl.3.html100666 1751 0 5436 6423554657 15740 0ustar kunkeewheel tk4.2 C API - GetCapStyl

tk4.2 C API - GetCapStyl

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 correspond-
     ing to string.  This will be one of the values CapButt, Cap-
     Projecting, 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
itcl2.2/html/tk4.2/GetClrmap.3.html100666 1751 0 7351 6423554657 15575 0ustar kunkeewheel tk4.2 C API - GetClrmap

tk4.2 C API - GetClrmap

NAME

     Tk_GetColormap, Tk_FreeColormap - allocate and  free  color-
     maps

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 win-
     dow with the same screen and visual as tkwin, and the color-
     map  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 refer-
     ence 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 color-
     maps  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
itcl2.2/html/tk4.2/GetColor.3.html100666 1751 0 20154 6423554657 15451 0ustar kunkeewheel tk4.2 C API - GetColor

tk4.2 C API - 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 infor-
                                        mation.   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  allo-
     cating  the  desired  color, then it returns a pointer to an
     XColor structure;  the structure indicates the exact  inten-
     sities  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  pro-
     cedures 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 per-
     sist 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
itcl2.2/html/tk4.2/GetCursor.3.html100666 1751 0 27067 6423554657 15662 0ustar kunkeewheel tk4.2 C API - GetCursor

tk4.2 C API - 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  bit-
                                           map,  in standard bit-
                                           map 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 cur-
                                           sor 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 correspond-
     ing 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 Sys-
          tem'' by Scheifler & Gettys has  illustrations  showing
          what  each of these cursors looks like.  If fgColor and
          bgColor are both specified, they  give  the  foreground