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
          and background colors to use for the cursor (any of the
          forms acceptable to Tk_GetColor may be used).  If  only
          fgColor  is specified, then there will be no background
          color:  the background  will  be  transparent.   If  no
          colors  are  specified,  then the cursor will use black
          for its foreground color and white for  its  background
          color.

          The Macintosh version of Tk also supports all of the  X
          cursors.   Tk  on  the  Mac will also accept any of the
          standard Mac cursors including ibeam, crosshair, watch,
          plus,  and  arrow.  In addition, Tk will load Macintosh
          cursor resources of the types  crsr  (color)  and  CURS
          (black  and  white) by the name of the of the resource.
          The application and  all  its  open  dynamic  library's
          resource  files  will be searched for the named cursor.
          If there are conflicts color  cursors  will  always  be
          loaded in preference to black and white cursors.

     @sourceName maskName fgColor bgColor
          In this form, sourceName and maskName are the names  of
          files  describing  bitmaps for the cursor's source bits
          and mask.  Each file must be in  standard  X11  or  X10
          bitmap format.  FgColor and bgColor indicate the colors
          to use for the cursor, in any of the  forms  acceptable
          to Tk_GetColor.  This form of the command will not work
          on Macintosh or Windows computers.

     @sourceName fgColor
          This form is similar to the one above, except that  the
          source  is  used  as  mask  also.   This means that the
          cursor's background is transparent.  This form  of  the
          command  will  not work on Macintosh or Windows comput-
          ers.

     Tk_GetCursorFromData allows cursors to be created  from  in-
     memory  descriptions  of  their  source  and  mask  bitmaps.
     Source points to  standard  bitmap  data  for  the  cursor's
     source  bits,  and  mask  points  to  standard  bitmap  data
     describing which pixels of source are to be drawn and  which
     are to be considered transparent.  Width and height give the
     dimensions of the cursor, xHot and yHot indicate  the  loca-
     tion  of  the  cursor's hot-spot (the point that is reported
     when an event occurs), and fg and bg describe  the  cursor's
     foreground and background colors textually (any of the forms
     suitable for Tk_GetColor may be used).  Typically, the argu-
     ments  to  Tk_GetCursorFromData  are  created by including a
     cursor file directly into the source code for a program,  as
     in the following example:
          Tk_Cursor cursor;
          #include "source.cursor"
          #include "mask.cursor"
          cursor = Tk_GetCursorFromData(interp, tkwin, source_bits,
            mask_bits, source_width, source_height, source_x_hot,
            source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue"));

     Under     normal      conditions,      Tk_GetCursor      and
     Tk_GetCursorFromData  will  return  an  identifier  for  the
     requested cursor.  If an error occurs in creating  the  cur-
     sor, such as when nameId refers to a non-existent file, then
     None is returned and an error  message  will  be  stored  in
     interp->result.
     Tk_GetCursor and Tk_GetCursorFromData maintain a database of
     all  the  cursors  they  have created.  Whenever possible, a
     call to Tk_GetCursor or Tk_GetCursorFromData will return  an
     existing  cursor  rather  than  creating  a  new  one.  This
     approach can substantially reduce server overhead, so the Tk
     procedures  should  generally  be used in preference to Xlib
     procedures like  XCreateFontCursor  or  XCreatePixmapCursor,
     which create a new cursor on each call.

     The procedure Tk_NameOfCursor  is  roughly  the  inverse  of
     Tk_GetCursor.    If  its  cursor  argument  was  created  by
     Tk_GetCursor, then the return value is the  nameId  argument
     that  was  passed  to Tk_GetCursor to create the cursor.  If
     cursor was created by a call to Tk_GetCursorFromData, or  by
     any  other mechanism, then the return value is a hexadecimal
     string giving the X identifier for the cursor.   Note:   the
     string  returned  by  Tk_NameOfCursor  is only guaranteed to
     persist until the next call to Tk_NameOfCursor.  Also,  this
     call   is  not  portable  except  for  cursors  returned  by
     Tk_GetCursor.

     When    a    cursor    returned    by    Tk_GetCursor     or
     Tk_GetCursorFromData  is  no  longer  needed,  Tk_FreeCursor
     should be called to release it.  There should be exactly one
     call  to  Tk_FreeCursor  for  each  call  to Tk_GetCursor or
     Tk_GetCursorFromData.  When a cursor is  no  longer  in  use
     anywhere  (i.e.  it  has  been freed as many times as it has
     been gotten) Tk_FreeCursor will release it to the  X  server
     and remove it from the database.

BUGS

     In determining whether an existing cursor  can  be  used  to
     satisfy a new request, Tk_GetCursor and Tk_GetCursorFromData
     consider only the immediate values of their arguments.   For
     example,  when  a  file  name  is  passed  to  Tk_GetCursor,
     Tk_GetCursor will assume it is safe to  re-use  an  existing
     cursor  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 different file.  Similarly,  Tk_GetCursorFromData
     assumes  that if the same source pointer is used in two dif-
     ferent calls, then the pointers refer to the same data;   it
     does  not  check  to  see  if  the  actual  data values have
     changed.

KEYWORDS

     cursor
itcl2.2/html/tk4.2/GetFontStr.3.html100666 1751 0 10022 6423554660 15755 0ustar kunkeewheel tk4.2 C API - GetFontStr

tk4.2 C API - GetFontStr

NAME

     Tk_GetFontStruct, Tk_NameOfFontStruct,  Tk_FreeFontStruct  -
     maintain database of fonts

SYNOPSIS

     #include <tk.h>

     XFontStruct *
     Tk_GetFontStruct(interp, tkwin, nameId)

     char *
     Tk_NameOfFontStruct(fontStructPtr)

     Tk_FreeFontStruct(fontStructPtr)

ARGUMENTS

     Tcl_Interp    *interp          (in)      Interpreter to  use
                                              for  error  report-
                                              ing.

     Tk_Window     tkwin            (in)      Token for window in
                                              which  font will be
                                              used.

     Tk_Uid        nameId           (in)      Name   of   desired
                                              font.

     XFontStruct   *fontStructPtr   (in)      Font  structure  to
                                              return  name for or
                                              delete.

DESCRIPTION

     Tk_GetFont loads the font indicated by nameId and returns  a
     pointer to information about the font.  The pointer returned
     by Tk_GetFont will remain valid until Tk_FreeFont is  called
     to release it.  NameId can be either a font name or pattern;
     any value that could be  passed  to  XLoadQueryFont  may  be
     passed   to   Tk_GetFont.   If  Tk_GetFont  is  unsuccessful
     (because, for example, there is  no  font  corresponding  to
     nameId)  then it returns NULL and stores an error message in
     interp->result.

     Tk_GetFont maintains a database of all fonts  it  has  allo-
     cated.  If the same nameId is requested multiple times (e.g.
     by different windows or for different purposes), then  addi-
     tional  calls  for  the  same  nameId  will  be handled very
     quickly, without involving the X server.  For  this  reason,
     it  is  generally  better  to  use  Tk_GetFont in place of X
     library procedures like XLoadQueryFont.

     The procedure Tk_NameOfFontStruct is roughly the inverse  of
     Tk_GetFontStruct.  If its fontStructPtr argument was created
     by Tk_GetFontStruct, then the return  value  is  the  nameId
     argument  that  was passed to Tk_GetFontStruct to create the
     font.  If  fontStructPtr  was  not  created  by  a  call  to
     Tk_GetFontStruct,  then  the  return  value is a hexadecimal
     string giving the X  identifier  for  the  associated  font.
     Note:   the  string  returned by Tk_NameOfFontStruct is only
     guaranteed   to   persist   until   the   next    call    to
     Tk_NameOfFontStruct.

     When a font returned by  Tk_GetFont  is  no  longer  needed,
     Tk_FreeFont should be called to release it.  There should be
     exactly one call to Tk_FreeFont for each call to Tk_GetFont.
     When  a  font is no longer in use anywhere (i.e. it has been
     freed as many times as it has been gotten) Tk_FreeFont  will
     release it to the X server and delete it from the database.

KEYWORDS

     font
itcl2.2/html/tk4.2/GetGC.3.html100666 1751 0 7773 6423554660 14652 0ustar kunkeewheel tk4.2 C API - GetGC

tk4.2 C API - GetGC

NAME

     Tk_GetGC, Tk_FreeGC - maintain database of read-only  graph-
     ics contexts

SYNOPSIS

     #include <tk.h>

     GC
     Tk_GetGC(tkwin, valueMask, valuePtr)

     Tk_FreeGC(display, gc)

ARGUMENTS

     Tk_Window       tkwin       (in)      Token  for  window  in
                                           which   the   graphics
                                           context will be used.

     unsigned long   valueMask   (in)      Mask of bits (such  as
                                           GCForeground        or
                                           GCStipple)  indicating
                                           which     fields    of
                                           *valuePtr are valid.

     XGCValues       *valuePtr   (in)      Pointer  to  structure
                                           describing the desired
                                           values for the  graph-
                                           ics context.

     Display         *display    (in)      Display for  which  gc
                                           was allocated.

     GC              gc          (in)      X    identifier    for
                                           graphics  context that
                                           is no  longer  needed.
                                           Must  have  been allo-
                                           cated by Tk_GetGC.

DESCRIPTION

     Tk_GetGC and Tk_FreeGC manage a collection of graphics  con-
     texts  being  used  by an application.  The procedures allow
     graphics contexts to be shared, thereby avoiding the  server
     overhead  that  would  be  incurred  if  a  separate GC were
     created for each use.  Tk_GetGC takes  arguments  describing
     the desired graphics context and returns an X identifier for
     a GC that fits the description.  The graphics  context  that
     is  returned  will  have default values in all of the fields
     not specified explicitly by valueMask and valuePtr.

     Tk_GetGC maintains a database of all the  graphics  contexts
     it  has created.  Whenever possible, a call to Tk_GetGC will
     return an existing graphics context rather than  creating  a
     new  one.   This  approach  can  substantially reduce server
     overhead, so Tk_GetGC should generally be used in preference
     to  the Xlib procedure XCreateGC, which creates a new graph-
     ics context on each call.

     Since the return values  of  Tk_GetGC  are  shared,  callers
     should  never  modify  the  graphics  contexts  returned  by
     Tk_GetGC.  If a graphics context must  be  modified  dynami-
     cally,  then  it  should  be  created  by  calling XCreateGC
     instead of Tk_GetGC.

     When a graphics  context  is  no  longer  needed,  Tk_FreeGC
     should be called to release it.  There should be exactly one
     call to Tk_FreeGC for each call to Tk_GetGC.  When a  graph-
     ics  context  is no longer in use anywhere (i.e. it has been
     freed as many times as it has been  gotten)  Tk_FreeGC  will
     release it to the X server and delete it from the database.

KEYWORDS

     graphics context
itcl2.2/html/tk4.2/GetImage.3.html100666 1751 0 24251 6423554660 15411 0ustar kunkeewheel tk4.2 C API - GetImage

tk4.2 C API - GetImage

NAME

     Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage  -
     use an image in a widget

SYNOPSIS

     #include <tk.h>

     Tk_Image
     Tk_GetImage(interp, tkwin, name, changeProc, clientData)

     Tk_RedrawImage(image, imageX, imageY, width, height, drawable, drawableX, drawableY)

     Tk_SizeOfImage(image, widthPtr, heightPtr)

     Tk_FreeImage(image)

ARGUMENTS

     Tcl_Interp            *interp       (in)      Place to leave
                                                   error message.

     Tk_Window             tkwin         (in)      Window      in
                                                   which    image
                                                   will be used.

     char                  *name         (in)      Name of image.

     Tk_ImageChangedProc   *changeProc   (in)      Procedure  for
                                                   Tk  to  invoke
                                                   whenever image
                                                   content     or
                                                   size changes.

     ClientData            clientData    (in)      One-word value
                                                   for Tk to pass
                                                   to changeProc.

     Tk_Image              image         (in)      Token      for
                                                   image
                                                   instance;
                                                   must have been
                                                   returned by  a
                                                   previous  call
                                                   to
                                                   Tk_GetImage.

     int                   imageX        (in)      X-coordinate
                                                   of  upper-left
                                                   corner      of
                                                   region      of
                                                   image       to
                                                   redisplay
                                                   (measured   in
                                                   pixels    from
                                                   the    image's
                                                   upper-left
                                                   corner).

     int                   imageY        (in)      Y-coordinate
                                                   of  upper-left
                                                   corner      of
                                                   region      of
                                                   image       to
                                                   redisplay
                                                   (measured   in
                                                   pixels    from
                                                   the    image's
                                                   upper-left
                                                   corner).

     int                   width         ((in))    Width       of
                                                   region      of
                                                   image       to
                                                   redisplay.

     int                   height        ((in))    Height      of
                                                   region      of
                                                   image       to
                                                   redisplay.

     Drawable              drawable      (in)      Where       to
                                                   display image.
                                                   Must either be
                                                   window  speci-
                                                   fied        to
                                                   Tk_GetImage or
                                                   a pixmap  com-
                                                   patible   with
                                                   that window.

     int                   drawableX     (in)      Where       to
                                                   display  image
                                                   in   drawable:
                                                   this   is  the
                                                   x-coordinate
                                                   in    drawable
                                                   where       x-
                                                   coordinate
                                                   imageX of  the
                                                   image   should
                                                   be displayed.

     int                   drawableY     (in)      Where       to
                                                   display  image
                                                   in   drawable:
                                                   this   is  the
                                                   y-coordinate
                                                   in    drawable
                                                   where       y-
                                                   coordinate
                                                   imageY of  the
                                                   image   should
                                                   be displayed.

     int                   widthPtr      (out)     Store width of
                                                   image (in pix-
                                                   els) here.

     int                   heightPtr     (out)     Store   height
                                                   of  image  (in
                                                   pixels) here.

DESCRIPTION

     These procedures are invoked by widgets that wish to display
     images.   Tk_GetImage  is  invoked by a widget when it first
     decides to display an image.  name gives  the  name  of  the
     desired  image  and  tkwin  identifies  the window where the
     image will be displayed.  Tk_GetImage looks up the image  in
     the  table  of existing images and returns a token for a new
     instance of the image.  If  the  image  doesn't  exist  then
     Tk_GetImage  returns  NULL  and  leaves  an error message in
     interp->result.

     When a widget wishes to actually display an  image  it  must
     call  Tk_RedrawWidget,  identifying  the  image  (image),  a
     region within the image to redisplay (imageX, imageY, width,
     and  height),  and  a  place to display the image (drawable,
     drawableX,  and  drawableY).   Tk  will  then   invoke   the
     appropriate  image manager, which will display the requested
     portion of the image before returning.

     A widget can find out the dimensions of an image by  calling
     Tk_SizeOfImage:   the width and height will be stored in the
     locations given by widthPtr and heightPtr, respectively.

     When a widget is finished with an image (e.g., the widget is
     being  deleted  or  it  is  going  to  use a different image
     instead of the current one), it must  call  Tk_FreeImage  to
     release  the  image instance.  The widget should never again
     use the image token after passing it to Tk_FreeImage.  There
     must  be  exactly  one call to Tk_FreeImage for each call to
     Tk_GetImage.

     If the contents or size of an image changes, then any  widg-
     ets  using the image will need to find out about the changes
     so that they can redisplay themselves.  The  changeProc  and
     clientData  arguments  to Tk_GetImage are used for this pur-
     pose.  changeProc will be called by  Tk  whenever  a  change
     occurs in the image;  it must match the following prototype:
          typedef void Tk_ImageChangedProc(
            ClientData clientData,
            int x,
            int y,
            int width,
            int height,
            int imageWidth,
            int imageHeight);
     The clientData argument to changeProc is  the  same  as  the
     clientData argument to Tk_GetImage.  It is usually a pointer
     to the widget record for  the  widget  or  some  other  data
     structure managed by the widget.  The arguments x, y, width,
     and height identify a region within the image that  must  be
     redisplayed;  they are specified in pixels measured from the
     upper-left corner of the image.   The  arguments  imageWidth
     and imageHeight give the image's (new) size.

SEE ALSO

     Tk_CreateImageType

KEYWORDS

     images, redisplay
itcl2.2/html/tk4.2/GetJoinStl.3.html100666 1751 0 5676 6423554660 15743 0ustar kunkeewheel tk4.2 C API - GetJoinStl

tk4.2 C API - GetJoinStl

NAME

     Tk_GetJoinStyle,  Tk_NameOfJoinStyle  -  translate   between
     strings and join styles

SYNOPSIS

     #include <tk.h>

     int
     Tk_GetJoinStyle(interp, string, joinPtr)

     char *
     Tk_NameOfJoinStyle(join)

ARGUMENTS

     Tcl_Interp   *interp    (in)      Interpreter  to  use   for
                                       error reporting.

     char         *string    (in)      String containing name  of
                                       join    style:    one   of
                                       ``bevel'',  ``miter'',  or
                                       ``round''.

     int          *joinPtr   (out)     Pointer  to  location   in
                                       which   to  store  X  join
                                       style   corresponding   to
                                       string.

     int          join       (in)      Join style: one  of  Join-
                                       Bevel,   JoinMiter,  Join-
                                       Round.

DESCRIPTION

     Tk_GetJoinStyle  places  in  *joinPtr  the  X   join   style
     corresponding  to  string,  which  will be one of JoinBevel,
     JoinMiter, or JoinRound.  Join styles are typically used  in
     X  graphics  contexts to indicate how adjacent line segments
     should be joined together.   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 join
     style or an abbreviation of one  of  these  names,  then  an
     error  message  is  stored  in  interp->result, TCL_ERROR is
     returned, and *joinPtr is unmodified.

     Tk_NameOfJoinStyle    is    the    logical    inverse     of
     Tk_GetJoinStyle.   Given  a  join style such as JoinBevel it
     returns a statically-allocated string corresponding to join.
     If  join  isn't  a  legal  join  style,  then ``unknown join
     style'' is returned.

KEYWORDS

     bevel, join style, miter, round
itcl2.2/html/tk4.2/GetJustify.3.html100666 1751 0 6251 6423554660 16004 0ustar kunkeewheel tk4.2 C API - GetJustify

tk4.2 C API - GetJustify

NAME

     Tk_GetJustify, Tk_NameOfJustify - translate between  strings
     and justification styles

SYNOPSIS

     #include <tk.h>

     Tk_Justify
     Tk_GetJustify(interp, string, justifyPtr)

     char *
     Tk_NameOfJustify(justify)

ARGUMENTS

     Tcl_Interp   *interp       (in)      Interpreter to use  for
                                          error reporting.

     char         *string       (in)      String containing  name
                                          of  justification style
                                          (``left'',   ``right'',
                                          or ``center'').

     int          *justifyPtr   (out)     Pointer to location  in
                                          which  to store justify
                                          value corresponding  to
                                          string.

     Tk_Justify   justify       (in)      Justification     style
                                          (one   of   the  values
                                          listed below).

DESCRIPTION

     Tk_GetJustify  places  in  *justifyPtr  the  justify   value
     corresponding to string.  This value will be one of the fol-
     lowing:

     TK_JUSTIFY_LEFT
          Means that the text on each line should  start  at  the
          left edge of the line;  as a result, the right edges of
          lines may be ragged.

     TK_JUSTIFY_RIGHT
          Means that the text on each  line  should  end  at  the
          right edge of the line;  as a result, the left edges of
          lines may be ragged.

     TK_JUSTIFY_CENTER
          Means that the text on each line  should  be  centered;
          as a result, both the left and right edges of lines may
          be ragged.

     Under normal circumstances the return value  is  TCL_OK  and
     interp is unused.  If string doesn't contain a valid justif-
     ication style or an abbreviation of one of these names, then
     an  error  message is stored in interp->result, TCL_ERROR is
     returned, and *justifyPtr is unmodified.

     Tk_NameOfJustify is the logical  inverse  of  Tk_GetJustify.
     Given  a  justify  value  it  returns a statically-allocated
     string corresponding to justify.  If justify isn't  a  legal
     justify  value,  then  ``unknown  justification  style''  is
     returned.

KEYWORDS

     center, fill, justification, string
itcl2.2/html/tk4.2/GetOption.3.html100666 1751 0 3335 6423554660 15617 0ustar kunkeewheel tk4.2 C API - GetOption

tk4.2 C API - GetOption

NAME

     Tk_GetOption - retrieve an option from the option database

SYNOPSIS

     #include <tk.h>

     Tk_Uid
     Tk_GetOption(tkwin, name, class)

ARGUMENTS

     Tk_Window   tkwin    (in)      Token for window.

     char        *name    (in)      Name of desired option.

     char        *class   (in)      Class  of   desired   option.
                                    Null  means there is no class
                                    for this option;   do  lookup
                                    based on name only.

DESCRIPTION

     This procedure is invoked to retrieve  an  option  from  the
     database  associated  with tkwin's main window.  If there is
     an option for tkwin that matches the given  name  or  class,
     then  it  is  returned in the form of a Tk_Uid.  If multiple
     options match name and class, then the highest-priority  one
     is returned.  If no option matches, then NULL is returned.

     Tk_GetOption caches options related to tkwin so that succes-
     sive calls for the same tkwin will execute much more quickly
     than successive calls for different windows.

KEYWORDS

     class, name, option, retrieve
itcl2.2/html/tk4.2/GetPixels.3.html100666 1751 0 6600 6423554660 15611 0ustar kunkeewheel tk4.2 C API - GetPixels

tk4.2 C API - GetPixels

NAME

     Tk_GetPixels, Tk_GetScreenMM - translate between strings and
     screen units

SYNOPSIS

     #include <tk.h>

     int
     Tk_GetPixels(interp, tkwin, string, intPtr)

     int
     Tk_GetScreenMM(interp, tkwin, string, doublePtr)

ARGUMENTS

     Tcl_Interp   *interp    (in)      Interpreter  to  use   for
                                       error reporting.

     Tk_Window    tkwin      (in)      Window    whose     screen
                                       geometry   determines  the
                                       conversion  between  abso-
                                       lute units and pixels.

     char         *string    (in)      String  that  specifies  a
                                       distance on the screen.

     int          *intPtr    (out)     Pointer  to  location   in
                                       which  to  store converted
                                       distance in pixels.

     double       *doublePtr (out)     Pointer  to  location   in
                                       which  to  store converted
                                       distance in millimeters.

DESCRIPTION

     These two procedures take as  argument  a  specification  of
     distance  on the screen (string) and compute the correspond-
     ing distance either in integer pixels or floating-point mil-
     limeters.   In  either  case, string specifies a screen dis-
     tance as a floating-point number followed by one of the fol-
     lowing characters that indicates units:

     <none>
          The number specifies a distance in pixels.

     c    The number specifies a distance in centimeters  on  the
          screen.

     i    The number  specifies  a  distance  in  inches  on  the
          screen.

     m    The number specifies a distance in millimeters  on  the
          screen.

     p    The number specifies a  distance  in  printer's  points
          (1/72 inch) on the screen.

     Tk_GetPixels converts string to the nearest even  number  of
     pixels  and  stores  that  value at *intPtr.  Tk_GetScreenMM
     converts  string  to  millimeters  and  stores  the  double-
     precision floating-point result at *doublePtr.

     Both procedures return TCL_OK  under  normal  circumstances.
     If  an  error occurs (e.g. string contains a number followed
     by a character that  isn't  one  of  the  ones  above)  then
     TCL_ERROR  is  returned  and  an  error  message  is left in
     interp->result.

KEYWORDS

     centimeters, convert, inches, millimeters,  pixels,  points,
     screen units
itcl2.2/html/tk4.2/GetPixmap.3.html100666 1751 0 4345 6423554660 15607 0ustar kunkeewheel tk4.2 C API - GetPixmap

tk4.2 C API - GetPixmap

NAME

     Tk_GetPixmap, Tk_FreePixmap - allocate and free pixmaps

SYNOPSIS

     #include <tk.h>

     Pixmap
     Tk_GetPixmap(display, d, width, height, depth)

     Tk_FreePixmap(display, pixmap)

ARGUMENTS

     Display    *display    (in)      X display for the pixmap.

     Drawable   d           (in)      Pixmap or window where  the
                                      new pixmap will be used for
                                      drawing.

     int        width       (in)      Width of pixmap.

     int        height      (in)      Height of pixmap.

     int        depth       (in)      Number of bits per pixel in
                                      pixmap.

     Pixmap     pixmap      (in)      Pixmap to destroy.

DESCRIPTION

     These  procedures  are  identical  to  the  Xlib  procedures
     XCreatePixmap  and  XFreePixmap, except that they have extra
     code to manage X resource identifiers  so  that  identifiers
     for  deleted  pixmaps  can  be  reused in the future.  It is
     important for Tk applications to use these procedures rather
     than  XCreatePixmap and XFreePixmap;  otherwise long-running
     applications may run out of resource identifiers.

     Tk_GetPixmap creates a pixmap suitable  for  drawing  in  d,
     with  dimensions  given  by  width,  height,  and depth, and
     returns its identifier.  Tk_FreePixmap destroys  the  pixmap
     given  by pixmap and makes its resource identifier available
     for reuse.

KEYWORDS

     pixmap, resource identifier
itcl2.2/html/tk4.2/GetRelief.3.html100666 1751 0 5547 6423554660 15564 0ustar kunkeewheel tk4.2 C API - GetRelief

tk4.2 C API - GetRelief

NAME

     Tk_GetRelief, Tk_NameOfRelief -  translate  between  strings
     and relief values

SYNOPSIS

     #include <tk.h>

     int
     Tk_GetRelief(interp, name, reliefPtr)

     char *
     Tk_NameOfRelief(relief)

ARGUMENTS

     Tcl_Interp   *interp      (in)      Interpreter to  use  for
                                         error reporting.

     char         *name        (in)      String containing relief
                                         name  (one  of ``flat'',
                                         ``groove'',  ``raised'',
                                         ``ridge'',            or
                                         ``sunken'').

     int          *reliefPtr   (out)     Pointer to  location  in
                                         which  to  store  relief
                                         value  corresponding  to
                                         name.

     int          relief       (in)      Relief  value  (one   of
                                         TK_RELIEF_FLAT,
                                         TK_RELIEF_RAISED,
                                         TK_RELIEF_SUNKEN,
                                         TK_RELIEF_GROOVE,     or
                                         TK_RELIEF_RIDGE).

DESCRIPTION

     Tk_GetRelief  places  in   *reliefPtr   the   relief   value
     corresponding   to   name.    This  value  will  be  one  of
     TK_RELIEF_FLAT,     TK_RELIEF_RAISED,      TK_RELIEF_SUNKEN,
     TK_RELIEF_GROOVE,  or  TK_RELIEF_RIDGE.   Under  normal cir-
     cumstances the return value is TCL_OK and interp is  unused.
     If  name doesn't contain one of the valid relief names or an
     abbreviation of one of them, then an error message is stored
     in  interp->result, TCL_ERROR is returned, and *reliefPtr is
     unmodified.

     Tk_NameOfRelief is  the  logical  inverse  of  Tk_GetRelief.
     Given  a  relief  value  it returns the corresponding string
     (``flat'',   ``raised'',    ``sunken'',    ``groove'',    or
     ``ridge'').   If  relief  isn't  a  legal relief value, then
     ``unknown relief'' is returned.

KEYWORDS

     name, relief, string
itcl2.2/html/tk4.2/GetRootCrd.3.html100666 1751 0 3431 6423554660 15720 0ustar kunkeewheel tk4.2 C API - GetRootCrd

tk4.2 C API - GetRootCrd

NAME

     Tk_GetRootCoords - Compute root-window coordinates of window

SYNOPSIS

     #include <tk.h>

     Tk_GetRootCoords(tkwin, xPtr, yPtr)

ARGUMENTS

     Tk_Window   tkwin   (in)      Token for window.

     int         *xPtr   (out)     Pointer to location  in  which
                                   to    store   root-window   x-
                                   coordinate  corresponding   to
                                   left edge of tkwin's border.

     int         *yPtr   (out)     Pointer to location  in  which
                                   to    store   root-window   y-
                                   coordinate  corresponding   to
                                   top edge of tkwin's border.

DESCRIPTION

     This procedure  scans  through  the  structural  information
     maintained  by  Tk  to  compute  the root-window coordinates
     corresponding to the upper-left corner  of  tkwin's  border.
     If  tkwin  has  no border, then Tk_GetRootCoords returns the
     root-window coordinates corresponding to location  (0,0)  in
     tkwin.   Tk_GetRootCoords  is relatively efficient, since it
     doesn't have to communicate with the X server.

KEYWORDS

     coordinates, root window
itcl2.2/html/tk4.2/GetScroll.3.html100666 1751 0 6726 6423554661 15615 0ustar kunkeewheel tk4.2 C API - GetScroll

tk4.2 C API - GetScroll

NAME

     Tk_GetScrollInfo - parse arguments for scrolling commands

SYNOPSIS

     #include <tk.h>

     int
     Tk_GetScrollInfo(interp, argc, argv, dblPtr, intPtr)

ARGUMENTS

     Tcl_Interp   *interp   (in)      Interpreter  to   use   for
                                      error reporting.

     int          argc      (in)      Number of strings  in  argv
                                      array.

     char         *argv[]   (in)      Argument  strings.    These
                                      represent the entire widget
                                      command, of which the first
                                      word   is   typically   the
                                      widget name and the  second
                                      word  is typically xview or
                                      yview.    This    procedure
                                      parses  arguments  starting
                                      with argv[2].

     double       *dblPtr   (out)     Filled  in  with   fraction
                                      from moveto option, if any.

     int          *intPtr   (out)     Filled in with line or page
                                      count  from  scroll option,
                                      if any.  The value  may  be
                                      negative.

DESCRIPTION

     Tk_GetScrollInfo parses the  arguments  expected  by  widget
     scrolling commands such as xview and yview.  It receives the
     entire list of words that  make  up  a  widget  command  and
     parses  the words starting with argv[2].  The words starting
     with argv[2] must have one of the following forms:
          moveto fraction
          scroll number units
          scroll number pages

     Any of the moveto, scroll, units, and pages keywords may  be
     abbreviated.   If argv has the moveto form, TK_SCROLL_MOVETO
     is returned as result and *dblPtr  is  filled  in  with  the
     fraction  argument  to  the  command, which must be a proper
     real value.  If argv has the scroll form, TK_SCROLL_UNITS or
     TK_SCROLL_PAGES  is  returned  and *intPtr is filled in with
     the number value, which must be a  proper  integer.   If  an
     error  occurs  in  parsing the arguments, TK_SCROLL_ERROR is
     returned and an error message is left in interp->result.

KEYWORDS

     parse, scrollbar, scrolling command, xview, yview
itcl2.2/html/tk4.2/GetSelect.3.html100666 1751 0 10333 6423554663 15605 0ustar kunkeewheel tk4.2 C API - GetSelect

tk4.2 C API - GetSelect

NAME

     Tk_GetSelection - retrieve the contents of a selection

SYNOPSIS

     #include <tk.h>

     int
     Tk_GetSelection(interp, tkwin, selection, target, proc, clientData)

ARGUMENTS

     Tcl_Interp      *interp      (in)      Interpreter  to   use
                                            for reporting errors.

     Tk_Window       tkwin        (in)      Window    on    whose
                                            behalf   to  retrieve
                                            the selection (deter-
                                            mines   display  from
                                            which to retrieve).

     Atom            selection    (in)      The   name   of   the
                                            selection    to    be
                                            retrieved.

     Atom            target       (in)      Form  in   which   to
                                            retrieve selection.

     Tk_GetSelProc   *proc        (in)      Procedure  to  invoke
                                            to  process pieces of
                                            the selection as they
                                            are retrieved.

     ClientData      clientData   (in)      Arbitrary    one-word
                                            value   to   pass  to
                                            proc.

DESCRIPTION

     Tk_GetSelection retrieves the  selection  specified  by  the
     atom  selection  in  the  format  specified  by target.  The
     selection may actually be retrieved in  several  pieces;  as
     each  piece  is  retrieved,  proc  is  called to process the
     piece.  Proc should have arguments and result that match the
     type Tk_GetSelProc:
          typedef int Tk_GetSelProc(
            ClientData clientData,
            Tcl_Interp *interp,
            char *portion);
     The clientData and interp parameters to proc will be  copies
     of  the corresponding arguments to Tk_GetSelection.  Portion
     will be a pointer to a string containing part or all of  the
     selection.   For  large  selections,  proc  will  be  called
     several times with successive  portions  of  the  selection.
     The X Inter-Client Communication Conventions Manual allows a
     selection to be returned in formats other than strings, e.g.
     as  an array of atoms or integers.  If this happens, Tk con-
     verts the selection back into a string before calling  proc.
     If a selection is returned as an array of atoms, Tk converts
     it to a string containing the atom names separated by  white
     space.   For  any other format besides string, Tk converts a
     selection  to  a  string   containing   hexadecimal   values
     separated by white space.

     Tk_GetSelection returns to its caller when the selection has
     been  completely  retrieved and processed by proc, or when a
     fatal error has occurred (e.g. the  selection  owner  didn't
     respond promptly).  Tk_GetSelection normally returns TCL_OK;
     if an error occurs, it returns TCL_ERROR and leaves an error
     message  in  interp->result.  Proc should also return either
     TCL_OK or TCL_ERROR. If proc encounters an error in  dealing
     with  the  selection,  it  should  leave an error message in
     interp->result and return TCL_ERROR;  this  will  abort  the
     selection retrieval.

KEYWORDS

     format, get, selection retrieval
itcl2.2/html/tk4.2/GetUid.3.html100666 1751 0 4055 6423554663 15073 0ustar kunkeewheel tk4.2 C API - GetUid

tk4.2 C API - GetUid

NAME

     Tk_GetUid, Tk_Uid - convert from string to unique identifier

SYNOPSIS

     #include <tk.h>

     #typedef char *Tk_Uid

     Tk_Uid
     Tk_GetUid(string)

ARGUMENTS

     char         *string            (in)      String  for  which
                                               the  corresponding
                                               unique  identifier
                                               is desired.

DESCRIPTION

     Tk_GetUid returns the  unique  identifier  corresponding  to
     string.   Unique  identifiers  are similar to atoms in Lisp,
     and are used in Tk to speed up comparisons and searches.   A
     unique  identifier (type Tk_Uid) is a string pointer and may
     be used anywhere that a variable of type ``char *'' could be
     used.  However, there is guaranteed to be exactly one unique
     identifier for any given  string  value.   If  Tk_GetUid  is
     called twice, once with string a and once with string b, and
     if a and b have the same string value (strcmp(a, b)  ==  0),
     then Tk_GetUid will return exactly the same Tk_Uid value for
     each call (Tk_GetUid(a) == Tk_GetUid(b)).  This  means  that
     variables  of  type Tk_Uid may be compared directly (x == y)
     without having to call  strcmp.   In  addition,  the  return
     value  from Tk_GetUid will have the same string value as its
     argument (strcmp(Tk_GetUid(a), a) == 0).

KEYWORDS

     atom, unique identifier
itcl2.2/html/tk4.2/GetVRoot.3.html100666 1751 0 5023 6423554664 15420 0ustar kunkeewheel tk4.2 C API - GetVRoot

tk4.2 C API - GetVRoot

NAME

     Tk_GetVRootGeometry - Get location and size of virtual  root
     for window

SYNOPSIS

     #include <tk.h>

     Tk_GetVRootGeometry(tkwin, xPtr, yPtr, widthPtr, heightPtr)

ARGUMENTS

     Tk_Window   tkwin       (in)      Token  for  window   whose
                                       virtual   root  is  to  be
                                       queried.

     int         xPtr        (out)     Points to word in which to
                                       store  x-offset of virtual
                                       root.

     int         yPtr        (out)     Points to word in which to
                                       store  y-offset of virtual
                                       root.

     int         widthPtr    (out)     Points to word in which to
                                       store   width  of  virtual
                                       root.

     int         heightPtr   (out)     Points to word in which to
                                       store  height  of  virtual
                                       root.

DESCRIPTION

     TkGetVRootGeometry returns geometry  information  about  the
     virtual  root  window  associated with tkwin.  The ``associ-
     ated'' virtual root is the  one  in  which  tkwin's  nearest
     top-level  ancestor  (or  tkwin  itself if it is a top-level
     window) has been reparented by  the  window  manager.   This
     window  is  identified by a __SWM_ROOT or __WM_ROOT property
     placed on the top-level window by the  window  manager.   If
     tkwin  is  not associated with a virtual root (e.g.  because
     the window manager doesn't use virtual roots) then *xPtr and
     *yPtr  will be set to 0 and *widthPtr and *heightPtr will be
     set to the dimensions of the screen containing tkwin.

KEYWORDS

     geometry, height,  location,  virtual  root,  width,  window
     manager
itcl2.2/html/tk4.2/GetVisual.3.html100666 1751 0 12526 6423554664 15640 0ustar kunkeewheel tk4.2 C API - GetVisual

tk4.2 C API - GetVisual

NAME

     Tk_GetVisual - translate from string to visual

SYNOPSIS

     #include <tk.h>

     Visual *
     Tk_GetVisual(interp, tkwin, string, depthPtr, colormapPtr)

ARGUMENTS

     Tcl_Interp   *interp        (in)      Interpreter to use for
                                           error reporting.

     Tk_Window    tkwin          (in)      Token  for  window  in
                                           which  the visual will
                                           be used.

     char         *string        (in)      String that identifies
                                           the   desired  visual.
                                           See  below  for  valid
                                           formats.

     int          *depthPtr      (out)     Depth   of    returned
                                           visual   gets   stored
                                           here.

     Colormap     *colormapPtr   (out)     If  non-NULL  then   a
                                           suitable  colormap for
                                           visual  is  found  and
                                           its    identifier   is
                                           stored here.

DESCRIPTION

     Tk_GetVisual takes a string  description  of  a  visual  and
     finds a suitable X Visual for use in tkwin, if there is one.
     It returns a pointer to  the  X  Visual  structure  for  the
     visual  and  stores  the  number of bits per pixel for it at
     *depthPtr.  If string is unrecognizable or  if  no  suitable
     visual   could   be   found,   then  NULL  is  returned  and
     Tk_GetVisual leaves an error message in interp->result.   If
     colormap  is  non-NULL  then  Tk_GetVisual  also  locates an
     appropriate colormap for use  with  the  result  visual  and
     stores its X identifier at *colormapPtr.

     The string argument specifies the desired visual in  one  of
     the following ways:

     class depth    The string consists of a class name  followed
                    by an integer depth, with any amount of white
                    space (including  none)  in  between.   class
                    selects  what  sort  of visual is desired and
                    must be one of directcolor, grayscale, greys-
                    cale,  pseudocolor,  staticcolor, staticgray,
                    staticgrey, or truecolor, or a unique  abbre-
                    viation.   depth  specifies how many bits per
                    pixel are needed for the visual.   If  possi-
                    ble,  Tk_GetVisual  will return a visual with
                    this depth; if there  is  no  visual  of  the
                    desired  depth  then Tk_GetVisual looks first
                    for a visual with  greater  depth,  then  one
                    with less depth.

     default        Use the default visual for tkwin's screen.

     pathName       Use the visual for the window given by  path-
                    Name.   pathName must be the name of a window
                    on the same screen as tkwin.

     number         Use the visual whose X identifier is number.

     best ?depth?   Choose the ``best  possible''  visual,  using
                    the  following  rules, in decreasing order of
                    priority:  (a) a visual that has exactly  the
                    desired  depth  is best, followed by a visual
                    with greater depth  than  requested  (but  as
                    little  extra  as  possible),  followed  by a
                    visual with less depth than requested (but as
                    great  a  depth as possible); (b) if no depth
                    is  specified,  then  the  deepest  available
                    visual  is  chosen; (c) pseudocolor is better
                    than  truecolor  or  directcolor,  which  are
                    better than staticcolor, which is better than
                    staticgray  or  grayscale;  (d)  the  default
                    visual  for  the  screen  is  better than any
                    other visual.

CREDITS

     The idea for Tk_GetVisual,  and  the  first  implementation,
     came from Paul Mackerras.

KEYWORDS

     colormap, screen, visual
itcl2.2/html/tk4.2/HandleEvent.3.html100666 1751 0 3714 6423554664 16111 0ustar kunkeewheel tk4.2 C API - HandleEvent

tk4.2 C API - HandleEvent

NAME

     Tk_HandleEvent - invoke event  handlers  for  window  system
     events

SYNOPSIS

     #include <tk.h>

     Tk_HandleEvent(eventPtr)

ARGUMENTS

     XEvent   *eventPtr   (in)      Pointer   to   X   event   to
                                    dispatch      to     relevant
                                    handler(s).

DESCRIPTION

     Tk_HandleEvent is a lower-level procedure  that  deals  with
     window   events.   It  is  called  by  Tk_ServiceEvent  (and
     indirectly by Tk_DoOneEvent),  and  in  a  few  other  cases
     within  Tk.  It makes callbacks to any window event handlers
     (created  by  calls  to  Tk_CreateEventHandler)  that  match
     eventPtr  and  then returns.  In some cases it may be useful
     for an application to bypass the Tk  event  queue  and  call
     Tk_HandleEvent  directly  instead  of  calling Tk_QueueEvent
     followed by Tk_ServiceEvent.

     This procedure may be invoked recursively.  For example,  it
     is  possible  to  invoke  Tk_HandleEvent  recursively from a
     handler called by Tk_HandleEvent.  This sort of operation is
     useful in some modal situations, such as when a notifier has
     been popped up and an application wishes  to  wait  for  the
     user to click a button in the notifier before doing anything
     else.

KEYWORDS

     callback, event, handler, window
itcl2.2/html/tk4.2/IdToWindow.3.html100666 1751 0 2124 6423554664 15735 0ustar kunkeewheel tk4.2 C API - IdToWindow

tk4.2 C API - IdToWindow

NAME

     Tk_IdToWindow - Find Tk's window information for an X window

SYNOPSIS

     #include <tk.h>

     Tk_Window
     Tk_IdToWindow(display, window)

ARGUMENTS

     Display     *display  (in)      X  display  containing   the
                                     window.

     Window      window    (in)      X id for window.

DESCRIPTION

     Given  an  X  window  identifier  and  the  X   display   it
     corresponds  to,  this  procedure  returns the corresponding
     Tk_Window handle.  If there is no Tk_Window corresponding to
     window then NULL is returned.

KEYWORDS

     X window id
itcl2.2/html/tk4.2/ImgChanged.3.html100666 1751 0 7773 6423554664 15713 0ustar kunkeewheel tk4.2 C API - ImgChanged

tk4.2 C API - ImgChanged

NAME

     Tk_ImageChanged - notify widgets  that  image  needs  to  be
     redrawn

SYNOPSIS

     #include <tk.h>

     Tk_ImageChanged(imageMaster, x, y, width, height, imageWidth, imageHeight)

ARGUMENTS

     Tk_ImageMaster   imageMaster   (in)      Token  for   image,
                                              which was passed to
                                              image's  createProc
                                              when  the image was
                                              created.

     int              x             (in)      X-coordinate     of
                                              upper-left   corner
                                              of   region    that
                                              needs     redisplay
                                              (measured      from
                                              upper-left   corner
                                              of image).

     int              y             (in)      Y-coordinate     of
                                              upper-left   corner
                                              of   region    that
                                              needs     redisplay
                                              (measured      from
                                              upper-left   corner
                                              of image).

     int              width         (in)      Width   of   region
                                              that  needs  to  be
                                              redrawn, in pixels.

     int              height        (in)      Height  of   region
                                              that  needs  to  be
                                              redrawn, in pixels.

     int              imageWidth    (in)      Current  width   of
                                              image, in pixels.

     int              imageHeight   (in)      Current  height  of
                                              image, in pixels.

DESCRIPTION


     An image manager calls Tk_ImageChanged for an image whenever
     anything  happens that requires the image to be redrawn.  As
     a result of calling Tk_ImageChanged, any widgets  using  the
     image  are  notified  so  that they can redisplay themselves
     appropriately.   The  imageMaster  argument  identifies  the
     image,  and  x,  y,  width, and height specify a rectangular
     region  within  the  image  that  needs   to   be   redrawn.
     imageWidth and imageHeight specify the image's (new) size.

     An image manager  should  call  Tk_ImageChanged  during  its
     createProc  to specify the image's initial size and to force
     redisplay if there are existing instances for the image.  If
     any of the pixel values in the image should change later on,
     Tk_ImageChanged should be called again with x, y, width, and
     height  values  that  cover all the pixels that changed.  If
     the size of the image should  change,  then  Tk_ImageChanged
     must  be  called to indicate the new size, even if no pixels
     need to be redisplayed.

SEE ALSO

     Tk_CreateImageType

KEYWORDS

     images, redisplay, image size changes
itcl2.2/html/tk4.2/InternAtom.3.html100666 1751 0 4732 6423554664 15775 0ustar kunkeewheel tk4.2 C API - InternAtom

tk4.2 C API - InternAtom

NAME

     Tk_InternAtom, Tk_GetAtomName - manage cache of X atoms

SYNOPSIS

     #include <tk.h>

     Atom
     Tk_InternAtom(tkwin, name)

     char *
     Tk_GetAtomName(tkwin, atom)

ARGUMENTS

     Tk_Window   tkwin    (in)      Token for  window.   Used  to
                                    map  atom or name relative to
                                    a particular display.

     char        *name    (in)      String name for which atom is
                                    desired.

     Atom        atom     (in)      Atom for which  corresponding
                                    string name is desired.

DESCRIPTION

     These procedures are similar to the Xlib procedures  XInter-
     nAtom  and  XGetAtomName.   Tk_InternAtom  returns  the atom
     identifier associated with string given by name;   the  atom
     identifier  is  only  valid  for the display associated with
     tkwin.  Tk_GetAtomName returns the  string  associated  with
     atom   on   tkwin's   display.    The   string  returned  by
     Tk_GetAtomName is in Tk's storage:  the caller need not free
     this  space  when  finished  with the string, and the caller
     should not modify the contents of the returned  string.   If
     there   is   no   atom   atom   on   tkwin's  display,  then
     Tk_GetAtomName returns the string ``?bad atom?''.

     Tk caches the  information  returned  by  Tk_InternAtom  and
     Tk_GetAtomName so that future calls for the same information
     can be  serviced  from  the  cache  without  contacting  the
     server.  Thus Tk_InternAtom and Tk_GetAtomName are generally
     much faster than their Xlib counterparts, and they should be
     used in place of the Xlib procedures.

KEYWORDS

     atom, cache, display
itcl2.2/html/tk4.2/MainLoop.3.html100666 1751 0 2115 6423554664 15424 0ustar kunkeewheel tk4.2 C API - MainLoop

tk4.2 C API - MainLoop

NAME

     Tk_MainLoop - loop for events until all windows are deleted

SYNOPSIS

     #include <tk.h>

     Tk_MainLoop()

DESCRIPTION

     Tk_MainLoop is a procedure  that  loops  repeatedly  calling
     Tcl_DoOneEvent.   It returns only when there are no applica-
     tions left in this  process  (i.e.  no  main  windows  exist
     anymore).  Most windowing applications will call Tk_MainLoop
     after initialization; the main execution of the  application
     will    consist    entirely   of   callbacks   invoked   via
     Tcl_DoOneEvent.

KEYWORDS

     application, event, main loop
itcl2.2/html/tk4.2/MainWin.3.html100666 1751 0 2212 6423554664 15246 0ustar kunkeewheel tk4.2 C API - MainWin

tk4.2 C API - MainWin

NAME

     Tk_MainWindow - find the main window for an application

SYNOPSIS

     #include <tk.h>

     Tk_Window
     Tk_MainWindow(interp)

ARGUMENTS

     Tcl_Interp   *interp     (in/out)  Interpreter    associated
                                        with the application.

DESCRIPTION

     If  interp  is  associated  with  a  Tk   application   then
     Tk_MainWindow  returns  the  application's  main window.  If
     there is no  Tk  application  associated  with  interp  then
     Tk_MainWindow  returns  NULL  and leaves an error message in
     interp->result.

KEYWORDS

     application, main window
itcl2.2/html/tk4.2/MaintGeom.3.html100666 1751 0 12357 6423554664 15617 0ustar kunkeewheel tk4.2 C API - MaintGeom

tk4.2 C API - MaintGeom

NAME

     Tk_MaintainGeometry,   Tk_UnmaintainGeometry   -    maintain
     geometry of one window relative to another

SYNOPSIS

     #include <tk.h>

     Tk_MaintainGeometry(slave, master, x, y, width, height)

     Tk_UnmaintainGeometry(slave, master)

ARGUMENTS

     Tk_Window   slave    (in)      Window whose geometry  is  to
                                    be controlled.

     Tk_Window   master   (in)      Window  relative   to   which
                                    slave's geometry will be con-
                                    trolled.

     int         x        (in)      Desired x-coordinate of slave
                                    in master, measured in pixels
                                    from the inside  of  master's
                                    left border to the outside of
                                    slave's left border.

     int         y        (in)      Desired y-coordinate of slave
                                    in master, measured in pixels
                                    from the inside  of  master's
                                    top  border to the outside of
                                    slave's top border.

     int         width    (in)      Desired width for  slave,  in
                                    pixels.

     int         height   (in)      Desired height for slave,  in
                                    pixels.

DESCRIPTION

     Tk_MaintainGeometry and Tk_UnmaintainGeometry make it easier
     for  geometry managers to deal with slaves whose masters are
     not their parents.  Three problems arise if the master for a
     slave is not its parent:

     [1]  The x- and y-position of the slave must  be  translated
          from the coordinate system of the master to that of the
          parent before positioning the slave.

     [2]  If the master window, or any of its ancestors up to the
          slave's  parent, is moved, then the slave must be repo-
          sitioned within its parent in  order  to  maintain  the
          correct position relative to the master.

     [3]  If the master or one of  its  ancestors  is  mapped  or
          unmapped,  then the slave must be mapped or unmapped to
          correspond.

     None of these problems is an issue if the parent and  master
     are  the  same.   For  example,  if the master or one of its
     ancestors is unmapped, the slave is automatically removed by
     the screen by X.

     Tk_MaintainGeometry deals with  these  problems  for  slaves
     whose  masters aren't their parents.  Tk_MaintainGeometry is
     typically called by a window manager  once  it  has  decided
     where  a  slave should be positioned relative to its master.
     Tk_MaintainGeometry translates the coordinates to the  coor-
     dinate  system  of slave's parent and then moves and resizes
     the slave  appropriately.   Furthermore,  it  remembers  the
     desired  position  and creates event handlers to monitor the
     master and all of its ancestors up to  (but  not  including)
     the  slave's  parent.   If  any  of  these windows is moved,
     mapped, or unmapped, the slave will be adjusted so  that  it
     is  mapped  only  when the master is mapped and its geometry
     relative to the master remains as specified by x, y,  width,
     and height.

     When a window manager relinquishes control over a window, or
     if  it decides that it does not want the window to appear on
     the    screen    under    any    conditions,    it     calls
     Tk_UnmaintainGeometry.    Tk_UnmaintainGeometry  unmaps  the
     window and cancels any previous calls to Tk_MaintainGeometry
     for  the master-slave pair, so that the slave's geometry and
     mapped  state  are  no  longer   maintained   automatically.
     Tk_UnmaintainGeometry  need  not  be  called  by  a geometry
     manager if the slave, the master, or  any  of  the  master's
     ancestors is destroyed:  Tk will call it automatically.

     If Tk_MaintainGeometry is called  repeatedly  for  the  same
     master-slave pair, the information from the most recent call
     supersedes any older information.  If  Tk_UnmaintainGeometry
     is  called  for  a master-slave pair that is isn't currently
     managed, the call has no effect.

KEYWORDS

     geometry manager,  map,  master,  parent,  position,  slave,
     unmap
itcl2.2/html/tk4.2/ManageGeom.3.html100666 1751 0 11730 6423554664 15731 0ustar kunkeewheel tk4.2 C API - ManageGeom

tk4.2 C API - ManageGeom

NAME

     Tk_ManageGeometry - arrange to handle geometry requests  for
     a window

SYNOPSIS

     #include <tk.h>

     Tk_ManageGeometry(tkwin, mgrPtr, clientData)

ARGUMENTS

     Tk_Window         tkwin        (in)      Token for window to
                                              be managed.

     Tk_GeomMgr        *mgrPtr      (in)      Pointer   to   data
                                              structure  contain-
                                              ing     information
                                              about  the geometry
                                              manager, or NULL to
                                              indicate       that
                                              tkwin's    geometry
                                              shouldn't        be
                                              managed    anymore.
                                              The  data structure
                                              pointed    to    by
                                              mgrPtr    must   be
                                              static:  Tk keeps a
                                              reference  to it as
                                              long as the  window
                                              is managed.

     ClientData        clientData   (in)      Arbitrary  one-word
                                              value  to  pass  to
                                              geometry    manager
                                              callbacks.

DESCRIPTION

     Tk_ManageGeometry  arranges  for   a   particular   geometry
     manager,  described  by  the mgrPtr argument, to control the
     geometry of a particular slave window, given by  tkwin.   If
     tkwin was previously managed by some other geometry manager,
     the previous manager loses control in favor of the new  one.
     If  mgrPtr  is  NULL,  geometry  management is cancelled for
     tkwin.

     The structure pointed  to  by  mgrPtr  contains  information
     about the geometry manager:
          typedef struct {
            char *name;
            Tk_GeomRequestProc *requestProc;
            Tk_GeomLostSlaveProc *lostSlaveProc;
          } Tk_GeomMgr;
     The name field is the textual name for the geometry manager,
     such  as  pack or place;  this value will be returned by the
     command winfo manager.

     requestProc is a procedure in the geometry manager that will
     be  invoked  whenever  Tk_GeometryRequest  is  called by the
     slave to change its desired  geometry.   requestProc  should
     have   arguments   and   results   that   match   the   type
     Tk_GeomRequestProc:
          typedef void Tk_GeomRequestProc(
            ClientData clientData,
            Tk_Window tkwin);
     The parameters to  requestProc  will  be  identical  to  the
     corresponding   parameters   passed   to  Tk_ManageGeometry.
     clientData usually points to  a  data  structure  containing
     application-specific information about how to manage tkwin's
     geometry.

     The lostSlaveProc field of mgrPtr  points  to  another  pro-
     cedure   in   the   geometry   manager.    Tk   will  invoke
     lostSlaveProc if some other manager calls  Tk_ManageGeometry
     to  claim  tkwin  away  from  the  current geometry manager.
     lostSlaveProc is not invoked if Tk_ManageGeometry is  called
     with  a  NULL  value  for  mgrPtr  (presumably  the  current
     geometry manager has made this call,  so  it  already  knows
     that  the  window is no longer managed), nor is it called if
     mgrPtr is the same as the window's current geometry manager.
     lostSlaveProc  should  have arguments and results that match
     the following prototype:
          typedef void Tk_GeomLostSlaveProc(
            ClientData clientData,
            Tk_Window tkwin);
     The parameters to lostSlaveProc will  be  identical  to  the
     corresponding parameters passed to Tk_ManageGeometry.

KEYWORDS

     callback, geometry, managed, request, unmanaged
itcl2.2/html/tk4.2/MapWindow.3.html100666 1751 0 3600 6423554664 15613 0ustar kunkeewheel tk4.2 C API - MapWindow

tk4.2 C API - MapWindow

NAME

     Tk_MapWindow, Tk_UnmapWindow - map or unmap a window

SYNOPSIS

     #include <tk.h>

     Tk_Window
     Tk_MapWindow(tkwin)

     Tk_UnmapWindow(tkwin)

ARGUMENTS

     Tk_Window   tkwin    (in)      Token for window.

DESCRIPTION

     These procedures may  be  used  to  map  and  unmap  windows
     managed by Tk.  Tk_MapWindow maps the window given by tkwin,
     and also creates an X window corresponding to  tkwin  if  it
     doesn't already exist.  See the Tk_CreateWindow manual entry
     for information on deferred window creation.  Tk_UnmapWindow
     unmaps tkwin's window from the screen.

     If tkwin is a child window  (i.e.  Tk_CreateChildWindow  was
     used  to  create  it), then event handlers interested in map
     and unmap events are invoked immediately.  If tkwin isn't an
     internal  window,  then  the  event handlers will be invoked
     later, after X has seen the request and  returned  an  event
     for it.

     These procedures should be used in place of the X procedures
     XMapWindow  and  XUnmapWindow,  since they update Tk's local
     data structure for tkwin.  Applications using Tk should  not
     invoke XMapWindow and XUnmapWindow directly.

KEYWORDS

     map, unmap, window
itcl2.2/html/tk4.2/Name.3.html100666 1751 0 7365 6423554665 14603 0ustar kunkeewheel tk4.2 C API - Name

tk4.2 C API - Name

NAME

     Tk_Name,  Tk_PathName,  Tk_NameToWindow  -  convert  between
     names and window tokens

SYNOPSIS

     #include <tk.h>

     Tk_Uid
     Tk_Name(tkwin)

     char *
     Tk_PathName(tkwin)

     Tk_Window
     Tk_NameToWindow(interp, pathName, tkwin)

ARGUMENTS

     Tk_Window    tkwin       (in)      Token for window.

     Tcl_Interp   *interp     (out)     Interpreter  to  use  for
                                        error reporting.

     char         *pathName   (in)      Character string contain-
                                        ing path name of window.

DESCRIPTION

     Each window managed by Tk has two names, a short  name  that
     identifies a window among children of the same parent, and a
     path name that identifies the window uniquely among all  the
     windows belonging to the same main window.  The path name is
     used more often in Tk than the short name;   many  commands,
     like bind, expect path names as arguments.

     The Tk_Name macro returns a window's short  name,  which  is
     the same as the name argument passed to Tk_CreateWindow when
     the window was created.  The value is returned as a  Tk_Uid,
     which  may  be  used just like a string pointer but also has
     the properties of a unique identifier (see the manual  entry
     for Tk_GetUid for details).

     The Tk_PathName macro returns a hierarchical name for tkwin.
     Path  names  have  a structure similar to file names in Unix
     but with dots between elements instead of slashes:  the main
     window  for  an  application  has  the path name ``.'';  its
     children have names like ``.a'' and ``.b'';  their  children
     have  names like ``.a.aa'' and ``.b.bb''; and so on.  A win-
     dow is considered to be be a child  of  another  window  for
     naming  purposes if the second window was named as the first
     window's parent when the first window was created.  This  is
     not always the same as the X window hierarchy.  For example,
     a pop-up is created as a child of the root window,  but  its
     logical  parent will usually be a window within the applica-
     tion.

     The procedure Tk_NameToWindow returns the token for a window
     given its path name (the pathName argument) and another win-
     dow belonging to the same main window (tkwin).  It  normally
     returns  a token for the named window, but if no such window
     exists Tk_NameToWindow leaves an error  message  in  interp-
     >result   and   returns   NULL.    The   tkwin  argument  to
     Tk_NameToWindow is needed because path names are only unique
     within  a  single application hierarchy.  If, for example, a
     single process has opened two main windows, each will have a
     separate  naming  hierarchy  and  the  same  path name might
     appear in each of the hierarchies.  Normally  tkwin  is  the
     main  window  of the desired hierarchy, but this need not be
     the case:  any window in the desired hierarchy may be used.

KEYWORDS

     name, path name, token, window
itcl2.2/html/tk4.2/MoveToplev.3.html100666 1751 0 5623 6423554664 16015 0ustar kunkeewheel tk4.2 C API - MoveToplev

tk4.2 C API - MoveToplev

NAME

     Tk_MoveToplevelWindow - Adjust the position of  a  top-level
     window

SYNOPSIS

     #include <tk.h>

     Tk_MoveToplevelWindow(tkwin, x, y)

ARGUMENTS

     Tk_Window   tkwin   (in)      Token for top-level window  to
                                   move.

     int         x       (in)      New x-coordinate for the  top-
                                   left  pixel of tkwin's border,
                                   or the top-left pixel  of  the
                                   decorative border supplied for
                                   tkwin by the  window  manager,
                                   if there is one.

     int         y       (in)      New y-coordinate for the  top-
                                   left  pixel of tkwin's border,
                                   or the top-left pixel  of  the
                                   decorative border supplied for
                                   tkwin by the  window  manager,
                                   if there is one.

DESCRIPTION

     In general, a window should  never  set  its  own  position;
     this  should  be  done  only  by the geometry manger that is
     responsible for the window.  For top-level windows the  win-
     dow  manager  is  effectively the geometry manager;  Tk pro-
     vides interface code between the application and the  window
     manager  to convey the application's desires to the geometry
     manager.  The desired size for a top-level  window  is  con-
     veyed  using  the  usual  Tk_GeometryRequest mechanism.  The
     procedure Tk_MoveToplevelWindow may be used by  an  applica-
     tion  to  request a particular position for a top-level win-
     dow;  this procedure  is  similar  in  function  to  the  wm
     geometry  Tcl command except that negative offsets cannot be
     specified.  It is invoked by widgets such as menus that want
     to appear at a particular place on the screen.

     When Tk_MoveToplevelWindow is called it doesn't  immediately
     pass  on the new desired location to the window manager;  it
     defers this action until all other outstanding work has been
     completed, using the Tk_DoWhenIdle mechanism.

KEYWORDS

     position, top-level window, window manager
itcl2.2/html/tk4.2/NameOfImg.3.html100666 1751 0 2217 6423554665 15514 0ustar kunkeewheel tk4.2 C API - NameOfImg

tk4.2 C API - NameOfImg

NAME

     Tk_NameOfImage - Return name of image.

SYNOPSIS

     #include <tk.h>

     char *
     Tk_NameOfImage(typePtr)

ARGUMENTS

     Tk_ImageMaster   *masterPtr   (in)      Token   for   image,
                                             which  was passed to
                                             image      manager's
                                             createProc  when the
                                             image was created.

DESCRIPTION

     This procedure is invoked by image managers to find out  the
     name of an image.  Given the token for the image, it returns
     the string name for the image.

KEYWORDS

     image manager, image name
itcl2.2/html/tk4.2/OwnSelect.3.html100666 1751 0 5111 6423554665 15611 0ustar kunkeewheel tk4.2 C API - OwnSelect

tk4.2 C API - OwnSelect

NAME

     Tk_OwnSelection - make a window the  owner  of  the  primary
     selection

SYNOPSIS

     #include <tk.h>

     Tk_OwnSelection(tkwin, selection, proc, clientData)

ARGUMENTS

     Tk_Window        tkwin        (in)      Window  that  is  to
                                             become new selection
                                             owner.

     Atom             selection    (in)      The  name   of   the
                                             selection    to   be
                                             owned,    such    as
                                             XA_PRIMARY.

     Tk_LostSelProc   *proc        (in)      Procedure to  invoke
                                             when   tkwin   loses
                                             selection  ownership
                                             later.

     ClientData       clientData   (in)      Arbitrary   one-word
                                             value   to  pass  to
                                             proc.

DESCRIPTION

     Tk_OwnSelection arranges for tkwin to become the  new  owner
     of  the  selection  specified  by the atom selection.  After
     this call completes, future requests for the selection  will
     be   directed   to   handlers   created   for   tkwin  using
     Tk_CreateSelHandler.  When tkwin eventually loses the selec-
     tion  ownership, proc will be invoked so that the window can
     clean itself up  (e.g.  by  unhighlighting  the  selection).
     Proc  should  have  arguments and result that match the type
     Tk_LostSelProc:
          typedef void Tk_LostSelProc(ClientData clientData);
     The clientData parameter to proc is a copy of the clientData
     argument  given to Tk_OwnSelection, and is usually a pointer
     to a data structure containing application-specific informa-
     tion about tkwin.

KEYWORDS

     own, selection owner
itcl2.2/html/tk4.2/ParseArgv.3.html100666 1751 0 46367 6423554665 15642 0ustar kunkeewheel tk4.2 C API - ParseArgv

tk4.2 C API - ParseArgv

NAME

     Tk_ParseArgv - process command-line options

SYNOPSIS

     #include <tk.h>

     int
     Tk_ParseArgv(interp, tkwin, argcPtr, argv, argTable, flags)

ARGUMENTS

     Tcl_Interp    *interp     (in)      Interpreter to  use  for
                                         returning   error   mes-
                                         sages.

     Tk_Window     tkwin       (in)      Window to use when argu-
                                         ments     specify     Tk
                                         options.  If NULL,  then
                                         no  Tk  options  will be
                                         processed.

     int           argcPtr     (in/out)  Pointer  to  number   of
                                         arguments in argv;  gets
                                         modified to hold  number
                                         of unprocessed arguments
                                         that  remain  after  the
                                         call.

     char          **argv      (in/out)  Command  line  arguments
                                         passed  to main program.
                                         Modified to hold  unpro-
                                         cessed   arguments  that
                                         remain after the call.

     Tk_ArgvInfo   *argTable   (in)      Array    of     argument
                                         descriptors,  terminated
                                         by  element  with   type
                                         TK_ARGV_END.

     int           flags       (in)      If  non-zero,  then   it
                                         specifies  one  or  more
                                         flags that  control  the
                                         parsing   of  arguments.
                                         Different flags  may  be
                                         OR'ed   together.    The
                                         flags currently  defined
                                         are
                                         TK_ARGV_DONT_SKIP_FIRST_ARG,
                                         TK_ARGV_NO_ABBREV,
                                         TK_ARGV_NO_LEFTOVERS,
                                         and TK_ARGV_NO_DEFAULTS.

DESCRIPTION

     Tk_ParseArgv processes an array  of  command-line  arguments
     according  to a table describing the kinds of arguments that
     are expected.  Each of the arguments in argv is processed in
     turn:   if  it  matches  one of the entries in argTable, the
     argument is processed according to that entry and discarded.
     The  arguments  that  do  not match anything in argTable are
     copied down to the beginning of argv (retaining their origi-
     nal  order)  and  returned to the caller.  At the end of the
     call Tk_ParseArgv sets *argcPtr to hold the number of  argu-
     ments  that  are  left in argv, and argv[*argcPtr] will hold
     the value NULL.  Normally, Tk_ParseArgv assumes that argv[0]
     is  a  command  name, so it is treated like an argument that
     doesn't match argTable and returned to the caller;  however,
     if  the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in flags then
     argv[0] will be processed just like the  other  elements  of
     argv.

     Tk_ParseArgv normally returns the value TCL_OK.  If an error
     occurs  while  parsing  the  arguments,  then  TCL_ERROR  is
     returned and Tk_ParseArgv will leave  an  error  message  in
     interp->result in the standard Tcl fashion.  In the event of
     an error return, *argvPtr will not have been  modified,  but
     argv  could  have  been  partially  modified.   The possible
     causes of errors are explained below.

     The argTable array specifies the kinds of arguments that are
     expected;  each of its entries has the following structure:
          typedef struct {
            char *key;
            int type;
            char *src;
            char *dst;
            char *help;
          } Tk_ArgvInfo;
     The key field is a string such as ``-display'' or  `` - bg''
     that  is  compared  with the values in argv.  Type indicates
     how to process an argument that matches key  (more  on  this
     below).   Src and dst are additional values used in process-
     ing the argument.  Their exact usage depends  on  type,  but
     typically  src  indicates a value and dst indicates where to
     store the value.  The char * declarations for  src  and  dst
     are  placeholders:   the  actual  types  may  be  different.
     Lastly, help is a string giving a brief description of  this
     option;   this  string  is  printed  when users ask for help
     about command-line options.

     When processing an argument in argv,  Tk_ParseArgv  compares
     the argument to each of the key's in argTable.  Tk_ParseArgv
     selects the first specifier whose key matches  the  argument
     exactly, if such a specifier exists.  Otherwise Tk_ParseArgv
     selects a specifier for  which  the  argument  is  a  unique
     abbreviation.   If the argument is a unique abbreviation for
     more than one specifier, then  an  error  is  returned.   If
     there is no matching entry in argTable, then the argument is
     skipped and returned to the caller.

     Once a matching argument specifier  is  found,  Tk_ParseArgv
     processes  the  argument  according to the type field of the
     specifier.  The argument that matched key  is  called  ``the
     matching  argument''  in the descriptions below.  As part of
     the processing, Tk_ParseArgv may also use the next  argument
     in  argv  after the matching argument, which is called ``the
     following argument''.  The legal values for  type,  and  the
     processing that they cause, are as follows:

     TK_ARGV_END
          Marks the end of the table.  The last entry in argTable
          must  have  this  type;   all  of  its other fields are
          ignored and it will never match any arguments.

     TK_ARGV_CONSTANT
          Src is treated as an integer and dst is  treated  as  a
          pointer  to  an  integer.   Src is stored at *dst.  The
          matching argument is discarded.

     TK_ARGV_INT
          The following argument must contain an  integer  string
          in the format accepted by strtol (e.g. ``0'' and ``0x''
          prefixes may be used to specify  octal  or  hexadecimal
          numbers, respectively).  Dst is treated as a pointer to
          an integer;  the following argument is converted to  an
          integer value and stored at *dst.  Src is ignored.  The
          matching and following  arguments  are  discarded  from
          argv.

     TK_ARGV_FLOAT
          The following argument must  contain  a  floating-point
          number  in  the  format  accepted  by  strtol.   Dst is
          treated as the address of an double-precision  floating
          point  value;  the following argument is converted to a
          double-precision value and stored at *dst.  The  match-
          ing and following arguments are discarded from argv.

     TK_ARGV_STRING
          In this form, dst is treated as a pointer  to  a  (char
          *);  Tk_ParseArgv  stores at *dst a pointer to the fol-
          lowing argument, and discards the matching and  follow-
          ing arguments from argv.  Src is ignored.

     TK_ARGV_UID
          This form is similar to TK_ARGV_STRING, except that the
          argument  is turned into a Tk_Uid by calling Tk_GetUid.
          Dst is treated as a pointer to a  Tk_Uid;  Tk_ParseArgv
          stores  at *dst the Tk_Uid corresponding to the follow-
          ing argument, and discards the matching  and  following
          arguments from argv.  Src is ignored.

     TK_ARGV_CONST_OPTION
          This form causes a Tk option  to  be  set  (as  if  the
          option  command  had  been  invoked).  The src field is
          treated as a pointer to a string giving the value of an
          option,  and dst is treated as a pointer to the name of
          the option.  The matching argument  is  discarded.   If
          tkwin  is  NULL,  then argument specifiers of this type
          are ignored (as if they did not exist).

     TK_ARGV_OPTION_VALUE
          This form is similar  to  TK_ARGV_CONST_OPTION,  except
          that  the value of the option is taken from the follow-
          ing argument instead of from src.  Dst is used  as  the
          name  of the option.  Src is ignored.  The matching and
          following arguments are discarded.  If tkwin  is  NULL,
          then  argument  specifiers of this type are ignored (as
          if they did not exist).

     TK_ARGV_OPTION_NAME_VALUE
          In this case the following argument  is  taken  as  the
          name  of  a  Tk  option  and the argument after that is
          taken as the value for that option.  Both src  and  dst
          are  ignored.   All  three arguments are discarded from
          argv.  If tkwin is NULL, then  argument  specifiers  of
          this type are ignored (as if they did not exist).

     TK_ARGV_HELP
          When this kind of option is  encountered,  Tk_ParseArgv
          uses  the  help  fields of argTable to format a message
          describing all the valid  arguments.   The  message  is
          placed   in  interp->result  and  Tk_ParseArgv  returns
          TCL_ERROR.  When  this  happens,  the  caller  normally
          prints  the  help message and aborts.  If the key field
          of a TK_ARGV_HELP specifier is NULL, then the specifier
          will  never  match  any  arguments;   in  this case the
          specifier simply provides  extra  documentation,  which
          will  be  included  when  some other TK_ARGV_HELP entry
          causes help information to be returned.

     TK_ARGV_REST
          This option is used by programs or commands that  allow
          the last several of their options to be the name and/or
          options for some  other  program.   If  a  TK_ARGV_REST
          argument  is  found,  then Tk_ParseArgv doesn't process
          any of the remaining arguments;  it returns them all at
          the beginning of argv (along with any other unprocessed
          arguments).  In addition, Tk_ParseArgv  treats  dst  as
          the address of an integer value, and stores at *dst the
          index of the first of the TK_ARGV_REST options  in  the
          returned  argv.  This allows the program to distinguish
          the TK_ARGV_REST options from other unprocessed options
          that preceded the TK_ARGV_REST.

     TK_ARGV_FUNC
          For this kind  of  argument,  src  is  treated  as  the
          address of a procedure, which is invoked to process the
          following argument.  The procedure should have the fol-
          lowing structure:
               int
               func(dst, key, nextArg)
                 char *dst;
                 char *key;
                 char *nextArg;
               {
               }
          The dst and key parameters will contain the correspond-
          ing  fields  from  the argTable entry, and nextArg will
          point to the following argument from argv (or  NULL  if
          there aren't any more arguments left in argv).  If func
          uses nextArg (so that Tk_ParseArgv should discard  it),
          then  it should return 1.  Otherwise it should return 0
          and TkParseArgv will process the following argument  in
          the normal fashion.  In either event the matching argu-
          ment is discarded.

     TK_ARGV_GENFUNC
          This form provides a more  general  procedural  escape.
          It treats src as the address of a procedure, and passes
          that procedure all of  the  remaining  arguments.   The
          procedure should have the following form:
               int
               genfunc(dst, interp, key, argc, argv)
                 char *dst;
                 Tcl_Interp *interp;
                 char *key;
                 int argc;
                 char **argv;
               {
               }
          The dst and key parameters will contain the correspond-
          ing fields from the argTable entry.  Interp will be the
          same as the interp argument to Tcl_ParseArgv.  Argc and
          argv  refer  to  all  of the options after the matching
          one.  Genfunc should behave in  a  fashion  similar  to
          Tk_ParseArgv:  parse as many of the remaining arguments
          as it can, then return any that are left by  compacting
          them  to  the  beginning of argv (starting at argv[0]).
          Genfunc should return a count of how many arguments are
          left  in argv; Tk_ParseArgv will process them.  If gen-
          func encounters an error then it should leave an  error
          message  in  interp->result,  in the usual Tcl fashion,
          and return -1;  when  this  happens  Tk_ParseArgv  will
          abort its processing and return TCL_ERROR.

FLAGS

     TK_ARGV_DONT_SKIP_FIRST_ARG
          Tk_ParseArgv normally treats argv[0] as  a  program  or
          command  name,  and returns it to the caller just as if
          it hadn't matched argTable.  If  this  flag  is  given,
          then argv[0] is not given special treatment.

     TK_ARGV_NO_ABBREV
          Normally, Tk_ParseArgv accepts unique abbreviations for
          key  values  in  argTable.   If this flag is given then
          only exact matches will be acceptable.

     TK_ARGV_NO_LEFTOVERS
          Normally, Tk_ParseArgv returns  unrecognized  arguments
          to  the  caller.   If  this  bit  is  set in flags then
          Tk_ParseArgv will return an error if it encounters  any
          argument  that doesn't match argTable.  The only excep-
          tion to this rule is argv[0], which will be returned to
          the    caller    with    no    errors    as   long   as
          TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified.

     TK_ARGV_NO_DEFAULTS
          Normally, Tk_ParseArgv searches an  internal  table  of
          standard  argument  specifiers in addition to argTable.
          If this bit is set in flags, then Tk_ParseArgv will use
          only argTable and not its default table.

EXAMPLE

     Here is an example definition of an argTable and some sample
     command lines that use the options.  Note the effect on argc
     and argv;  arguments processed  by  Tk_ParseArgv  are  elim-
     inated  from  argv,  and  argc is updated to reflect reduced
     number of arguments.
          /*
           * Define and set default values for globals.
           */
          int debugFlag = 0;
          int numReps = 100;
          char defaultFileName[] = "out";
          char *fileName = defaultFileName;
          Boolean exec = FALSE;

          /*
           * Define option descriptions.
           */
          Tk_ArgvInfo argTable[] = {
            {"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
               "Turn on debugging printfs"},
            {"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
               "Number of repetitions"},
            {"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName,
               "Name of file for output"},
            {"x", TK_ARGV_REST, (char *) NULL, (char *) &exec,
               "File to exec, followed by any arguments (must be last argument)."},
            {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL,
                (char *) NULL}
          };

          main(argc, argv)
            int argc;
            char *argv[];
          {
            ...

            if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
               fprintf(stderr, "%s\n", interp->result);
               exit(1);
            }

            /*
             * Remainder of the program.
             */
          }

     Note that default values can be assigned to variables  named
     in  argTable:  the variables will only be overwritten if the
     particular arguments are present in  argv.   Here  are  some
     example command lines and their effects.
          prog -N 200 infile# just sets the numReps variable to 200
          prog -of out200 infile # sets fileName to reference "out200"
          prog -XN 10 infile# sets the debug flag, also sets numReps
     In  all  of  the  above  examples,  argc  will  be  set   by
     Tk_ParseArgv to 2, argv[0] will be ``prog'', argv[1] will be
     ``infile'', and argv[2] will be NULL.

KEYWORDS

     arguments, command line, options
itcl2.2/html/tk4.2/QWinEvent.3.html100666 1751 0 3537 6423554665 15600 0ustar kunkeewheel tk4.2 C API - QWinEvent

tk4.2 C API - QWinEvent

NAME

     Tk_QueueWindowEvent - Add a window event to  the  Tcl  event
     queue

SYNOPSIS

     #include <tk.h>

     Tk_QueueWindowEvent(eventPtr, position)

ARGUMENTS

     XEvent              *eventPtr  (in)      An event to add  to
                                              the event queue.

     Tcl_QueuePosition   position   (in)      Where  to  add  the
                                              new  event  in  the
                                              queue:
                                              TCL_QUEUE_TAIL,
                                              TCL_QUEUE_HEAD,  or
                                              TCL_QUEUE_MARK.

DESCRIPTION

     This procedure places a window event on Tcl's internal event
     queue for eventual servicing.  It creates a Tcl_Event struc-
     ture, copies  the  event  into  that  structure,  and  calls
     Tcl_QueueEvent  to  add  the  event  to the queue.  When the
     event is eventually removed from the queue it  is  processed
     just like all window events.

     The position argument to Tk_QueueWindowEvent  has  the  same
     significance  as  for Tcl_QueueEvent;  see the documentation
     for Tcl_QueueEvent for details.

KEYWORDS

     callback, clock, handler, modal timeout
itcl2.2/html/tk4.2/Restack.3.html100666 1751 0 4451 6423554665 15310 0ustar kunkeewheel tk4.2 C API - Restack

tk4.2 C API - Restack

NAME

     Tk_RestackWindow - Change a window's position in the  stack-
     ing order

SYNOPSIS

     #include <tk.h>

     int
     Tk_RestackWindow(tkwin, aboveBelow, other)

ARGUMENTS

     Tk_Window   tkwin        (in)      Token for window to  res-
                                        tack.

     int         aboveBelow   (in)      Indicates new position of
                                        tkwin  relative to other;
                                        must be Above or Below.

     Tk_Window   other        (in)      Tkwin  will  be   reposi-
                                        tioned   just   above  or
                                        below this window.   Must
                                        be  a sibling of tkwin or
                                        a   descendant    of    a
                                        sibling.   If  NULL  then
                                        tkwin is restacked  above
                                        or below all siblings.

DESCRIPTION

     Tk_RestackWindow changes the stacking order of window  rela-
     tive  to  its  siblings.  If other is specified as NULL then
     window is repositioned at the top or bottom of its  stacking
     order,  depending  on  whether aboveBelow is Above or Below.
     If other has a non-NULL value then  window  is  repositioned
     just above or below other.

     The aboveBelow argument must have one of the symbolic values
     Above  or  Below.   Both  of these values are defined by the
     include file <X11/Xlib.h>.

KEYWORDS

     above, below, obscure, stacking order
itcl2.2/html/tk4.2/RestrictEv.3.html100666 1751 0 12360 6423554665 16024 0ustar kunkeewheel tk4.2 C API - RestrictEv

tk4.2 C API - RestrictEv

NAME

     Tk_RestrictEvents - filter and selectively delay X events

SYNOPSIS

     #include <tk.h>

     Tk_RestrictProc *
     Tk_RestrictEvents(proc, clientData, prevClientDataPtr)

ARGUMENTS

     Tk_RestrictProc   *proc                 (in)      Predicate
                                                       procedure
                                                       to call to
                                                       filter
                                                       incoming X
                                                       events.
                                                       NULL means
                                                       do     not
                                                       restrict
                                                       events  at
                                                       all.

     ClientData        clientData            (in)      Arbitrary
                                                       argument
                                                       to pass to
                                                       proc.

     ClientData        *prevClientDataPtr    (out)     Pointer to
                                                       place   to
                                                       save argu-
                                                       ment    to
                                                       previous
                                                       restrict
                                                       procedure.

DESCRIPTION

     This procedure is useful in certain situations where  appli-
     cations  are  only  prepared  to  receive  certain X events.
     After Tk_RestrictEvents is called, Tk_DoOneEvent (and  hence
     Tk_MainLoop)  will filter X input events through proc.  Proc
     indicates whether a given event is to be  processed  immedi-
     ately,  deferred  until some later time (e.g. when the event
     restriction is lifted), or discarded.  Proc is  a  procedure
     with    arguments   and   result   that   match   the   type
     Tk_RestrictProc:
          typedef Tk_RestrictAction Tk_RestrictProc(
            ClientData clientData,
            XEvent *eventPtr);

     The clientData argument is a copy of the  clientData  passed
     to  Tk_RestrictEvents;  it  may be used to provide proc with
     information it needs to filter events.  The eventPtr  points
     to  an  event  under consideration.  Proc returns a restrict
     action (enumerated type  Tk_RestrictAction)  that  indicates
     what  Tk_DoOneEvent should do with the event.  If the return
     value is TK_PROCESS_EVENT, then the event  will  be  handled
     immediately.   If  the  return value is TK_DEFER_EVENT, then
     the event will be left on the event queue for later process-
     ing.   If  the  return  value  is TK_DISCARD_EVENT, then the
     event will be removed from the  event  queue  and  discarded
     without being processed.

     Tk_RestrictEvents uses its return  value  and  prevClientDa-
     taPtr to return information about the current event restric-
     tion  procedure  (a  NULL  return  value  means  there   are
     currently  no  restrictions).   These  values may be used to
     restore the previous restriction  state  when  there  is  no
     longer any need for the current restriction.

     There are very few places where Tk_RestrictEvents is needed.
     In  most cases, the best way to restrict events is by chang-
     ing the bindings with the bind Tcl  command  or  by  calling
     Tk_CreateEventHandler and Tk_DeleteEventHandler from C.  The
     main place where Tk_RestrictEvents must be used is when per-
     forming  synchronous  actions  (for  example, if you need to
     wait for a particular event to occur on a particular  window
     but  you  don't  want  to  invoke any handlers for any other
     events).  The ``obvious'' solution in these situations is to
     call XNextEvent or XWindowEvent, but these procedures cannot
     be used because  Tk  keeps  its  own  event  queue  that  is
     separate   from   the   X   event   queue.    Instead,  call
     Tk_RestrictEvents  to   set   up   a   filter,   then   call
     Tk_DoOneEvent to retrieve the desired event(s).

KEYWORDS

     delay, event, filter, restriction
itcl2.2/html/tk4.2/SetAppName.3.html100666 1751 0 5577 6423554665 15723 0ustar kunkeewheel tk4.2 C API - SetAppName

tk4.2 C API - SetAppName

NAME

     Tk_SetAppName - Set the name of an application for  ``send''
     commands

SYNOPSIS

     #include <tk.h>

     char *
     Tk_SetAppName(tkwin, name)

ARGUMENTS

     Tk_Window   tkwin    (in)      Token for window in  applica-
                                    tion.   Used only to select a
                                    particular application.

     char        *name    (in)      Name under which to  register
                                    the application.

DESCRIPTION

     Tk_SetAppName associates a name with a given application and
     records  that association on the display containing with the
     application's main window.  After this  procedure  has  been
     invoked,  other  applications on the display will be able to
     use the send command to invoke operations  in  the  applica-
     tion.   If  name is already in use by some other application
     on the display, then a new name will be generated by append-
     ing  ``  #2''  to  name;   if  this name is also in use, the
     number will be incremented until an unused  name  is  found.
     The return value from the procedure is a pointer to the name
     actually used.

     If the application already has a name when Tk_SetAppName  is
     called, then the new name replaces the old name.

     Tk_SetAppName also adds a send command to the  application's
     interpreter,  which  can  be used to send commands from this
     application to others on  any  of  the  displays  where  the
     application has windows.

     The  application's  name  registration  persists  until  the
     interpreter  is  deleted or the send command is deleted from
     interp, at which  point  the  name  is  automatically  unre-
     gistered  and the application becomes inaccessible via send.
     The application can be  made  accessible  again  by  calling
     Tk_SetAppName.

     Tk_SetAppName is called automatically by Tk_Init, so  appli-
     cations don't normally need to call it explicitly.
     The command tk appname  provides  Tcl-level  access  to  the
     functionality of Tk_SetAppName.

KEYWORDS

     application, name, register, send command
itcl2.2/html/tk4.2/SetClass.3.html100666 1751 0 4465 6423554665 15442 0ustar kunkeewheel tk4.2 C API - SetClass

tk4.2 C API - SetClass

NAME

     Tk_SetClass, Tk_Class - set or retrieve a window's class

SYNOPSIS

     #include <tk.h>

     Tk_SetClass(tkwin, class)

     Tk_Uid
     Tk_Class(tkwin)

ARGUMENTS

     Tk_Window   tkwin    (in)      Token for window.

     char        *class   (in)      New class name for window.

DESCRIPTION

     Tk_SetClass is called to associate a class with a particular
     window.  The class string identifies the type of the window;
     all windows with the same general class of behavior (button,
     menu,  etc.)  should have the same class.  By convention all
     class names start with a capital letter, and there exists  a
     Tcl  command with the same name as each class (except all in
     lower-case) which can be used to create and manipulate  win-
     dows  of that class.  A window's class string is initialized
     to NULL when the window is created.

     For main windows, Tk automatically propagates the  name  and
     class  to  the  WM_CLASS  property  used by window managers.
     This happens either when a main window is  actually  created
     (e.g. in Tk_MakeWindowExist), or when Tk_SetClass is called,
     whichever occurs later.  If  a  main  window  has  not  been
     assigned  a class then Tk will not set the WM_CLASS property
     for the window.

     Tk_Class is a  macro  that  returns  the  current  value  of
     tkwin's class.  The value is returned as a Tk_Uid, which may
     be used just like a string pointer but also has the  proper-
     ties  of  a  unique  identifier  (see  the  manual entry for
     Tk_GetUid for details).  If tkwin has not yet been  given  a
     class, then Tk_Class will return NULL.

KEYWORDS

     class, unique identifier, window, window manager
itcl2.2/html/tk4.2/SetGrid.3.html100666 1751 0 6413 6423554665 15255 0ustar kunkeewheel tk4.2 C API - SetGrid

tk4.2 C API - SetGrid

NAME

     Tk_SetGrid, Tk_UnsetGrid - control the grid for  interactive
     resizing

SYNOPSIS

     #include <tk.h>

     Tk_SetGrid(tkwin, reqWidth, reqHeight, widthInc, heightInc)

     Tk_UnsetGrid(tkwin)

ARGUMENTS

     Tk_Window   tkwin       (in)      Token for window.

     int         reqWidth    (in)      Width in grid  units  that
                                       corresponds  to  the pixel
                                       dimension    tkwin     has
                                       requested              via
                                       Tk_GeometryRequest.

     int         reqHeight   (in)      Height in grid units  that
                                       corresponds  to  the pixel
                                       dimension    tkwin     has
                                       requested              via
                                       Tk_GeometryRequest.

     int         widthInc    (in)      Width of one grid unit, in
                                       pixels.

     int         heightInc   (in)      Height of one  grid  unit,
                                       in pixels.

DESCRIPTION

     Tk_SetGrid turns on gridded geometry management for  tkwin's
     toplevel  window  and  specifies  the  geometry of the grid.
     Tk_SetGrid is typically invoked by a widget when its setGrid
     option  is  true.   It  restricts  interactive  resizing  of
     tkwin's toplevel window so that the space allocated  to  the
     toplevel  is  equal to its requested size plus or minus even
     multiples  of  widthInc  and  heightInc.   Furthermore,  the
     reqWidth  and  reqHeight  values  are  passed  to the window
     manager so that it can report  the  window's  size  in  grid
     units  during interactive resizes.  If tkwin's configuration
     changes (e.g., the size of a grid  unit  changes)  then  the
     widget  should invoke Tk_SetGrid again with the new informa-
     tion.


     Tk_UnsetGrid cancels gridded geometry management for tkwin's
     toplevel window.

     For each toplevel window there can be at most  one  internal
     window with gridding enabled.  If Tk_SetGrid or Tk_UnsetGrid
     is invoked when some other  window  is  already  controlling
     gridding  for tkwin's toplevel, the calls for the new window
     have no effect.

     See the wm manual entry for additional information on  grid-
     ded geometry management.

KEYWORDS

     grid, window, window manager
itcl2.2/html/tk4.2/SetVisual.3.html100666 1751 0 4627 6423554665 15640 0ustar kunkeewheel tk4.2 C API - SetVisual

tk4.2 C API - SetVisual

NAME

     Tk_SetWindowVisual - change visual characteristics of window

SYNOPSIS

     #include <tk.h>

     int
     Tk_SetWindowVisual(tkwin, visual, depth, colormap)

ARGUMENTS

     Tk_Window       tkwin      (in)      Token for window.

     Visual          *visual    (in)      New visual type to  use
                                          for tkwin.

     int             depth      (in)      Number  of   bits   per
                                          pixel    desired    for
                                          tkwin.

     Colormap        colormap   (in)      New colormap for tkwin,
                                          which  must be compati-
                                          ble  with  visual   and
                                          depth.

DESCRIPTION

     When Tk creates a new  window  it  assigns  it  the  default
     visual characteristics (visual, depth, and colormap) for its
     screen.  Tk_SetWindowVisual may be called  to  change  them.
     Tk_SetWindowVisual  must  be  called  before  the window has
     actually been created in  X  (e.g.  before  Tk_MapWindow  or
     Tk_MakeWindowExist  has  been  invoked for the window).  The
     safest thing is to call Tk_SetWindowVisual immediately after
     calling  Tk_CreateWindow.  If tkwin has already been created
     before Tk_SetWindowVisual is called then it  returns  0  and
     doesn't make any changes;  otherwise it returns 1 to signify
     that the operation completed successfully.

     Note:  Tk_SetWindowVisual should not be called if  you  just
     want  to  change  a  window's  colormap without changing its
     visual or depth; call Tk_SetWindowColormap instead.

KEYWORDS

     colormap, depth, visual
itcl2.2/html/tk4.2/StrictMotif.3.html100666 1751 0 2614 6423554665 16162 0ustar kunkeewheel tk4.2 C API - StrictMotif

tk4.2 C API - StrictMotif

NAME

     Tk_StrictMotif - Return value of tk_strictMotif variable

SYNOPSIS

     #include <tk.h>

     int
     Tk_StrictMotif(tkwin)

ARGUMENTS

     Tk_Window   tkwin   (in)      Token for window.

DESCRIPTION

     This  procedure   returns   the   current   value   of   the
     tk_strictMotif  variable  in the interpreter associated with
     tkwin's application.  The value is returned  as  an  integer
     that is either 0 or 1.  1 means that strict Motif compliance
     has been requested, so anything that  is  not  part  of  the
     Motif   specification  should  be  avoided.   0  means  that
     ``Motif-like'' is good enough, and extra features  are  wel-
     come.

     This procedure uses a link to the Tcl  variable  to  provide
     much faster access to the variable's value than could be had
     by calling Tcl_GetVar.

KEYWORDS

     Motif compliance, tk_strictMotif variable
itcl2.2/html/tk4.2/Tk_Init.3.html100666 1751 0 3704 6423554665 15255 0ustar kunkeewheel tk4.2 C API - Tk_Init

tk4.2 C API - Tk_Init

NAME

     Tk_Init - add Tk to an interpreter and make a new Tk  appli-
     cation.

SYNOPSIS

     #include <tk.h>

     int
     Tk_Init(interp)

ARGUMENTS

     Tcl_Interp   *interp   (in)      Interpreter  in  which   to
                                      load  Tk.   Tk  should  not
                                      already be loaded  in  this
                                      interpreter.

DESCRIPTION

     Tk_Init is the package initialization procedure for Tk.   It
     is  normally  invoked  by  the  Tcl_AppInit procedure for an
     application or by the load command.   Tk_Init  adds  all  of
     Tk's  commands  to  interp and creates a new Tk application,
     including its main window.  If the  initialization  is  suc-
     cessful  Tk_Init  returns  TCL_OK;   if there is an error it
     returns TCL_ERROR.  Tk_Init also leaves a  result  or  error
     message in interp->result.

     If there is a variable argv in interp,  Tk_Init  treats  the
     contents  of  this variable as a list of options for the new
     Tk application.  The options may have any of the forms docu-
     mented  for the wish application (in fact, wish uses Tk_Init
     to process its command-line arguments).

KEYWORDS

     application, initialization, load, main window
itcl2.2/html/tk4.2/Tk_Main.3.html100666 1751 0 6224 6423554665 15236 0ustar kunkeewheel tk4.2 C API - Tk_Main

tk4.2 C API - Tk_Main

NAME

     Tk_Main - main program for Tk-based applications

SYNOPSIS

     #include <tk.h>

     Tk_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

     Tk_Main acts as the main program for most Tk-based  applica-
     tions.   Starting  with Tk 4.0 it is not called main anymore
     because it is part of the Tk library and having  a  function
     main  in  a  library  (particularly a shared library) causes
     problems on many systems.  Having main  in  the  Tk  library
     would also make it hard to use Tk 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 Tk_Main.  Tk_Main then does all
     the work of creating and running a wish-like application.

     When it is has finished its own initialization,  but  before
     it  processes commands, Tk_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/tk4.2/WindowId.3.html100666 1751 0 13752 6423554665 15464 0ustar kunkeewheel tk4.2 C API - WindowId

tk4.2 C API - WindowId

NAME

     Tk_WindowId,    Tk_Parent,    Tk_Display,    Tk_DisplayName,
     Tk_ScreenNumber, Tk_Screen, Tk_X, Tk_Y, Tk_Width, Tk_Height,
     Tk_Changes,   Tk_Attributes,   Tk_IsMapped,   Tk_IsTopLevel,
     Tk_ReqWidth,      Tk_ReqHeight,      Tk_InternalBorderWidth,
     Tk_Visual, Tk_Depth,  Tk_Colormap   -  retrieve  information
     from Tk's local data structure

SYNOPSIS

     #include <tk.h>

     Window
     Tk_WindowId(tkwin)

     Tk_Window
     Tk_Parent(tkwin)

     Display *
     Tk_Display(tkwin)

     char *
     Tk_DisplayName(tkwin)

     int
     Tk_ScreenNumber(tkwin)

     Screen *
     Tk_Screen(tkwin)

     int
     Tk_X(tkwin)

     int
     Tk_Y(tkwin)

     int
     Tk_Width(tkwin)

     int
     Tk_Height(tkwin)

     XWindowChanges *
     Tk_Changes(tkwin)

     XSetWindowAttributes *
     Tk_Attributes(tkwin)

     int
     Tk_IsMapped(tkwin)

     int
     Tk_IsTopLevel(tkwin)

     int
     Tk_ReqWidth(tkwin)

     int
     Tk_ReqHeight(tkwin)

     int
     Tk_InternalBorderWidth(tkwin)

     Visual *
     Tk_Visual(tkwin)

     int
     Tk_Depth(tkwin)

     Colormap
     Tk_Colormap(tkwin)

ARGUMENTS

     Tk_Window   tkwin   (in)      Token for window.

DESCRIPTION

     Tk_WindowID and the other names listed above are all  macros
     that return fields from Tk's local data structure for tkwin.
     None of these  macros  requires  any  interaction  with  the
     server;  it is safe to assume that all are fast.

     Tk_WindowId returns the X identifier for tkwin, or  NULL  if
     no X window has been created for tkwin yet.

     Tk_Parent returns Tk's  token  for  the  logical  parent  of
     tkwin.   The  parent  is  the  token that was specified when
     tkwin was created, or NULL for main windows.

     Tk_Display returns a pointer to the Xlib  display  structure
     corresponding  to  tkwin.   Tk_DisplayName  returns an ASCII
     string identifying tkwin's display.  Tk_ScreenNumber returns
     the index of tkwin's screen among all the screens of tkwin's
     display.  Tk_Screen returns a pointer to the Xlib  structure
     corresponding to tkwin's screen.

     Tk_X, Tk_Y, Tk_Width, and Tk_Height return information about
     tkwin's  location within its parent and its size.  The loca-
     tion information refers to the upper-left pixel in the  win-
     dow,  or  its  border if there is one.  The width and height
     information refers to the interior size of the  window,  not
     including  any  border.   Tk_Changes  returns a pointer to a
     structure containing all of the above information plus a few
     other   fields.   Tk_Attributes  returns  a  pointer  to  an
     XSetWindowAttributes structure describing all of the  attri-
     butes  of  the  tkwin's  window,  such as background pixmap,
     event mask, and so on (Tk keeps track of all  this  informa-
     tion  as  it  is  changed  by the application).  Note: it is
     essential  that  applications   use   Tk   procedures   like
     Tk_ResizeWindow  instead of X procedures like XResizeWindow,
     so that Tk can keep its data structures up-to-date.

     Tk_IsMapped returns a non-zero value if tkwin is mapped  and
     zero if tkwin isn't mapped.

     Tk_IsTopLevel returns a non-zero value if tkwin  is  a  top-
     level window (its X parent is the root window of the screen)
     and zero if tkwin isn't a top-level window.

     Tk_ReqWidth and Tk_ReqHeight return  information  about  the
     window's  requested  size.   These  values correspond to the
     last call to Tk_GeometryRequest for tkwin.

     Tk_InternalBorderWidth returns the width of internal  border
     that  has  been  requested  for  tkwin,  or 0 if no internal
     border was requested.  The return value is simply  the  last
     value passed to Tk_SetInternalBorder for tkwin.

     Tk_Visual,  Tk_Depth,  and  Tk_Colormap  return  information
     about  the  visual  characteristics  of a window.  Tk_Visual
     returns the visual type for the window, Tk_Depth returns the
     number  of  bits  per  pixel,  and  Tk_Colormap  returns the
     current colormap for the window.  The visual characteristics
     are  normally set from the defaults for the window's screen,
     but they may be overridden by calling Tk_SetWindowVisual.

KEYWORDS

     attributes,  colormap,  depth,  display,  height,   geometry
     manager,  identifier,  mapped,  requested size, screen, top-
     level, visual, width, window, x, y
itcl2.2/html/tk4.2/bell.n.html100666 1751 0 2136 6423554665 14723 0ustar kunkeewheel tk4.2 User Commands - bell

tk4.2 User Commands - bell

NAME

     bell - Ring a display's bell

SYNOPSIS

     bell ?-displayof window?

DESCRIPTION

     This command rings the bell on the display  for  window  and
     returns  an empty string.  If the -displayof option is omit-
     ted, the display of the application's main window is used by
     default.  The command uses the current bell-related settings
     for the display, which may be modified with programs such as
     xset.

     This command also resets the screen saver  for  the  screen.
     Some  screen  savers will ignore this, but others will reset
     so that the screen becomes visible again.

KEYWORDS

     beep, bell, ring
itcl2.2/html/tk4.2/bind.n.html100666 1751 0 66623 6423554665 14754 0ustar kunkeewheel tk4.2 User Commands - bind

tk4.2 User Commands - bind

NAME

     bind - Arrange for X events to invoke Tcl scripts

SYNOPSIS

     bind tag

     bind tag sequence

     bind tag sequence script

     bind tag sequence +script

INTRODUCTION

     The bind command associates Tcl scripts with X  events.   If
     all  three  arguments  are  specified, bind will arrange for
     script (a Tcl script) to be evaluated whenever the  event(s)
     given  by sequence occur in the window(s) identified by tag.
     If script is prefixed with a ``+'', then it is  appended  to
     any   existing   binding  for  sequence;   otherwise  script
     replaces any existing binding.  If script is an empty string
     then  the current binding for sequence is destroyed, leaving
     sequence unbound.  In all of the cases where a script  argu-
     ment is provided, bind returns an empty string.

     If sequence is specified without a script, then  the  script
     currently  bound to sequence is returned, or an empty string
     is returned if there is no binding for sequence.  If neither
     sequence nor script is specified, then the return value is a
     list whose elements are all the sequences  for  which  there
     exist bindings for tag.

     The tag argument  determines  which  window(s)  the  binding
     applies to.  If tag begins with a dot, as in .a.b.c, then it
     must be the path name for a window; otherwise it may  be  an
     arbitrary  string.   Each  window  has an associated list of
     tags, and a binding applies to a particular  window  if  its
     tag  is  among those specified for the window.  Although the
     bindtags command may be used to assign an arbitrary  set  of
     binding  tags  to a window, the default binding tags provide
     the following behavior:

          If a tag is the name of an internal window the  binding
          applies to that window.

          If the tag is the name of a toplevel window the binding
          applies  to  the  toplevel  window and all its internal
          windows.

          If the tag is the name of a class of widgets,  such  as
          Button,  the  binding  applies  to  all widgets in that
          class;

          If tag has the value all, the binding  applies  to  all
          windows in the application.

EVENT PATTERNS

     The sequence argument specifies a sequence of  one  or  more
     event  patterns,  with optional white space between the pat-
     terns.  Each event pattern may take one of three forms.   In  |
     the  simplest  case it is a single printing ASCII character,
     such as a or [.  The character may not be a space  character
     or the character <.  This form of pattern matches a KeyPress
     event for the particular character.  The second form of pat-
     tern  is longer but more general.  It has the following syn-
     tax:
          <modifier-modifier-type-detail>
     The entire event pattern is surrounded  by  angle  brackets.
     Inside  the  angle  brackets  are zero or more modifiers, an
     event type, and an extra piece of information (detail) iden-
     tifying  a  particular  button or keysym.  Any of the fields
     may be omitted, as long as at least one of type  and  detail
     is  present.  The fields must be separated by white space or
     dashes.                                                       |

     The third form of pattern is used to specify a user-defined,  |
     named virtual event.  It has the following syntax:            |
          <<name>>                                                 |
     The entire virtual event pattern  is  surrounded  by  double  |
     angle  brackets.   Inside  the  angle  brackets is the user-  |
     defined name of the virtual event.  Modifiers, such as Shift  |
     or  Control,  may  not  be  combined with a virtual event to  |
     modify it.  Bindings on  a  virtual  event  may  be  created  |
     before  the  virtual event is defined, and if the definition  |
     of a virtual event changes dynamically, all windows bound to  |
     that  virtual  event  will  respond  immediately  to the new  |
     definition.

MODIFIERS

     Modifiers consist of any of the following values:

          Control                 Mod2, M2
          Shift                   Mod3, M3
          Lock                    Mod4, M4
          Button1, B1             Mod5, M5
          Button2, B2             Meta, M
          Button3, B3             Alt
          Button4, B4             Double
          Button5, B5             Triple
          Mod1, M1

     Where more than one value is listed,  separated  by  commas,
     the  values  are equivalent.  Most of the modifiers have the
     obvious X meanings.  For example, Button1 requires that but-
     ton  1 be depressed when the event occurs.  For a binding to
     match a given event, the modifiers in the event must include
     all  of  those specified in the event pattern.  An event may
     also contain additional modifiers not specified in the bind-
     ing.   For  example,  if button 1 is pressed while the shift
     and control keys are down,  the  pattern  <Control-Button-1>
     will  match  the event, but <Mod1-Button-1> will not.  If no
     modifiers are specified, then any combination  of  modifiers
     may be present in the event.

     Meta and M refer to whichever of the M1 through M5 modifiers
     is  associated with the meta key(s) on the keyboard (keysyms
     Meta_R and Meta_L).  If there are no meta keys, or  if  they
     are  not associated with any modifiers, then Meta and M will
     not match any events.  Similarly, the Alt modifier refers to
     whichever  modifier is associated with the alt key(s) on the
     keyboard (keysyms Alt_L and Alt_R).

     The Double and Triple modifiers are a convenience for speci-
     fying  double  mouse  clicks and other repeated events. They
     cause a particular event pattern  to  be  repeated  2  or  3
     times,  and  also  place a time and space requirement on the
     sequence:  for a sequence of events to  match  a  Double  or
     Triple  pattern, all of the events must occur close together
     in time and without substantial  mouse  motion  in  between.
     For  example,  <Double-Button-1>  is  equivalent to <Button-
     1><Button-1> with the extra time and space requirement.

EVENT TYPES

     The type field may be any of the  standard  X  event  types,
     with  a few extra abbreviations.  Below is a list of all the
     valid types; where  two  names  appear  together,  they  are
     synonyms.

          ButtonPress, Button Expose             Map
          ButtonRelease       FocusIn            Motion
          Circulate           FocusOut           Property
          Colormap            Gravity            Reparent
          Configure           KeyPress, Key      Unmap
          Destroy             KeyRelease         Visibility
          Enter               Leave              Activate
          Deactivate


     The last part of a long event specification is  detail.   In
     the  case of a ButtonPress or ButtonRelease event, it is the
     number of a button (1-5).  If a button number is given, then
     only  an  event on that particular button will match;  if no
     button number is given, then an event  on  any  button  will
     match.   Note:  giving a specific button number is different
     than specifying a button modifier; in  the  first  case,  it
     refers  to  a button being pressed or released, while in the
     second it refers  to  some  other  button  that  is  already
     depressed  when  the  matching  event  occurs.   If a button
     number is given then type may be omitted:  if  will  default
     to   ButtonPress.    For   example,  the  specifier  <1>  is
     equivalent to <ButtonPress-1>.

     If the event type is KeyPress or KeyRelease, then detail may
     be  specified  in the form of an X keysym.  Keysyms are tex-
     tual specifications for particular  keys  on  the  keyboard;
     they  include  all  the  alphanumeric ASCII characters (e.g.
     ``a'' is the keysym for the  ASCII  character  ``a''),  plus
     descriptions  for  non-alphanumeric characters (``comma'' is
     the keysym for the comma character), plus  descriptions  for
     all  the  non-ASCII keys on the keyboard (``Shift_L'' is the
     keysm for the left shift key, and ``F1'' is the  keysym  for
     the  F1  function  key, if it exists).  The complete list of
     keysyms is not presented here;  it is available in  other  X
     documentation and may vary from system to system.  If neces-
     sary, you can use the %K notation described below  to  print
     out  the  keysym  name  for  a  particular key.  If a keysym
     detail is given, then the type field  may  be  omitted;   it
     will  default  to KeyPress.  For example, <Control-comma> is
     equivalent to <Control-KeyPress-comma>.

BINDING SCRIPTS AND SUBSTITUTIONS

     The script argument to bind is a Tcl script, which  will  be
     executed  whenever the given event sequence occurs.  Command
     will be executed in the same interpreter that the bind  com-
     mand  was executed in, and it will run at global level (only
     global variables will be accessible).   If  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 current event.  The replacement depends
     on  the  character  following  the %, as defined in the list
     below.  Unless otherwise indicated, the  replacement  string
     is  the  decimal  value  of the given field from the current
     event.  Some of the substitutions are only valid for certain
     types of events;  if they are used for other types of events
     the value substituted is undefined.

     %%   Replaced with a single percent.

     %#   The number of the last client request processed by  the
          server  (the  serial  field from the event).  Valid for
          all event types.

     %a   The above field from the event, formatted as a  hexade-
          cimal number.  Valid only for Configure events.

     %b   The number of the button that was pressed or  released.
          Valid only for ButtonPress and ButtonRelease events.

     %c   The count field from the event.  Valid only for  Expose
          events.

     %d   The detail field from the event.  The %d is replaced by
          a  string  identifying  the  detail.  For Enter, Leave,
          FocusIn, and FocusOut events, the string will be one of
          the following:

               NotifyAncestor          NotifyNonlinearVirtual
               NotifyDetailNone        NotifyPointer
               NotifyInferior          NotifyPointerRoot
               NotifyNonlinear         NotifyVirtual

          For events other than these, the substituted string  is
          undefined.

     %f   The focus field from the event (0 or  1).   Valid  only
          for Enter and Leave events.

     %h   The height field from the event.  Valid only  for  Con-  |
          figure and Expose events.

     %k   The keycode field  from  the  event.   Valid  only  for
          KeyPress and KeyRelease events.

     %m   The mode field from the event.  The substituted  string
          is  one  of  NotifyNormal, NotifyGrab, NotifyUngrab, or  |
          NotifyWhileGrabbed.  Valid  only  for  Enter,  FocusIn,  |
          FocusOut, and Leave events.

     %o   The override_redirect field from the event.  Valid only
          for Map, Reparent, and Configure events.

     %p   The place field from the event, substituted as  one  of
          the  strings  PlaceOnTop  or PlaceOnBottom.  Valid only
          for Circulate events.

     %q   The fully-qualified access command for  the  window  to  |
          which the event was reported.  The %q field is like %W,  |
          but it reports the  complete  namespace  path  for  the  |
          widget access command.  It should be used instead of %W  |
          as the command name for  the  widget.   Valid  for  all  |
          event types.

     %s   The state field from the event.  For ButtonPress,  But-
          tonRelease,  Enter,  KeyPress,  KeyRelease,  Leave, and
          Motion events, a decimal string  is  substituted.   For
          Visibility,  one  of  the strings VisibilityUnobscured,
          VisibilityPartiallyObscured,   and   VisibilityFullyOb-
          scured is substituted.

     %t   The time field from the event.  Valid only  for  events
          that contain a time field.

     %w   The width field from the event.  Valid only for Config-  |
          ure and Expose events.

     %x   The x field from the event.  Valid only for events con-
          taining an x field.

     %y   The y field from the event.  Valid only for events con-
          taining a y field.

     %A   Substitutes the ASCII character  corresponding  to  the
          event,  or  the  empty  string  if  the  event  doesn't
          correspond to an ASCII character (e.g.  the  shift  key
          was  pressed).   XLookupString  does  all  the  work of
          translating from  the  event  to  an  ASCII  character.
          Valid only for KeyPress and KeyRelease events.

     %B   The border_width field from the event.  Valid only  for
          Configure events.

     %E   The send_event field from the  event.   Valid  for  all
          event types.

     %K   The keysym corresponding to the event, substituted as a
          textual string.  Valid only for KeyPress and KeyRelease
          events.

     %M   The window path name for the mega-widget containing the  |
          window  which received the event.  The %M field is like  |
          %Q, but it reports a Tk window name that can be used in  |
          conjunction with commands like pack and destroy.  Valid  |
          for all event types.

     %N   The keysym corresponding to the event, substituted as a
          decimal number.  Valid only for KeyPress and KeyRelease
          events.

     %Q   The fully-qualified access command for the  mega-widget  |
          containing  the window to which the event was reported.  |
          The %Q field is like %M, but it  reports  the  complete  |
          namespace  path for the mega-widget access command.  It  |
          is useful for making generic bindings that are attached  |
          to  mega-widget  components  but  manipulate  the mega-  |
          widget at a higher  level  when  events  are  received.  |
          Valid for all event types.

     %R   The root window identifier from the event.  Valid  only
          for events containing a root field.

     %S   The subwindow window identifier from the event, format-
          ted  as  a  hexadecimal  number.  Valid only for events
          containing a subwindow field.

     %T   The type field from the event.   Valid  for  all  event
          types.

     %W   The path name of the window  to  which  the  event  was
          reported  (the window field from the event).  Valid for
          all event types.

     %X   The x_root field from the  event.   If  a  virtual-root
          window manager is being used then the substituted value
          is the corresponding x-coordinate in the virtual  root.
          Valid  only  for  ButtonPress, ButtonRelease, KeyPress,
          KeyRelease, and Motion events.

     %Y   The y_root field from the  event.   If  a  virtual-root
          window manager is being used then the substituted value
          is the corresponding y-coordinate in the virtual  root.
          Valid  only  for  ButtonPress, ButtonRelease, KeyPress,
          KeyRelease, and Motion events.

     The replacement string for a %-replacement is formatted as a
     proper  Tcl  list  element.  This means that it will be sur-
     rounded with braces if it contains spaces, or special  char-
     acters such as $ and { may be preceded by backslashes.  This
     guarantees that the string will be passed  through  the  Tcl
     parser  when the binding script is evaluated.  Most replace-
     ments are numbers or well-defined  strings  such  as  Above;
     for  these replacements no special formatting is ever neces-
     sary.  The most common case where reformatting occurs is for
     the %A substitution.  For example, if script is
          insert %A
     and the character typed is an open square bracket, then  the
     script actually executed will be
          insert \[
     This will cause the insert to receive the original  replace-
     ment string (open square bracket) as its first argument.  If
     the extra backslash hadn't been added, Tcl  would  not  have
     been able to parse the script correctly.

MULTIPLE MATCHES

     It is possible for several  bindings  to  match  a  given  X
     event.  If the bindings are associated with different tag's,
     then each of the bindings will be executed,  in  order.   By
     default,  a  binding  for the widget will be executed first,
     followed by a class binding, a binding for its toplevel, and
     an  all binding.  The bindtags command may be used to change
     this order for a particular window  or  to  associate  addi-
     tional binding tags with the window.

     The continue and break commands may be used inside a binding
     script  to  control  the processing of matching scripts.  If
     continue is invoked, then the current binding script is ter-
     minated  but  Tk  will  continue  processing binding scripts
     associated with  other  tag's.   If  the  break  command  is
     invoked within a binding script, then that script terminates
     and no other scripts will be invoked for the event.           |

     If more than one binding matches a particular event and they  |
     have  the same tag, then the most specific binding is chosen  |
     and its  script  is  evaluated.   The  following  tests  are  |
     applied,  in  order,  to determine which of several matching  |
     sequences is more  specific:   (a)  an  event  pattern  that  |
     specifies a specific button or key is more specific than one  |
     that doesn't; (b) a longer sequence (in terms of  number  of  |
     events  matched)  is  more specific than a shorter sequence;  |
     (c) if the modifiers specified in one pattern are  a  subset  |
     of  the  modifiers in another pattern, then the pattern with  |
     more modifiers is more specific.  (d) a virtual event  whose  |
     physical  pattern matches the sequence is less specific than  |
     the same physical pattern that is not associated with a vir-  |
     tual  event.   (e) given a sequence that matches two or more  |
     virtual events, one of the virtual events  will  be  chosen,  |
     but the order is undefined.                                   |

     If the matching sequences contain more than one event,  then  |
     tests  (c)-(e)  are  applied  in  order from the most recent  |
     event to the least recent event in the sequences.  If  these  |
     tests  fail  to  determine  a winner, then the most recently  |
     registered sequence is the winner.                            |

     If there are two (or more)  virtual  events  that  are  both  |
     triggered  by  the  same sequence, and both of those virtual  |
     events are bound to the same window tag, then  only  one  of  |
     the  virtual events will be triggered, and it will be picked  |
     at random:                                                    |
          event add <<Paste>> <Control-y>                          |
          event add <<Paste>> <Button-2>                           |
          event add <<Scroll>> <Button-2>                          |
          bind Entry <<Paste>> {puts Paste}                        |
          bind Entry <<Scroll>> {puts Scroll}                      |
     If the user types Control-y, the <<Paste>> binding  will  be  |
     invoked, but if the user presses button 2 then one of either  |
     the <<Paste>> or the <<Scroll>> bindings  will  be  invoked,  |
     but exactly which one gets invoked is undefined.

     If an X event does not match any of the  existing  bindings,
     then  the  event  is  ignored.   An  unbound  event  is  not
     considered to be an error.

MULTI-EVENT SEQUENCES AND IGNORED EVENTS

     When a sequence specified in a bind  command  contains  more
     than one event pattern, then its script is executed whenever
     the recent events (leading up to and including  the  current
     event)  match  the given sequence.  This means, for example,
     that  if  button  1  is  clicked  repeatedly  the   sequence
     <Double-ButtonPress-1>  will match each button press but the
     first.  If extraneous events  that  would  prevent  a  match
     occur in the middle of an event sequence then the extraneous
     events are ignored unless they are KeyPress  or  ButtonPress
     events.   For  example,  <Double-ButtonPress-1> will match a
     sequence of presses of button 1, even though there  will  be
     ButtonRelease  events  (and  possibly Motion events) between
     the ButtonPress events.  Furthermore, a KeyPress  event  may
     be  preceded  by  any  number  of  other KeyPress events for
     modifier keys without the modifier keys preventing a  match.
     For example, the event sequence aB will match a press of the
     a key, a release of the a key, a press of the Shift key, and
     a press of the b key:  the press of Shift is ignored because
     it is a modifier key.  Finally,  if  several  Motion  events
     occur  in  a  row, only the last one is used for purposes of
     matching binding sequences.

ERRORS

     If an error occurs in executing the  script  for  a  binding
     then the bgerror mechanism is used to report the error.  The
     bgerror command will be executed at  global  level  (outside
     the context of any Tcl procedure).

SEE ALSO

     bgerror

KEYWORDS

     form, manual
itcl2.2/html/tk4.2/bindtags.n.html100666 1751 0 7530 6423554666 15604 0ustar kunkeewheel tk4.2 User Commands - bindtags

tk4.2 User Commands - bindtags

NAME

     bindtags - Determine which bindings apply to a  window,  and
     order of evaluation

SYNOPSIS

     bindtags window ?tagList?

DESCRIPTION

     When a binding is created with the bind command, it is asso-
     ciated  either  with  a  particular window such as .a.b.c, a
     class name such as Button, the keyword  all,  or  any  other
     string.   All  of these forms are called binding tags.  Each
     window contains a list of binding tags  that  determine  how
     events  are  processed for the window.  When an event occurs
     in a window, it is applied to each of the window's  tags  in
     order:  for each tag, the most specific binding that matches
     the given tag and event is executed.  See the  bind  command
     for more information on the matching process.

     By default, each window has four binding tags consisting  of
     the name of the window, the window's class name, the name of
     the window's nearest toplevel ancestor,  and  all,  in  that
     order.   Toplevel  windows  have only three tags by default,
     since the toplevel name is the same as that of  the  window.
     The bindtags command allows the binding tags for a window to
     be read and modified.

     If bindtags is invoked with  only  one  argument,  then  the
     current  set  of  binding  tags  for window is returned as a
     list.  If the tagList argument  is  specified  to  bindtags,
     then  it  must  be  a  proper  list; the tags for window are
     changed to the  elements  of  the  list.   The  elements  of
     tagList may be arbitrary strings;  however, any tag starting
     with a dot is treated as the name of a window;  if no window
     by  that name exists at the time an event is processed, then
     the tag is ignored for that event.  The order  of  the  ele-
     ments  in  tagList  determines  the  order  in which binding
     scripts are executed in response to  events.   For  example,
     the command
          bindtags .b {all . Button .b}
     reverses  the  order  in  which  binding  scripts  will   be
     evaluated  for  a  button  named .b so that all bindings are
     invoked first,  following  by  bindings  for  .b's  toplevel
     (``.''),  followed  by  class bindings, followed by bindings
     for .b.

     The bindtags command may  be  used  to  introduce  arbitrary
     additional  binding tags for a window, or to remove standard
     tags.  For example, the command
          bindtags .b {.b TrickyButton . all}
     replaces the Button tag  for  .b  with  TrickyButton.   This
     means  that  the  default widget bindings for buttons, which
     are associated with the Button tag, will no longer apply  to
     .b,  but  any bindings associated with TrickyButton (perhaps
     some new button behavior) will apply.

SEE ALSO

     bind

KEYWORDS

     binding, event, tag
itcl2.2/html/tk4.2/bitmap.n.html100666 1751 0 12514 6423554666 15303 0ustar kunkeewheel tk4.2 User Commands - bitmap

tk4.2 User Commands - bitmap

NAME

     bitmap - Images that display two colors

SYNOPSIS

     image create bitmap ?name? ?options?

DESCRIPTION

     A bitmap is an image whose pixels can display either of  two
     colors or be transparent.  A bitmap image is defined by four
     things:  a background color, a  foreground  color,  and  two
     bitmaps,  called  the source and the mask.  Each of the bit-
     maps specifies 0/1 values for a rectangular array of pixels,
     and the two bitmaps must have the same dimensions.  For pix-
     els where the mask is zero, the image displays nothing, pro-
     ducing  a  transparent  effect.  For other pixels, the image
     displays the foreground color if the source data is one  and
     the background color if the source data is zero.

CREATING BITMAPS

     Like all images, bitmaps are created using the image  create
     command.  Bitmaps support the following options:

     -background color
          Specifies a background color for the image  in  any  of
          the  standard  ways  accepted by Tk.  If this option is
          set to an empty string then the background pixels  will
          be  transparent.   This effect is achieved by using the
          source bitmap as the mask bitmap, ignoring any  - mask-
          data or -maskfile options.

     -data string
          Specifies the  contents  of  the  source  bitmap  as  a
          string.   The  string  must adhere to X11 bitmap format
          (e.g., as generated by the bitmap  program).   If  both
          the  - data  and -file options are specified, the -data
          option takes precedence.

     -file name
          name gives the name of a file whose contents define the
          source bitmap.  The file must adhere to X11 bitmap for-
          mat (e.g., as generated by the bitmap program).

     -foreground color
          Specifies a foreground color for the image  in  any  of
          the standard ways accepted by Tk.

     -maskdata string
          Specifies the contents of the mask as  a  string.   The
          string  must adhere to X11 bitmap format (e.g., as gen-
          erated by the bitmap program).  If both the  - maskdata
          and  - maskfile  options  are  specified, the -maskdata
          option takes precedence.

     -maskfile name
          name gives the name of a file whose contents define the
          mask.  The file must adhere to X11 bitmap format (e.g.,
          as generated by the bitmap program).

IMAGE COMMAND

     When a bitmap image is created, Tk also creates a  new  com-
     mand  whose name is the same as the image.  This command may
     be used to invoke various operations on the image.   It  has
     the following general form:
          imageName option ?arg arg ...?
     Option and the args determine the exact behavior of the com-
     mand.   The  following  commands  are  possible  for  bitmap
     images:

     imageName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the image create bitmap command.

     imageName configure ?option? ?value option value ...?
          Query or  modify  the  configuration  options  for  the
          image.   If  no  option  is  specified,  returns a list
          describing all of the available options  for  imageName
          (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
          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 image create bitmap  com-
          mand.

KEYWORDS

     bitmap, image
itcl2.2/html/tk4.2/button.n.html100666 1751 0 22135 6423554666 15342 0ustar kunkeewheel tk4.2 User Commands - button

tk4.2 User Commands - button

NAME

     button - Create and manipulate button widgets

SYNOPSIS

     button pathName ?options?

STANDARD OPTIONS

     -activebackground              -cursor         -highlightthickness-takefocus
     -activeforeground              -disabledforeground-image-text
     -anchor         -font          -justify        -textvariable
     -background     -foreground    -padx           -underline
     -bitmap         -highlightbackground           -pady-wraplength
     -borderwidth    -highlightcolor                -relief

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

WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-command
     Database Name:  command
     Database Class: Command

          Specifies a Tcl command to associate with  the  button.
          This  command  is typically invoked when mouse button 1
          is released over the button window.

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

          Specifies a desired height for the button.  If an image
          or  bitmap  is  being  displayed in the button then the
          value is in screen units (i.e. any of the forms accept-
          able to Tk_GetPixels); for text it is in lines of text.
          If this option isn't specified,  the  button's  desired
          height is computed from the size of the image or bitmap
          or text being displayed in it.

     Command-Line Name:-state
     Database Name:  state
     Database Class: State

          Specifies one of three states for the button:   normal,
          active,  or  disabled.   In  normal state the button is
          displayed using the foreground and background  options.
          The  active state is typically used when the pointer is
          over  the  button.   In  active  state  the  button  is
          displayed  using  the  activeForeground and activeBack-
          ground options.  Disabled state means that  the  button
          should  be  insensitive:   the  default  bindings  will
          refuse to activate the widget  and  will  ignore  mouse
          button  presses.   In this state the disabledForeground
          and background options  determine  how  the  button  is
          displayed.

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

          Specifies a desired width for the button.  If an  image
          or  bitmap  is  being  displayed in the button then the
          value is in screen units (i.e. any of the forms accept-
          able  to  Tk_GetPixels);  for text it is in characters.
          If this option isn't specified,  the  button's  desired
          width  is computed from the size of the image or bitmap
          or text being displayed in it.

DESCRIPTION

     The button command creates a new window (given by the  path-
     Name  argument)  and  makes  it into a button widget.  Addi-
     tional options, described above, may  be  specified  on  the
     command  line or in the option database to configure aspects
     of the button such as its colors, font,  text,  and  initial
     relief.   The  button 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 button is a widget that displays a textual string,  bitmap
     or  image.  If text is displayed, it must all be in a single
     font, but it can occupy multiple lines on the screen (if  it
     contains  newlines or if wrapping occurs because of the wra-
     pLength option) and one of the characters may optionally  be
     underlined  using  the  underline  option.   It  can display
     itself in either of three different ways, according  to  the
     state  option;  it  can be made to appear raised, sunken, or
     flat; and it can be made to flash.  When a user invokes  the
     button  (by pressing mouse button 1 with the cursor over the
     button), then the Tcl command  specified  in  the  - command
     option is invoked.

WIDGET COMMAND

     The button 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 button widg-
     ets:

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

     pathName flash
          Flash the button.  This is accomplished by redisplaying
          the  button  several  times, alternating between active
          and normal colors.  At the end of the flash the  button
          is  left  in  the  same normal/active state as when the
          command was invoked.  This command is  ignored  if  the
          button's state is disabled.

     pathName invoke
          Invoke the Tcl command associated with the  button,  if
          there  is  one.   The  return value is the return value
          from the Tcl command, or an empty string if there is no
          command  associated  with  the button.  This command is
          ignored if the button's state is disabled.

DEFAULT BINDINGS

     Tk automatically creates class  bindings  for  buttons  that
     give them the following default behavior:

     [1]  A button activates whenever the mouse  passes  over  it
          and deactivates whenever the mouse leaves the button.

     [2]  A button's relief is changed to sunken  whenever  mouse
          button  1 is pressed over the button, and the relief is
          restored to its original value when button 1  is  later
          released.

     [3]  If mouse button 1 is pressed over a  button  and  later
          released  over the button, the button is invoked.  How-
          ever, if the mouse is not over the button when button 1
          is released, then no invocation occurs.

     [4]  When a button has the input focus, the space key causes
          the button to be invoked.

     If the button's state is disabled then  none  of  the  above
     actions occur:  the button is completely non-responsive.

     The behavior of buttons can be changed by defining new bind-
     ings for individual widgets or by redefining the class bind-
     ings.

KEYWORDS

     button, widget
itcl2.2/html/tk4.2/canvas.n.html100666 1751 0 263165 6423554666 15334 0ustar kunkeewheel tk4.2 User Commands - canvas

tk4.2 User Commands - canvas

NAME

     canvas - Create and manipulate canvas widgets

SYNOPSIS

     canvas pathName ?options?

STANDARD OPTIONS

     -background     -highlightthickness            -insertwidth-takefocus
     -borderwidth    -insertbackground              -relief-xscrollcommand
     -cursor         -insertborderwidth             -selectbackground-yscrollcommand
     -highlightbackground           -insertofftime  -selectborderwidth
     -highlightcolor -insertontime  -selectforeground

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

WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-closeenough
     Database Name:  closeEnough
     Database Class: CloseEnough

          Specifies a floating-point value indicating  how  close
          the  mouse  cursor must be to an item before it is con-
          sidered to be ``inside'' the item.  Defaults to 1.0.

     Command-Line Name:-confine
     Database Name:  confine
     Database Class: Confine

          Specifies a boolean value that indicates whether or not
          it should be allowable to set the canvas's view outside
          the  region  defined  by  the  scrollRegion   argument.
          Defaults  to  true,  which  means that the view will be
          constrained within the scroll region.

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

          Specifies a  desired  window  height  that  the  canvas
          widget  should  request from its geometry manager.  The
          value may be specified in any of the forms described in
          the COORDINATES section below.

     Command-Line Name:-scrollregion
     Database Name:  scrollRegion
     Database Class: ScrollRegion

          Specifies a list with four coordinates  describing  the
          left,   top,   right,   and  bottom  coordinates  of  a
          rectangular region.  This region is used for  scrolling
          purposes  and  is  considered to be the boundary of the
          information in the canvas.  Each of the coordinates may
          be  specified  in any of the forms given in the COORDI-
          NATES section below.

     Command-Line Name:-width
     Database Name:  width
     Database Class: width

          Specifies a desired window width that the canvas widget
          should  request  from  its geometry manager.  The value
          may be specified in any of the forms described  in  the
          COORDINATES section below.

     Command-Line Name:-xscrollincrement
     Database Name:  xScrollIncrement
     Database Class: ScrollIncrement

          Specifies an increment for horizontal scrolling, in any
          of  the usual forms permitted for screen distances.  If
          the value of this option is greater than zero, the hor-
          izontal  view in the window will be constrained so that
          the canvas x coordinate at the left edge of the  window
          is always an even multiple of xScrollIncrement;  furth-
          ermore, the units for scrolling (e.g.,  the  change  in
          view  when the left and right arrows of a scrollbar are
          selected) will also be xScrollIncrement.  If the  value
          of this option is less than or equal to zero, then hor-
          izontal scrolling is unconstrained.

     Command-Line Name:-yscrollincrement
     Database Name:  yScrollIncrement
     Database Class: ScrollIncrement

          Specifies an increment for vertical scrolling,  in  any
          of  the usual forms permitted for screen distances.  If
          the value of this option  is  greater  than  zero,  the
          vertical view in the window will be constrained so that
          the canvas y coordinate at the top edge of  the  window
          is always an even multiple of yScrollIncrement;  furth-
          ermore, the units for scrolling (e.g.,  the  change  in
          view  when the top and bottom arrows of a scrollbar are
          selected) will also be yScrollIncrement.  If the  value
          of  this  option  is  less  than or equal to zero, then
          vertical scrolling is unconstrained.

INTRODUCTION

     The canvas command creates a new window (given by the  path-
     Name   argument)   and   makes  it  into  a  canvas  widget.
     Additional options, described above, may be specified on the
     command  line or in the option database to configure aspects
     of the canvas such as its colors and 3-D relief.  The canvas
     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.

     Canvas widgets  implement  structured  graphics.   A  canvas
     displays  any number of items, which may be things like rec-
     tangles, circles, lines, and text.  Items may be manipulated
     (e.g.  moved  or  re-colored) and commands may be associated
     with items in much the same way that the bind command allows
     commands  to be bound to widgets.  For example, a particular
     command may be associated with the <Button-1> event so  that
     the command is invoked whenever button 1 is pressed with the
     mouse cursor over an item.  This means that items in a  can-
     vas  can  have behaviors defined by the Tcl scripts bound to
     them.

DISPLAY LIST

     The items in a canvas are ordered for purposes  of  display,
     with  the  first  item  in  the display list being displayed
     first, followed by the next item in the  list,  and  so  on.
     Items  later in the display list obscure those that are ear-
     lier in the display list and are sometimes  referred  to  as
     being  ``on  top''  of  earlier  items.   When a new item is
     created it is placed at the end of the display list, on  top
     of  everything  else.   Widget  commands  may be used to re-
     arrange the order of the display list.

ITEM IDS AND TAGS

     Items in a canvas widget may be named in either of two ways:
     by  id or by tag.  Each item has a unique identifying number
     which is assigned to that item when it is created.   The  id
     of  an  item  never changes and id numbers are never re-used
     within the lifetime of a canvas widget.

     Each item may also have any number of tags  associated  with
     it.   A  tag is just a string of characters, and it may take
     any form except that of an integer.  For  example,  ``x123''
     is  OK  but  ``123''  isn't.  The same tag may be associated
     with many different items.  This is commonly done  to  group
     items   in  various  interesting  ways;   for  example,  all
     selected items might be given the tag ``selected''.

     The tag all is implicitly associated with every item in  the
     canvas;   it  may  be  used  to invoke operations on all the
     items in the canvas.


     The tag current is managed automatically by Tk;  it  applies
     to  the  current item, which is the topmost item whose drawn
     area covers the position of the mouse cursor.  If the  mouse
     is  not in the canvas widget or is not over an item, then no
     item has the current tag.

     When specifying items in  canvas  widget  commands,  if  the
     specifier  is  an integer then it is assumed to refer to the
     single item with that  id.   If  the  specifier  is  not  an
     integer,  then it is assumed to refer to all of the items in
     the canvas that have a tag matching the specifier.  The sym-
     bol  tagOrId  is  used  below  to  indicate that an argument
     specifies either an id that selects a single item or  a  tag
     that  selects zero or more items.  Some widget commands only
     operate on a single item at a time;  if tagOrId is specified
     in a way that names multiple items, then the normal behavior
     is for the command to use the first (lowest) of these  items
     in  the  display  list  that  is  suitable  for the command.
     Exceptions are noted  in  the  widget  command  descriptions
     below.

COORDINATES

     All coordinates related to canvases are stored as  floating-
     point  numbers.   Coordinates and distances are specified in
     screen units, which are  floating-point  numbers  optionally
     followed  by  one  of several letters.  If no letter is sup-
     plied then the distance is in pixels.  If the  letter  is  m
     then the distance is in millimeters on the screen;  if it is
     c then the distance is in centimeters; i means inches, and p
     means  printers  points  (1/72  inch).  Larger y-coordinates
     refer to points lower on the screen;   larger  x-coordinates
     refer to points farther to the right.

TRANSFORMATIONS

     Normally the origin of the canvas coordinate  system  is  at
     the  upper-left  corner of the window containing the canvas.
     It is possible to adjust the origin of the canvas coordinate
     system  relative to the origin of the window using the xview
     and yview widget  commands;   this  is  typically  used  for
     scrolling.   Canvases  do not support scaling or rotation of
     the canvas coordinate system relative to the window  coordi-
     nate system.

     Individual items may be moved or scaled  using  widget  com-
     mands described below, but they may not be rotated.

INDICES

     Text items support the notion of an  index  for  identifying
     particular  positions within the item.  Indices are used for
     commands such as inserting text, deleting a range of charac-
     ters,  and  setting the insertion cursor position.  An index
     may be specified in any of a number of ways,  and  different
     types  of  items  may support different forms for specifying
     indices.  Text items support  the  following  forms  for  an
     index;  if you define new types of text-like items, it would
     be advisable to support as many of these forms as practical.
     Note  that  it  is  possible  to refer to the character just
     after the last one in the text item;  this is necessary  for
     such tasks as inserting new text at the end of the item.

     number    A  decimal  number  giving  the  position  of  the
               desired  character within the text item.  0 refers
               to the first character, 1 to the  next  character,
               and  so on.  A number less than 0 is treated as if
               it were zero, and a number greater than the length
               of the text item is treated as if it were equal to
               the length of the text item.

     end       Refers to the character just after the last one in
               the  item (same as the number of characters in the
               item).

     insert    Refers to the  character  just  before  which  the
               insertion cursor is drawn in this item.

     sel.first Refers to the  first  selected  character  in  the
               item.   If  the  selection isn't in this item then
               this form is illegal.

     sel.last  Refers to the last selected character in the item.
               If the selection isn't in this item then this form
               is illegal.

     @x,y      Refers to the character at the point  given  by  x
               and  y, where x and y are specified in the coordi-
               nate system of the canvas.  If x and y lie outside
               the  coordinates  covered  by  the text item, then
               they refer to the first or last character  in  the
               line that is closest to the given point.

WIDGET COMMAND

     The canvas 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 widget commands are possible for canvas
     widgets:

     pathName addtag tag searchSpec ?arg arg ...?
          For each item that meets the constraints  specified  by
          searchSpec  and  the  args, add tag to the list of tags
          associated with the item if it isn't already present on
          that  list.   It is possible that no items will satisfy
          the constraints given by searchSpec and args, in  which
          case  the  command has no effect.  This command returns
          an empty string as result.  SearchSpec  and  arg's  may
          take any of the following forms:

          above tagOrId
               Selects the item just after (above) the one  given
               by  tagOrId  in  the  display  list.   If  tagOrId
               denotes more than one item, then  the  last  (top-
               most) of these items in the display list is used.

          all  Selects all the items in the canvas.

          below tagOrId
               Selects the item just before (below) the one given
               by  tagOrId  in  the  display  list.   If  tagOrId
               denotes  more  than  one  item,  then  the   first
               (lowest)  of  these  items  in the display list is
               used.

          closest x y ?halo? ?start?
               Selects the item closest to the point given  by  x
               and  y.   If  more  than  one  item is at the same
               closest  distance  (e.g.  two  items  overlap  the
               point), then the top-most of these items (the last
               one in the display list)  is  used.   If  halo  is
               specified,  then  it must be a non-negative value.
               Any item closer than halo to  the  point  is  con-
               sidered  to overlap it.  The start argument may be
               used to step circularly through  all  the  closest
               items.   If  start  is specified, it names an item
               using a tag or id (if by tag, it selects the first
               item  in  the  display  list  with the given tag).
               Instead of selecting  the  topmost  closest  item,
               this  form  will  select  the topmost closest item
               that is below start in the display  list;   if  no
               such item exists, then the selection behaves as if
               the start argument had not been specified.

          enclosed x1 y1 x2 y2
               Selects all the items completely  enclosed  within
               the  rectangular  region  given by x1, y1, x2, and
               y2.  X1 must be no greater then x2 and y1 must  be
               no greater than y2.

          overlapping x1 y1 x2 y2
               Selects all the items that overlap or are enclosed
               within the rectangular region given by x1, y1, x2,
               and y2.  X1 must be no greater then x2 and y1 must
               be no greater than y2.

          withtag tagOrId
               Selects all the items given by tagOrId.

     pathName bbox tagOrId ?tagOrId tagOrId ...?
          Returns a list with four elements giving an approximate
          bounding  box  for  all  the items named by the tagOrId
          arguments.  The list has the form ``x1 y1 x2 y2''  such
          that  the  drawn  areas  of  all the named elements are
          within the region bounded by x1 on the left, x2 on  the
          right, y1 on the top, and y2 on the bottom.  The return
          value may overestimate the actual bounding box by a few
          pixels.  If no items match any of the tagOrId arguments
          or if the matching  items  have  empty  bounding  boxes
          (i.e.  they  have  nothing  to  display)  then an empty
          string is returned.

     pathName bind tagOrId ?sequence? ?command?
          This command associates  command  with  all  the  items
          given  by tagOrId such that whenever the event sequence
          given by sequence occurs for one of the items the  com-
          mand  will  be invoked.  This widget command is similar
          to the bind command except that it operates on items in
          a  canvas  rather  than  entire  widgets.  See the bind
          manual entry for complete  details  on  the  syntax  of
          sequence  and  the  substitutions  performed on command
          before invoking it.  If  all  arguments  are  specified
          then  a  new binding is created, replacing any existing
          binding for the same sequence and tagOrId (if the first
          character  of command is ``+'' then command augments an
          existing binding rather than replacing  it).   In  this
          case  the  return value is an empty string.  If command
          is omitted then the command returns the command associ-
          ated  with  tagOrId  and  sequence  (an error occurs if
          there  is  no  such  binding).   If  both  command  and
          sequence are omitted then the command returns a list of
          all the sequences for which bindings have been  defined
          for tagOrId.

          The only events for which bindings may be specified are
          those related to the mouse and keyboard, such as Enter,
          Leave, ButtonPress, Motion, and KeyPress.  The handling
          of  events in canvases uses the current item defined in
          ITEM IDS  AND  TAGS  above.   Enter  and  Leave  events
          trigger for an item when it becomes the current item or
          ceases to be the current item;  note that these  events
          are  different than Enter and Leave events for windows.
          Mouse-related events are directed to the current  item,
          if  any.   Keyboard-related  events are directed to the
          focus item, if any (see the focus widget command  below
          for more on this).

          It is possible for multiple bindings to match a partic-
          ular  event.   This  could  occur,  for example, if one
          binding is associated with the item's id and another is
          associated  with  one  of  the  item's tags.  When this
          occurs, all of the matching bindings  are  invoked.   A
          binding  associated  with the all tag is invoked first,
          followed by one binding for each of the item's tags (in
          order),  followed  by  a  binding  associated  with the
          item's id.  If there are multiple matching bindings for
          a  single  tag,  then only the most specific binding is
          invoked.  A continue command in a binding  script  ter-
          minates  that  script,  and  a break command terminates
          that script and skips any  remaining  scripts  for  the
          event, just as for the bind command.

          If bindings have been created for a canvas window using
          the  bind command, then they are invoked in addition to
          bindings created for the canvas's items using the  bind
          widget command.  The bindings for items will be invoked
          before any of the bindings for the window as a whole.

     pathName canvasx screenx ?gridspacing?
          Given a window x-coordinate in the canvas screenx, this
          command   returns   the  canvas  x-coordinate  that  is
          displayed at that location.  If gridspacing  is  speci-
          fied,  then  the  canvas  coordinate  is rounded to the
          nearest multiple of gridspacing units.

     pathName canvasy screeny ?gridspacing?
          Given a window y-coordinate in the canvas screeny  this
          command   returns   the  canvas  y-coordinate  that  is
          displayed at that location.  If gridspacing  is  speci-
          fied,  then  the  canvas  coordinate  is rounded to the
          nearest multiple of gridspacing units.

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

     pathName coords tagOrId ?x0 y0 ...?
          Query or modify the coordinates that  define  an  item.
          If no coordinates are specified, this command returns a
          list whose elements are the  coordinates  of  the  item
          named  by  tagOrId.  If coordinates are specified, then
          they replace the  current  coordinates  for  the  named
          item.   If  tagOrId  refers to multiple items, then the
          first one in the display list is used.

     pathName create type x y ?x y ...? ?option value ...?
          Create a new item in pathName of type type.  The  exact
          format of the arguments after type depends on type, but
          usually they consist of the coordinates for one or more
          points,  followed  by  specifications  for zero or more
          item options.  See the subsections on  individual  item
          types  below  for  more  on the syntax of this command.
          This command returns the id for the new item.

     pathName dchars tagOrId first ?last?
          For each item given by tagOrId, delete  the  characters
          in  the  range  given by first and last, inclusive.  If
          some of the items given by tagOrId don't  support  text
          operations,  then they are ignored.  First and last are
          indices of characters within the item(s)  as  described
          in  INDICES  above.  If last is omitted, it defaults to
          first.  This command returns an empty string.

     pathName delete ?tagOrId tagOrId ...?
          Delete each of the items given  by  each  tagOrId,  and
          return an empty string.

     pathName dtag tagOrId ?tagToDelete?
          For each of the items given by tagOrId, delete the  tag
          given  by tagToDelete from the list of those associated
          with the item.  If an item doesn't have the tag  tagTo-
          Delete  then the item is unaffected by the command.  If
          tagToDelete is omitted then  it  defaults  to  tagOrId.
          This command returns an empty string.

     pathName find searchCommand ?arg arg ...?
          This command returns a list consisting of all the items
          that  meet  the  constraints specified by searchCommand
          and arg's.  SearchCommand and  args  have  any  of  the
          forms accepted by the addtag command.

     pathName focus ?tagOrId?
          Set the keyboard focus for the  canvas  widget  to  the
          item  given  by  tagOrId.  If tagOrId refers to several
          items, then the focus is set to the first such item  in
          the  display  list  that supports the insertion cursor.
          If tagOrId doesn't refer to any items, or  if  none  of
          them support the insertion cursor, then the focus isn't
          changed.  If tagOrId is an empty string, then the focus
          item  is  reset  so  that  no  item  has the focus.  If
          tagOrId is not specified then the command  returns  the
          id  for  the  item  that currently has the focus, or an
          empty string if no item has the focus.

          Once the focus has been set to an item, the  item  will
          display  the  insertion  cursor and all keyboard events
          will be directed to that item.  The focus item within a
          canvas and the focus window on the screen (set with the
          focus command) are totally independent:  a  given  item
          doesn't  actually  have  the input focus unless (a) its
          canvas is the focus window and  (b)  the  item  is  the
          focus  item  within  the  canvas.   In most cases it is
          advisable to follow the focus widget command  with  the
          focus command to set the focus window to the canvas (if
          it wasn't there already).

     pathName gettags tagOrId
          Return a list whose elements are  the  tags  associated
          with  the  item given by tagOrId.  If tagOrId refers to
          more than one item, then the tags are returned from the
          first  such  item  in  the  display  list.   If tagOrId
          doesn't refer to any items, or if the item contains  no
          tags, then an empty string is returned.

     pathName icursor tagOrId index
          Set the  position  of  the  insertion  cursor  for  the
          item(s)  given  by tagOrId to just before the character
          whose position is given by index.  If some  or  all  of
          the  items  given by tagOrId don't support an insertion
          cursor then this command has no effect  on  them.   See
          INDICES  above for a description of the legal forms for
          index.  Note:  the insertion cursor is  only  displayed
          in  an  item  if  that  item currently has the keyboard
          focus (see the widget command focus,  below),  but  the
          cursor  position  may be set even when the item doesn't
          have the focus.  This command returns an empty string.

     pathName index tagOrId index
          This command returns a decimal string giving the numer-
          ical  index  within  tagOrId  corresponding  to  index.
          Index gives a textual description of the desired  posi-
          tion  as  described in INDICES above.  The return value
          is guaranteed to lie between 0 and the number of  char-
          acters  within  the item, inclusive.  If tagOrId refers
          to multiple items, then the index is processed  in  the
          first  of these items that supports indexing operations
          (in display list order).

     pathName insert tagOrId beforeThis string
          For each of the items given by  tagOrId,  if  the  item
          supports  text  insertion  then string is inserted into
          the item's text just before the character  whose  index
          is beforeThis.  See INDICES above for information about
          the forms allowed for beforeThis.  This command returns
          an empty string.

     pathName itemcget tagOrId option
          Returns the current value of the  configuration  option
          for  the  item  given  by tagOrId whose name is option.
          This command is similar  to  the  cget  widget  command
          except that it applies to a particular item rather than
          the widget as a whole.  Option  may  have  any  of  the
          values  accepted  by the create widget command when the
          item was created.  If tagOrId is a tag that  refers  to
          more  than  one  item,  the first (lowest) such item is
          used.

     pathName itemconfigure tagOrId  ?option?  ?value?  ?option  value
          This command is similar to the configure widget command
          except that it modifies item-specific options  for  the
          items given by tagOrId instead of modifying options for
          the overall canvas widget.  If no option is  specified,
          returns  a list describing all of the available options
          for   the   first   item   given   by   tagOrId    (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  each  of  the  items  given  by
          tagOrId;   in  this  case  the command returns an empty
          string.  The options and values are the same  as  those
          permissible  in  the  create  widget  command  when the
          item(s) were created; see the sections describing indi-
          vidual  item  types  below  for  details  on  the legal
          options.

     pathName lower tagOrId ?belowThis?
          Move all of the items given by tagOrId to a  new  posi-
          tion  in the display list just before the item given by
          belowThis.  If tagOrId refers to  more  than  one  item
          then  all are moved but the relative order of the moved
          items will not be changed.  BelowThis is a tag  or  id;
          if  it  refers  to  more  than  one item then the first
          (lowest) of these items in the display list is used  as
          the  destination  location  for  the moved items.  This
          command returns an empty string.

     pathName move tagOrId xAmount yAmount
          Move each of the items given by tagOrId in  the  canvas
          coordinate  space by adding xAmount to the x-coordinate
          of each point associated with the item and  yAmount  to
          the  y-coordinate  of  each  point  associated with the
          item.  This command returns an empty string.

     pathName postscript ?option value option value ...?
          Generate a Postscript representation for part or all of
          the  canvas.  If the -file option is specified then the
          Postscript is written to a file and an empty string  is
          returned;   otherwise the Postscript is returned as the
          result of the command.  The Postscript  is  created  in
          Encapsulated  Postscript  form using version 3.0 of the
          Document Structuring  Conventions.   Note:  by  default
          Postscript  is  only  generated  for  information  that
          appears in the canvas's window on the screen.   If  the
          canvas is freshly created it may still have its initial
          size of  1x1  pixel  so  nothing  will  appear  in  the
          Postscript.   To  get around this problem either invoke
          the "update" command to wait for the canvas  window  to
          reach  its  final  size,  or  else use the -width and -
          height options to specify the area  of  the  canvas  to
          print.   The  option-value argument pairs provide addi-
          tional  information  to  control  the   generation   of
          Postscript.  The following options are supported:

          -colormap varName
               VarName must be the name of an array variable that
               specifies   a   color   mapping   to  use  in  the
               Postscript.  Each element of varName must  consist
               of Postscript code to set a particular color value
               (e.g. ``1.0 1.0 0.0 setrgbcolor'').  When  output-
               ting  color  information  in  the  Postscript,  Tk
               checks to see if there is an  element  of  varName
               with  the  same name as the color.  If so, Tk uses
               the value of the element as the Postscript command
               to  set  the  color.   If  this option hasn't been
               specified, or if there isn't an entry  in  varName
               for  a  given  color, then Tk uses the red, green,
               and blue intensities from the X color.

          -colormode mode
               Specifies how to output color  information.   Mode
               must be either color (for full color output), gray
               (convert   all   colors   to   their    gray-scale
               equivalents)  or mono (convert all colors to black
               or white).

          -file fileName
               Specifies the name of the file in which  to  write
               the  Postscript.   If  this option isn't specified
               then the Postscript is returned as the  result  of
               the command instead of being written to a file.

          -fontmap varName
               VarName must be the name of an array variable that
               specifies a font mapping to use in the Postscript.
               Each element of varName must consist of a Tcl list
               with  two  elements,  which are the name and point
               size  of  a  Postscript  font.   When   outputting
               Postscript  commands  for  a  particular  font, Tk
               checks to see if varName contains an element  with
               the  same  name  as the font.  If there is such an
               element, then the font  information  contained  in
               that element is used in the Postscript.  Otherwise
               Tk attempts to guess what Postscript font to  use.
               Tk's  guesses  generally  only work for well-known
               fonts such as Times and Helvetica and Courier, and
               only  if  the X font name does not omit any dashes
               up through the point  size.   For  example,  - * -
               Courier - Bold - R - Normal--*-120-* will work but
               *Courier-Bold-R-Normal*120* will  not;   Tk  needs
               the dashes to parse the font name).

          -height size
               Specifies the height of the area of the canvas  to
               print.   Defaults to the height of the canvas win-
               dow.

          -pageanchor anchor
               Specifies which point of the printed area  of  the
               canvas should appear over the positioning point on
               the page (which is given by the -pagex and - pagey
               options).   For  example, -pageanchor n means that
               the top center of the area  of  the  canvas  being
               printed  (as  it  appears  in  the  canvas window)
               should be over the positioning point. Defaults  to
               center.

          -pageheight size
               Specifies that the Postscript should be scaled  in
               both x and y so that the printed area is size high
               on  the  Postscript  page.   Size  consists  of  a
               floating-point  number  followed by c for centime-
               ters, i for inches, m for  millimeters,  or  p  or
               nothing   for   printer's   points   (1/72  inch).
               Defaults to the height of the printed area on  the
               screen.   If  both  -pageheight and -pagewidth are
               specified then the scale factor from -pagewidth is
               used (non-uniform scaling is not implemented).

          -pagewidth size
               Specifies that the Postscript should be scaled  in
               both x and y so that the printed area is size wide
               on the Postscript page.  Size has the same form as
               for  - pageheight.   Defaults  to the width of the
               printed area on the screen.  If both  - pageheight
               and -pagewidth are specified then the scale factor
               from -pagewidth  is used (non-uniform  scaling  is
               not implemented).

          -pagex position
               Position gives the x-coordinate of the positioning
               point  on  the  Postscript  page, using any of the
               forms allowed for -pageheight.  Used  in  conjunc-
               tion  with  the  -pagey and -pageanchor options to
               determine where the printed area  appears  on  the
               Postscript  page.   Defaults  to the center of the
               page.

          -pagey position
               Position gives the y-coordinate of the positioning
               point  on  the  Postscript  page, using any of the
               forms allowed for -pageheight.  Used  in  conjunc-
               tion  with  the  -pagex and -pageanchor options to
               determine where the printed area  appears  on  the
               Postscript  page.   Defaults  to the center of the
               page.

          -rotate boolean
               Boolean specifies whether the printed area  is  to
               be  rotated 90 degrees.  In non-rotated output the
               x-axis of the printed area runs  along  the  short
               dimension  of the page (``portrait'' orientation);
               in rotated output the x-axis runs along  the  long
               dimension of the page (``landscape'' orientation).
               Defaults to non-rotated.

          -width size
               Specifies the width of the area of the  canvas  to
               print.   Defaults  to the width of the canvas win-
               dow.

          -x position
               Specifies the x-coordinate of the left edge of the
               area  of the canvas that is to be printed, in can-
               vas coordinates, not window coordinates.  Defaults
               to the coordinate of the left edge of the window.

          -y position
               Specifies the y-coordinate of the top edge of  the
               area  of the canvas that is to be printed, in can-
               vas coordinates, not window coordinates.  Defaults
               to the coordinate of the top edge of the window.

     pathName raise tagOrId ?aboveThis?
          Move all of the items given by tagOrId to a  new  posi-
          tion  in  the display list just after the item given by
          aboveThis.  If tagOrId refers to  more  than  one  item
          then  all are moved but the relative order of the moved
          items will not be changed.  AboveThis is a tag  or  id;
          if  it refers to more than one item then the last (top-
          most) of these items in the display list is used as the
          destination location for the moved items.  This command
          returns an empty string.

     pathName scale tagOrId xOrigin yOrigin xScale yScale
          Rescale all of the items given  by  tagOrId  in  canvas
          coordinate  space.   XOrigin  and  yOrigin identify the
          origin for the scaling operation and xScale and  yScale
          identify  the  scale  factors for x- and y-coordinates,
          respectively (a scale factor of 1.0 implies  no  change
          to  that  coordinate).  For each of the points defining
          each item, the x-coordinate is adjusted to  change  the
          distance  from  xOrigin  by  a factor of xScale.  Simi-
          larly, each y-coordinate is adjusted to change the dis-
          tance from yOrigin by a factor of yScale.  This command
          returns an empty string.

     pathName scan option args
          This command is used to implement scanning on canvases.
          It has two forms, depending on option:

          pathName scan mark x y
               Records x and y and  the  canvas's  current  view;
               used  in  conjunction  with later scan dragto com-
               mands.  Typically this command is associated  with
               a mouse button press in the widget and x and y are
               the coordinates of the mouse.  It returns an empty
               string.

          pathName scan dragto x y.
               This command computes the difference between its x
               and y arguments (which are typically mouse coordi-
               nates) and the x and y arguments to the last  scan
               mark  command for the widget.  It then adjusts the
               view by 10 times the  difference  in  coordinates.
               This  command  is  typically associated with mouse
               motion events in the widget, to produce the effect
               of  dragging  the canvas at high speed through its
               window.  The return value is an empty string.

     pathName select option ?tagOrId arg?
          Manipulates the  selection  in  one  of  several  ways,
          depending  on  option.  The command may take any of the
          forms described below.   In  all  of  the  descriptions
          below,  tagOrId  must  refer  to  an item that supports
          indexing and selection;  if it refers to multiple items
          then  the first of these that supports indexing and the
          selection is used.  Index gives a  textual  description
          of  a  position within tagOrId, as described in INDICES
          above.

          pathName select adjust tagOrId index
               Locate the end of the selection in tagOrId nearest
               to  the  character given by index, and adjust that
               end of the selection to be at index (i.e.  includ-
               ing but not going beyond index).  The other end of
               the selection is made the anchor point for  future
               select   to  commands.   If  the  selection  isn't
               currently in tagOrId then this command behaves the
               same  as the select to widget command.  Returns an
               empty string.

          pathName select clear
               Clear the selection if it is in this  widget.   If
               the  selection  isn't in this widget then the com-
               mand has no effect.  Returns an empty string.

          pathName select from tagOrId index
               Set the selection anchor point for the  widget  to
               be just before the character given by index in the
               item  given  by  tagOrId.   This  command  doesn't
               change  the selection;  it just sets the fixed end
               of the selection for future  select  to  commands.
               Returns an empty string.

          pathName select item
               Returns the id of the selected item, if the selec-
               tion  is in an item in this canvas.  If the selec-
               tion is not in this canvas then an empty string is
               returned.

          pathName select to tagOrId index
               Set the selection to consist of  those  characters
               of  tagOrId between the selection anchor point and
               index.  The new selection will include the charac-
               ter  given by index; it will include the character
               given by the anchor point only if index is greater
               than  or  equal  to  the anchor point.  The anchor
               point is determined  by  the  most  recent  select
               adjust or select from command for this widget.  If
               the selection anchor point for  the  widget  isn't
               currently  in  tagOrId, then it is set to the same
               character  given  by  index.   Returns  an   empty
               string.

     pathName type tagOrId
          Returns the type of the item given by tagOrId, such  as
          rectangle  or text.  If tagOrId refers to more than one
          item, then the type of the first item  in  the  display
          list  is  returned.   If  tagOrId  doesn't refer to any
          items at all then an empty string is returned.

     pathName xview  ?args?
          This command is used to query and change the horizontal
          position  of  the information displayed in the canvas's
          window.  It can take any of the following forms:

          pathName xview
               Returns a list containing two elements.  Each ele-
               ment is a real fraction between 0 and 1;  together
               they describe the horizontal span that is  visible
               in  the window.  For example, if the first element
               is .2 and the second element is  .6,  20%  of  the
               canvas's  area  (as  defined  by the -scrollregion
               option) is off-screen to the left, the middle  40%
               is visible in the window, and 40% of the canvas is
               off-screen to  the  right.   These  are  the  same
               values  passed  to scrollbars via the -xscrollcom-
               mand option.

          pathName xview moveto fraction
               Adjusts the view in the window so that fraction of
               the total width of the canvas is off-screen to the
               left.  Fraction must be a fraction between  0  and
               1.

          pathName xview scroll number what
               This command shifts the view in the window left or
               right  according  to number and what.  Number must
               be an integer.  What must be either units or pages
               or  an  abbreviation  of one of these.  If what is
               units, the view adjusts left or right in units  of
               the xScrollIncrement option, if it is greater than
               zero, or in units of one-tenth the window's  width
               otherwise.  If what is pages then the view adjusts
               in units of nine-tenths the  window's  width.   If
               number is negative then information farther to the
               left becomes visible;   if  it  is  positive  then
               information farther to the right becomes visible.

     pathName yview ?args?
          This command is used to query and change  the  vertical
          position  of  the information displayed in the canvas's
          window.  It can take any of the following forms:

          pathName yview
               Returns a  list  containing  two  elements.   Each
               element  is  a  real  fraction  between  0  and 1;
               together they describe the vertical span  that  is
               visible  in the window.  For example, if the first
               element is .6 and the second element is  1.0,  the
               lowest 40% of the canvas's area (as defined by the
               -scrollregion option) is visible  in  the  window.
               These are the same values passed to scrollbars via
               the -yscrollcommand option.

          pathName yview moveto fraction
               Adjusts the view in the window so that fraction of
               the canvas's area is off-screen to the top.  Frac-
               tion is a fraction between 0 and 1.

          pathName yview scroll number what
               This command adjusts the view in the window up  or
               down according to number and what.  Number must be
               an integer.  What must be either units  or  pages.
               If  what  is units, the view adjusts up or down in
               units of the yScrollIncrement  option,  if  it  is
               greater  than  zero,  or in units of one-tenth the
               window's height otherwise.  If what is pages  then
               the  view  adjusts  in  units  of  nine-tenths the
               window's  height.   If  number  is  negative  then
               higher  information  becomes  visible;   if  it is
               positive then lower information becomes visible.

OVERVIEW OF ITEM TYPES

     The sections below describe the various types of items  sup-
     ported  by  canvas widgets.  Each item type is characterized
     by two things:  first, the form of the create  command  used
     to  create instances of the type;  and second, a set of con-
     figuration options for items of that type, which may be used
     in the create and itemconfigure widget commands.  Most items
     don't support indexing or selection or the commands  related
     to  them,  such as index and insert.  Where items do support
     these facilities, it is noted explicitly in the descriptions
     below (at present, only text items provide this support).

ARC ITEMS

     Items of type  arc  appear  on  the  display  as  arc-shaped
     regions.   An  arc  is a section of an oval delimited by two
     angles (specified by the -start and  - extent  options)  and
     displayed  in  one  of several ways (specified by the -style
     option).  Arcs are created with widget commands of the  fol-
     lowing form:
          pathName create arc x1 y1 x2 y2 ?option value option value ...?
     The arguments x1, y1, x2, and y2 give the coordinates of two
     diagonally  opposite corners of a rectangular region enclos-
     ing the oval that defines the arc.   After  the  coordinates
     there may be any number of option-value pairs, each of which
     sets one of the configuration options for the  item.   These
     same  option-value pairs may be used in itemconfigure widget
     commands to change the item's configuration.  The  following
     options are supported for arcs:

     -extent degrees
          Specifies the size of the angular range occupied by the
          arc.   The  arc's  range  extends  for  degrees degrees
          counter-clockwise from the starting angle given by  the
          - start  option.   Degrees  may  be negative.  If it is
          greater than 360 or less than -360, then degrees modulo
          360 is used as the extent.

     -fill color
          Fill the region of the arc with color.  Color may  have
          any  of the forms accepted by Tk_GetColor.  If color is
          an empty string (the default), then then the  arc  will
          not be filled.

     -outline color
          Color specifies a color to use for  drawing  the  arc's
          outline;   it  may  have  any  of the forms accepted by
          Tk_GetColor.  This option defaults to black.  If  color
          is  specified  as  an  empty  string then no outline is
          drawn for the arc.

     -outlinestipple bitmap
          Indicates that the outline for the arc should be  drawn
          with  a  stipple  pattern; bitmap specifies the stipple
          pattern to  use,  in  any  of  the  forms  accepted  by
          Tk_GetBitmap.   If  the  - outline  option  hasn't been
          specified then this option has no effect.  If bitmap is
          an  empty  string  (the  default),  then the outline is
          drawn in a solid fashion.

     -start degrees
          Specifies the beginning of the angular  range  occupied
          by the arc.  Degrees is given in units of degrees meas-
          ured counter-clockwise from the 3-o'clock position;  it
          may be either positive or negative.

     -stipple bitmap
          Indicates that the arc should be filled  in  a  stipple
          pattern;  bitmap  specifies the stipple pattern to use,
          in any of the forms accepted by Tk_GetBitmap.  If the -
          fill  option hasn't been specified then this option has
          no effect.  If bitmap is an empty string (the default),
          then filling is done in a solid fashion.

     -style type
          Specifies how to draw the arc.   If  type  is  pieslice
          (the  default)  then  the  arc's region is defined by a
          section of the oval's perimeter plus two line segments,
          one  between the center of the oval and each end of the
          perimeter section.  If type is  chord  then  the  arc's
          region  is defined by a section of the oval's perimeter
          plus a single  line  segment  connecting  the  two  end
          points  of  the perimeter section.  If type is arc then
          the arc's region consists of a section of the perimeter
          alone.  In this last case the -fill option is ignored.

     -tags tagList
          Specifies a set of tags to apply to the item.   TagList
          consists  of  a  list  of  tag names, which replace any
          existing tags for the item.  TagList may  be  an  empty
          list.

     -width outlineWidth
          Specifies the width of the outline to be  drawn  around
          the  arc's region, in any of the forms described in the
          COORDINATES section above.  If the -outline option  has
          been  specified as an empty string then this option has
          no effect.  Wide outlines will be drawn centered on the
          edges  of  the  arc's  region.  This option defaults to
          1.0.

BITMAP ITEMS

     Items of type bitmap appear on the display  as  images  with
     two  colors, foreground and background.  Bitmaps are created
     with widget commands of the following form:
          pathName create bitmap x y ?option value option value ...?
     The arguments x and y specify the  coordinates  of  a  point
     used  to position the bitmap on the display (see the -anchor
     option  below  for  more  information  on  how  bitmaps  are
     displayed).   After  the coordinates there may be any number
     of option-value pairs, each of which sets one of the  confi-
     guration  options  for  the  item.   These same option-value
     pairs may be used in itemconfigure widget commands to change
     the  item's  configuration.   The following options are sup-
     ported for bitmaps:

     -anchor anchorPos
          AnchorPos tells how to position the bitmap relative  to
          the positioning point for the item;  it may have any of
          the forms accepted by Tk_GetAnchor.   For  example,  if
          anchorPos  is center then the bitmap is centered on the
          point;  if anchorPos is n then the bitmap will be drawn
          so  that  its  top  center  point is at the positioning
          point.  This option defaults to center.

     -background color
          Specifies a color to use for each of the bitmap  pixels
          whose  value  is  0.   Color  may have any of the forms
          accepted by Tk_GetColor.  If this option  isn't  speci-
          fied,  or  if  it is specified as an empty string, then
          nothing is displayed where the  bitmap  pixels  are  0;
          this produces a transparent effect.

     -bitmap bitmap
          Specifies the bitmap to display in  the  item.   Bitmap
          may have any of the forms accepted by Tk_GetBitmap.

     -foreground color
          Specifies a color to use for each of the bitmap  pixels
          whose  value  is  1.   Color  may have any of the forms
          accepted by Tk_GetColor and defaults to black.

     -tags tagList
          Specifies a set of tags to apply to the item.   TagList
          consists  of  a  list  of  tag names, which replace any
          existing tags for the item.  TagList may  be  an  empty
          list.

IMAGE ITEMS

     Items of type image are used to display images on a  canvas.
     Images  are  created  with  widget commands of the following
     form:
          pathName create image x y ?option value option value ...?
     The arguments x and y specify the  coordinates  of  a  point
     used  to  position the image on the display (see the -anchor
     option below for more information).  After  the  coordinates
     there may be any number of option-value pairs, each of which
     sets one of the configuration options for the  item.   These
     same  option-value pairs may be used in itemconfigure widget
     commands to change the item's configuration.  The  following
     options are supported for images:

     -anchor anchorPos
          AnchorPos tells how to position the image  relative  to
          the positioning point for the item;  it may have any of
          the forms accepted by Tk_GetAnchor.   For  example,  if
          anchorPos  is  center then the image is centered on the
          point;  if anchorPos is n then the image will be  drawn
          so  that  its  top  center  point is at the positioning
          point.  This option defaults to center.

     -image name
          Specifies the name of the image to display in the item.
          This  image  must have been created previously with the
          image create command.

     -tags tagList
          Specifies a set of tags to apply to the item.   TagList
          consists  of  a  list  of  tag names, which replace any
          existing tags for the item;  it may be an empty list.

LINE ITEMS

     Items of type line appear on the display as one or more con-
     nected  line  segments  or  curves.   Lines are created with
     widget commands of the following form:
          pathName create line x1 y1... xn yn ?option value option value ...?
     The arguments x1 through  yn  give  the  coordinates  for  a
     series  of two or more points that describe a series of con-
     nected line segments.  After the coordinates  there  may  be
     any  number of option-value pairs, each of which sets one of
     the configuration options for the item.  These same option -
     value  pairs may be used in itemconfigure widget commands to
     change the item's configuration.  The following options  are
     supported for lines:

     -arrow where
          Indicates whether or not arrowheads are to be drawn  at
          one  or  both ends of the line.  Where must have one of
          the values none (for  no  arrowheads),  first  (for  an
          arrowhead at the first point of the line), last (for an
          arrowhead at the last point of the line), or both  (for
          arrowheads  at  both  ends).   This  option defaults to
          none.

     -arrowshape shape
          This option indicates  how  to  draw  arrowheads.   The
          shape argument must be a list with three elements, each
          specifying a distance in any of the forms described  in
          the  COORDINATES  section  above.  The first element of
          the list gives the distance along  the  line  from  the
          neck  of  the arrowhead to its tip.  The second element
          gives the distance along the  line  from  the  trailing
          points  of the arrowhead to the tip, and the third ele-
          ment gives the distance from the outside  edge  of  the
          line  to  the  trailing  points.   If this option isn't
          specified then Tk picks a ``reasonable'' shape.

     -capstyle style
          Specifies the ways in which caps are to be drawn at the
          endpoints of the line.  Style may have any of the forms
          accepted  by  Tk_GetCapStyle  (butt,   projecting,   or
          round).    If  this  option  isn't  specified  then  it
          defaults to butt.  Where arrowheads are drawn  the  cap
          style is ignored.

     -fill color
          Color specifies a color to use for drawing the line; it
          may  have  any  of the forms acceptable to Tk_GetColor.
          It may also be an empty string, in which case the  line
          will be transparent.  This option defaults to black.

     -joinstyle style
          Specifies the ways in which joints are to be  drawn  at
          the  vertices  of  the line.  Style may have any of the
          forms accepted  by  Tk_GetCapStyle  (bevel,  miter,  or
          round).    If  this  option  isn't  specified  then  it
          defaults to miter.   If  the  line  only  contains  two
          points then this option is irrelevant.

     -smooth boolean
          Boolean  must  have  one  of  the  forms  accepted   by
          Tk_GetBoolean.   It  indicates  whether or not the line
          should be drawn as a curve.  If so, the  line  is  ren-
          dered  as  a set of Bezier splines: one spline is drawn
          for the first and second line  segments,  one  for  the
          second  and  third,  and so on.  Straight-line segments
          can be generated within  a  curve  by  duplicating  the
          end-points of the desired line segment.

     -splinesteps number
          Specifies the degree of smoothness desired for  curves:
          each  spline will be approximated with number line seg-
          ments.  This option  is  ignored  unless  the  - smooth
          option is true.

     -stipple bitmap
          Indicates that the line should be filled in  a  stipple
          pattern;  bitmap  specifies the stipple pattern to use,
          in any of the forms accepted by Tk_GetBitmap.  If  bit-
          map  is  an empty string (the default), then filling is
          done in a solid fashion.

     -tags tagList
          Specifies a set of tags to apply to the item.   TagList
          consists  of  a  list  of  tag names, which replace any
          existing tags for the item.  TagList may  be  an  empty
          list.

     -width lineWidth
          LineWidth specifies the width of the line,  in  any  of
          the  forms  described in the COORDINATES section above.
          Wide lines will be drawn centered on the path specified
          by  the points.  If this option isn't specified then it
          defaults to 1.0.

OVAL ITEMS

     Items of type oval appear as circular or oval regions on the
     display.   Each  oval  may have an outline, a fill, or both.
     Ovals are created with  widget  commands  of  the  following
     form:
          pathName create oval x1 y1 x2 y2 ?option value option value ...?
     The arguments x1, y1, x2, and y2 give the coordinates of two
     diagonally  opposite corners of a rectangular region enclos-
     ing the oval.  The oval will include the top and left  edges
     of  the  rectangle  not  the  lower  or right edges.  If the
     region is square then the resulting oval is circular; other-
     wise  it is elongated in shape.  After the coordinates there
     may be any number of option-value pairs, each of which  sets
     one  of  the configuration options for the item.  These same
     option-value pairs may be used in itemconfigure widget  com-
     mands  to  change  the  item's configuration.  The following
     options are supported for ovals:

     -fill color
          Fill the area of the oval with color.  Color  may  have
          any  of the forms accepted by Tk_GetColor.  If color is
          an empty string (the default), then then the oval  will
          not be filled.

     -outline color
          Color specifies a color to use for drawing  the  oval's
          outline;   it  may  have  any  of the forms accepted by
          Tk_GetColor.  This option defaults to black.  If  color
          is  an  empty  string then no outline will be drawn for
          the oval.

     -stipple bitmap
          Indicates that the oval should be filled in  a  stipple
          pattern;  bitmap  specifies the stipple pattern to use,
          in any of the forms accepted by Tk_GetBitmap.  If the -
          fill  option hasn't been specified then this option has
          no effect.  If bitmap is an empty string (the default),
          then filling is done in a solid fashion.

     -tags tagList
          Specifies a set of tags to apply to the item.   TagList
          consists  of  a  list  of  tag names, which replace any
          existing tags for the item.  TagList may  be  an  empty
          list.

     -width outlineWidth
          outlineWidth specifies the width of the outline  to  be
          drawn around the oval, in any of the forms described in
          the COORDINATES section above.  If the -outline  option
          hasn't  been  specified then this option has no effect.
          Wide outlines are  drawn  centered  on  the  oval  path
          defined by x1, y1, x2, and y2.  This option defaults to
          1.0.

POLYGON ITEMS


     Items of type polygon appear as polygonal or  curved  filled
     regions  on  the  display.  Polygons are created with widget
     commands of the following form:
          pathName create polygon x1 y1 ... xn yn ?option value option value ...?
     The arguments x1 through  yn  specify  the  coordinates  for
     three  or  more  points  that  define a closed polygon.  The
     first and last points may be the same;  whether they are  or
     not,  Tk  will  draw the polygon as a closed polygon.  After
     the coordinates there may be any  number  of  option - value
     pairs,  each  of which sets one of the configuration options
     for the item.  These same option-value pairs may be used  in
     itemconfigure  widget  commands  to change the item's confi-
     guration.  The following options are supported for polygons:

     -fill color
          Color specifies a color to use for filling the area  of
          the polygon; it may have any of the forms acceptable to
          Tk_GetColor.  If color is  an  empty  string  then  the
          polygon  will  be transparent.  This option defaults to
          black.

     -outline color
          Color  specifies  a  color  to  use  for  drawing   the
          polygon's  outline;   it  may  have  any  of  the forms
          accepted by Tk_GetColor.  If color is an  empty  string
          then  no  outline  will be drawn for the polygon.  This
          option defaults to empty (no outline).

     -smooth boolean
          Boolean  must  have  one  of  the  forms  accepted   by
          Tk_GetBoolean  It  indicates whether or not the polygon
          should be drawn with a curved perimeter.   If  so,  the
          outline of the polygon becomes a set of Bezier splines,
          one spline for the first and second line segments,  one
          for  the  second  and  third, and so on.  Straight-line
          segments can be generated  in  a  smoothed  polygon  by
          duplicating the end-points of the desired line segment.

     -splinesteps number
          Specifies the degree of smoothness desired for  curves:
          each  spline will be approximated with number line seg-
          ments.  This option  is  ignored  unless  the  - smooth
          option is true.

     -stipple bitmap
          Indicates that the polygon should be filled in a  stip-
          ple  pattern;  bitmap  specifies the stipple pattern to
          use, in any of the forms accepted by Tk_GetBitmap.   If
          bitmap  is  an empty string (the default), then filling
          is done in a solid fashion.

     -tags tagList
          Specifies a set of tags to apply to the item.   TagList
          consists  of  a  list  of  tag names, which replace any
          existing tags for the item.  TagList may  be  an  empty
          list.

     -width outlineWidth
          OutlineWidth specifies the width of the outline  to  be
          drawn around the polygon, in any of the forms described
          in the COORDINATES section  above.   If  the  - outline
          option  hasn't  been  specified then this option has no
          effect.  This option defaults to 1.0.

     Polygon items are different from other items such as rectan-
     gles,  ovals and arcs in that interior points are considered
     to be ``inside'' a polygon (e.g. for purposes  of  the  find
     closest  and find overlapping widget commands) even if it is
     not filled.  For most other item types, an interior point is
     considered  to be inside the item only if the item is filled
     or if it has neither a fill nor an outline.   If  you  would
     like  an unfilled polygon whose interior points are not con-
     sidered to be inside the polygon, use a line item instead.

RECTANGLE ITEMS

     Items of type rectangle appear as rectangular regions on the
     display.   Each  rectangle  may  have an outline, a fill, or
     both.  Rectangles are created with widget  commands  of  the
     following form:
          pathName create rectangle x1 y1 x2 y2 ?option value option value ...?
     The arguments x1, y1, x2, and y2 give the coordinates of two
     diagonally  opposite corners of the rectangle (the rectangle
     will include its upper and left edges but not its  lower  or
     right edges).  After the coordinates there may be any number
     of option-value pairs, each of which sets one of the  confi-
     guration  options  for  the  item.   These same option-value
     pairs may be used in itemconfigure widget commands to change
     the  item's  configuration.   The following options are sup-
     ported for rectangles:

     -fill color
          Fill the area of the rectangle with color, which may be
          specified  in any of the forms accepted by Tk_GetColor.
          If color is an empty string  (the  default),  then  the
          rectangle will not be filled.

     -outline color
          Draw an outline around the edge  of  the  rectangle  in
          color.   Color  may  have  any of the forms accepted by
          Tk_GetColor.  This option defaults to black.  If  color
          is  an  empty  string then no outline will be drawn for
          the rectangle.

     -stipple bitmap
          Indicates that the rectangle  should  be  filled  in  a
          stipple  pattern;  bitmap specifies the stipple pattern
          to use, in any of the forms accepted  by  Tk_GetBitmap.
          If  the  - fill  option hasn't been specified then this
          option has no effect.  If bitmap  is  an  empty  string
          (the default), then filling is done in a solid fashion.

     -tags tagList
          Specifies a set of tags to apply to the item.   TagList
          consists  of  a  list  of  tag names, which replace any
          existing tags for the item.  TagList may  be  an  empty
          list.

     -width outlineWidth
          OutlineWidth specifies the width of the outline  to  be
          drawn  around  the  rectangle,  in  any  of  the  forms
          described in the COORDINATES section above.  If  the  -
          outline  option  hasn't been specified then this option
          has no effect.  Wide outlines are drawn centered on the
          rectangular  path  defined by x1, y1, x2, and y2.  This
          option defaults to 1.0.

TEXT ITEMS

     A text item displays a string of characters on the screen in
     one  or  more lines.  Text items support indexing and selec-
     tion, along with the following  text-related  canvas  widget
     commands:   dchars,  focus,  icursor, index, insert, select.
     Text items are created with widget commands of the following
     form:
          pathName create text x y ?option value option value ...?
     The arguments x and y specify the  coordinates  of  a  point
     used  to  position  the text on the display (see the options
     below for more information on how text is displayed).  After
     the  coordinates  there  may  be  any number of option-value
     pairs, each of which sets one of the  configuration  options
     for  the item.  These same option-value pairs may be used in
     itemconfigure widget commands to change  the  item's  confi-
     guration.   The  following  options  are  supported for text
     items:

     -anchor anchorPos
          AnchorPos tells how to position the  text  relative  to
          the positioning point for the text;  it may have any of
          the forms accepted by Tk_GetAnchor.   For  example,  if
          anchorPos  is  center  then the text is centered on the
          point;  if anchorPos is n then the text will  be  drawn
          such  that  the  top  center  point  of the rectangular
          region occupied by the text will be at the  positioning
          point.  This option defaults to center.

     -fill color
          Color specifies a color to use  for  filling  the  text
          characters;  it  may  have any of the forms accepted by
          Tk_GetColor.  If this option isn't  specified  then  it
          defaults to black.

     -font fontName
          Specifies the font to use for the text item.   FontName
          may  be  any string acceptable to Tk_GetFontStruct.  If
          this option isn't specified, it defaults to  a  system-
          dependent font.

     -justify how
          Specifies how to justify the text within  its  bounding
          region.   How must be one of the values left, right, or
          center.  This option will only matter if  the  text  is
          displayed as multiple lines.  If the option is omitted,
          it defaults to left.

     -stipple bitmap
          Indicates that the text should be drawn in  a  stippled
          pattern rather than solid; bitmap specifies the stipple
          pattern to  use,  in  any  of  the  forms  accepted  by
          Tk_GetBitmap.   If  bitmap  is  an  empty  string  (the
          default) then the text is drawn in a solid fashion.

     -tags tagList
          Specifies a set of tags to apply to the item.   TagList
          consists  of  a  list  of  tag names, which replace any
          existing tags for the item.  TagList may  be  an  empty
          list.

     -text string
          String specifies the characters to be displayed in  the
          text  item.  Newline characters cause line breaks.  The
          characters in the item may also  be  changed  with  the
          insert   and   delete  widget  commands.   This  option
          defaults to an empty string.

     -width lineLength
          Specifies a maximum line length for the text, in any of
          the  forms  described in the COORDINATES section above.
          If this option is zero (the default) the text is broken
          into  lines  only  at  newline characters.  However, if
          this option is non-zero then any  line  that  would  be
          longer  than  lineLength  is broken just before a space
          character to make the  line  shorter  than  lineLength;
          the  space character is treated as if it were a newline
          character.

WINDOW ITEMS

     Items of  type  window  cause  a  particular  window  to  be
     displayed  at  a given position on the canvas.  Window items
     are created with widget commands of the following form:
          pathName create window x y ?option value option value ...?
     The arguments x and y specify the  coordinates  of  a  point
     used  to position the window on the display (see the -anchor
     option  below  for  more  information  on  how  bitmaps  are
     displayed).   After  the coordinates there may be any number
     of option-value pairs, each of which sets one of the  confi-
     guration  options  for  the  item.   These same option-value
     pairs may be used in itemconfigure widget commands to change
     the  item's  configuration.   The following options are sup-
     ported for window items:

     -anchor anchorPos
          AnchorPos tells how to position the window relative  to
          the positioning point for the item;  it may have any of
          the forms accepted by Tk_GetAnchor.   For  example,  if
          anchorPos  is center then the window is centered on the
          point;  if anchorPos is n then the window will be drawn
          so  that  its  top  center  point is at the positioning
          point.  This option defaults to center.

     -height pixels
          Specifies the height to assign to  the  item's  window.
          Pixels may have any of the forms described in the COOR-
          DINATES section above.  If this option isn't specified,
          or if it is specified as an empty string, then the win-
          dow is given whatever height it requests internally.

     -tags tagList
          Specifies a set of tags to apply to the item.   TagList
          consists  of  a  list  of  tag names, which replace any
          existing tags for the item.  TagList may  be  an  empty
          list.

     -width pixels
          Specifies the width to assign  to  the  item's  window.
          Pixels may have any of the forms described in the COOR-
          DINATES section above.  If this option isn't specified,
          or if it is specified as an empty string, then the win-
          dow is given whatever width it requests internally.

     -window pathName
          Specifies the window to associate with this item.   The
          window  specified by pathName must either be a child of
          the canvas widget or a child of some  ancestor  of  the
          canvas  widget.   PathName may not refer to a top-level
          window.

APPLICATION-DEFINED ITEM TYPES

     It is possible for individual  applications  to  define  new
     item  types  for canvas widgets using C code.  See the docu-
     mentation for Tk_CreateItemType.

BINDINGS

     In the current implementation, new canvases  are  not  given
     any  default  behavior:  you'll have to execute explicit Tcl
     commands to give the canvas its behavior.

CREDITS

     Tk's canvas widget is a blatant ripoff of  ideas  from  Joel
     Bartlett's ezd program.  Ezd provides structured graphics in
     a Scheme environment and preceded canvases by a year or two.
     Its  simple  mechanisms  for placing and animating graphical
     objects inspired the functions of canvases.

KEYWORDS

     canvas, widget
itcl2.2/html/tk4.2/checkbutton.n.html100666 1751 0 33063 6423554666 16342 0ustar kunkeewheel tk4.2 User Commands - checkbutton

tk4.2 User Commands - checkbutton

NAME

     checkbutton - Create and manipulate checkbutton widgets

SYNOPSIS

     checkbutton pathName ?options?

STANDARD OPTIONS

     -activebackground              -cursor         -highlightthickness-takefocus
     -activeforeground              -disabledforeground-image-text
     -anchor         -font          -justify        -textvariable
     -background     -foreground    -padx           -underline
     -bitmap         -highlightbackground           -pady-wraplength
     -borderwidth    -highlightcolor                -relief

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

WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-command
     Database Name:  command
     Database Class: Command

          Specifies a Tcl command to associate with  the  button.
          This  command  is typically invoked when mouse button 1
          is released over the button window.  The button's  glo-
          bal  variable (-variable option) will be updated before
          the command is invoked.

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

          Specifies a desired height for the button.  If an image
          or  bitmap  is  being  displayed in the button then the
          value is in screen units (i.e. any of the forms accept-
          able to Tk_GetPixels); for text it is in lines of text.
          If this option isn't specified,  the  button's  desired
          height is computed from the size of the image or bitmap
          or text being displayed in it.

     Command-Line Name:-indicatoron
     Database Name:  indicatorOn
     Database Class: IndicatorOn

          Specifies whether or not the indicator should be drawn.
          Must  be  a proper boolean value.  If false, the relief
          option is ignored and the  widget's  relief  is  always
          sunken if the widget is selected and raised otherwise.


     Command-Line Name:-offvalue
     Database Name:  offValue
     Database Class: Value

          Specifies value to store  in  the  button's  associated
          variable  whenever this button is deselected.  Defaults
          to ``0''.

     Command-Line Name:-onvalue
     Database Name:  onValue
     Database Class: Value

          Specifies value to store  in  the  button's  associated
          variable whenever this button is selected.  Defaults to
          ``1''.

     Command-Line Name:-selectcolor
     Database Name:  selectColor
     Database Class: Background

          Specifies a background color to use when the button  is
          selected.  If indicatorOn is true then the color appli-
          cies to the indicator.  If indicatorOn is  false,  this
          color  is used as the background for the entire widget,
          in place of background  or  activeBackground,  whenever
          the  widget  is  selected.   If  specified  as an empty
          string then no special color  is  used  for  displaying
          when the widget is selected.

     Command-Line Name:-selectimage
     Database Name:  selectImage
     Database Class: SelectImage

          Specifies an image to display (in place  of  the  image
          option)  when the checkbutton is selected.  This option
          is ignored unless the image option has been specified.

     Command-Line Name:-state
     Database Name:  state
     Database Class: State

          Specifies one of  three  states  for  the  checkbutton:
          normal,  active,  or  disabled.   In  normal  state the
          checkbutton is displayed using the foreground and back-
          ground  options.   The  active  state is typically used
          when the pointer is over the  checkbutton.   In  active
          state   the   checkbutton   is   displayed   using  the
          activeForeground and  activeBackground  options.   Dis-
          abled state means that the checkbutton should be insen-
          sitive:  the default bindings will refuse  to  activate
          the  widget  and  will ignore mouse button presses.  In
          this  state  the  disabledForeground   and   background
          options determine how the checkbutton is displayed.

     Command-Line Name:-variable
     Database Name:  variable
     Database Class: Variable

          Specifies name of global variable to  set  to  indicate
          whether  or  not  this button is selected.  Defaults to
          the name of the button within its parent (i.e. the last
          element of the button window's path name).

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

          Specifies a desired width for the button.  If an  image
          or  bitmap  is  being  displayed in the button then the
          value is in screen units (i.e. any of the forms accept-
          able  to  Tk_GetPixels);  for text it is in characters.
          If this option isn't specified,  the  button's  desired
          width  is computed from the size of the image or bitmap
          or text being displayed in it.

DESCRIPTION

     The checkbutton command creates a new window (given  by  the
     pathName  argument)  and makes it into a checkbutton widget.
     Additional options, described above, may be specified on the
     command  line or in the option database to configure aspects
     of the checkbutton such as its colors, font, text, and  ini-
     tial  relief.   The checkbutton 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 checkbutton is a widget that displays  a  textual  string,
     bitmap  or  image and a square called an indicator.  If text
     is displayed, it must all be in a single font,  but  it  can
     occupy multiple lines on the screen (if it contains newlines
     or if wrapping occurs because of the wrapLength option)  and
     one of the characters may optionally be underlined using the
     underline option.  A checkbutton has all of the behavior  of
     a  simple  button,  including  the following: it can display
     itself in either of three different ways, according  to  the
     state  option;  it  can be made to appear raised, sunken, or
     flat; it can be made to flash; and it invokes a Tcl  command
     whenever mouse button 1 is clicked over the checkbutton.

     In addition, checkbuttons can be selected.  If a checkbutton
     is  selected  then  the  indicator  is normally drawn with a
     sunken relief and  a  special  color,  and  a  Tcl  variable
     associated with the checkbutton is set to a particular value
     (normally 1).  If the checkbutton is not selected, then  the
     indicator  is  drawn  with  a  raised  relief and no special
     color, and the associated variable is  set  to  a  different
     value  (typically  0).  By default, the name of the variable
     associated with a checkbutton is the same as the  name  used
     to  create  the  checkbutton.   The  variable  name, and the
     ``on'' and ``off'' values stored in it, may be modified with
     options on the command line or in the option database.  Con-
     figuration options may also be used to modify  the  way  the
     indicator  is displayed (or whether it is displayed at all).
     By  default  a  checkbutton  is  configured  to  select  and
     deselect  itself  on  alternate button clicks.  In addition,
     each  checkbutton  monitors  its  associated  variable   and
     automatically  selects  and  deselects itself when the vari-
     ables value changes to and from the button's ``on'' value.

WIDGET COMMAND

     The checkbutton 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 checkbutton
     widgets:

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

     pathName deselect
          Deselects the checkbutton and sets the associated vari-
          able to its ``off'' value.

     pathName flash
          Flashes  the  checkbutton.   This  is  accomplished  by
          redisplaying the checkbutton several times, alternating
          between active and normal colors.  At the  end  of  the
          flash the checkbutton is left in the same normal/active
          state as when the command was invoked.  This command is
          ignored if the checkbutton's state is disabled.

     pathName invoke
          Does just what would have happened if the user  invoked
          the  checkbutton  with  the mouse: toggle the selection
          state of the button and invoke the Tcl command  associ-
          ated with the checkbutton, if there is one.  The return
          value is the return value from the Tcl command,  or  an
          empty string if there is no command associated with the
          checkbutton.   This   command   is   ignored   if   the
          checkbutton's state is disabled.

     pathName select
          Selects the checkbutton and sets the  associated  vari-
          able to its ``on'' value.

     pathName toggle
          Toggles the selection state of the button, redisplaying
          it and modifying its associated variable to reflect the
          new state.

BINDINGS

     Tk automatically creates  class  bindings  for  checkbuttons
     that give them the following default behavior:

     [1]  A checkbutton activates whenever the mouse passes  over
          it and deactivates whenever the mouse leaves the check-
          button.

     [2]  When mouse button 1 is pressed over a checkbutton it is
          invoked  (its  selection  state toggles and the command
          associated with the button  is  invoked,  if  there  is
          one).

     [3]  When a checkbutton has the input focus, the  space  key
          causes the checkbutton to be invoked.

     If the checkbutton's state is  disabled  then  none  of  the
     above  actions  occur:   the  checkbutton is completely non-
     responsive.

     The behavior of checkbuttons can be changed by defining  new
     bindings  for  individual widgets or by redefining the class
     bindings.

KEYWORDS

     checkbutton, widget
itcl2.2/html/tk4.2/chooseColor.n.html100666 1751 0 3474 6423554666 16273 0ustar kunkeewheel tk4.2 User Commands - chooseColor

tk4.2 User Commands - chooseColor

NAME

     tk_chooseColor - pops up a dialog box for the user to select
     a color.

SYNOPSIS

     tk_chooseColor ?option value ...?

DESCRIPTION

     The procedure tk_chooseColor pops up a dialog  box  for  the
     user to select a color. The following option-value pairs are
     possible as command line arguments:

     -initialcolor color
          Specifies the color to display in the color dialog when
          it  pops  up. color must be in a form acceptable to the
          Tk_GetColor function.

     -parent window
          Makes window the logical parent of  the  color  dialog.
          The color dialog is displayed on top of its parent win-
          dow.

     -title titleString
          Specifies a string to display as the title of the  dia-
          log  box.  If  this  option  is  not  specified, then a
          default title will be displayed.

     If the user selects a color, tk_chooseColor will return  the
     name  of  the color in a form acceptable to Tk_GetColor.  If
     the user cancels the operation, both  commands  will  return
     the empty string.

EXAMPLE

          button .b -fg [tk_chooseColor -initialcolor gray -title "Choose color"]

KEYWORDS

     color selection dialog
itcl2.2/html/tk4.2/clipboard.n.html100666 1751 0 10372 6423554666 15766 0ustar kunkeewheel tk4.2 User Commands - clipboard

tk4.2 User Commands - clipboard

NAME

     clipboard - Manipulate Tk clipboard

SYNOPSIS

     clipboard option ?arg arg ...?

DESCRIPTION

     This command provides a Tcl interface to the  Tk  clipboard,
     which  stores  data  for later retrieval using the selection
     mechanism.  In order to copy data into the clipboard,  clip-
     board clear must be called, followed by a sequence of one or
     more calls to clipboard append.  To ensure  that  the  clip-
     board is updated atomically, all appends should be completed
     before returning to the event loop.

     The first argument to clipboard determines the format of the
     rest  of the arguments and the behavior of the command.  The
     following forms are currently supported:

     clipboard clear ?-displayof window?
          Claims ownership of the clipboard on  window's  display
          and  removes any previous contents.  Window defaults to
          ``.''.  Returns an empty string.

type? ?--? data

     clipboard append ?-displayof window? ?- format  format?  ? -
           type
          Appends data to the clipboard on  window's  display  in
          the form given by type with the representation given by
          format  and  claims  ownership  of  the  clipboard   on
          window's display.

          Type specifies the form in which the selection is to be
          returned  (the  desired  ``target''  for conversion, in
          ICCCM terminology), and should be an atom name such  as
          STRING or FILE_NAME; see the Inter-Client Communication
          Conventions Manual for complete details.  Type defaults
          to STRING.

          The format argument specifies the  representation  that
          should be used to transmit the selection to the reques-
          ter (the second column of Table 2 of  the  ICCCM),  and
          defaults to STRING.  If format is STRING, the selection
          is transmitted as 8-bit ASCII characters.  If format is
          ATOM, then the data is divided into fields separated by
          white space; each field is converted to its atom value,
          and the 32-bit atom value is transmitted instead of the
          atom name.  For any other format,  data is divided into
          fields  separated by white space and each field is con-
          verted to a 32-bit integer; an  array  of  integers  is
          transmitted  to  the  selection  requester.   Note that
          strings passed to  clipboard  append  are  concatenated
          before  conversion,  so  the  caller  must take care to
          ensure appropriate spacing  across  string  boundaries.
          All  items appended to the clipboard with the same type
          must have the same format.

          The format argument is needed  only  for  compatibility
          with clipboard requesters that don't use Tk.  If the Tk
          toolkit is being used to retrieve the CLIPBOARD  selec-
          tion  then  the  value is converted back to a string at
          the requesting end, so format is irrelevant.

          A -- argument may be  specified  to  mark  the  end  of
          options:   the  next  argument  will  always be used as
          data.  This feature may be convenient if, for  example,
          data starts with a -.

KEYWORDS

     clear, format, clipboard, append, selection, type
itcl2.2/html/tk4.2/destroy.n.html100666 1751 0 1705 6423554666 15500 0ustar kunkeewheel tk4.2 User Commands - destroy

tk4.2 User Commands - destroy

NAME

     destroy - Destroy one or more windows

SYNOPSIS

     destroy ?window window ...?

DESCRIPTION

     This command deletes the windows given by the  window  argu-
     ments,  plus all of their descendants.  If a window ``.'' is
     deleted then the entire application will be destroyed.   The
     windows  are  destroyed  in order, and if an error occurs in
     destroying a window the command  aborts  without  destroying
     the remaining windows.

KEYWORDS

     application, destroy, window
itcl2.2/html/tk4.2/dialog.n.html100666 1751 0 5014 6423554666 15243 0ustar kunkeewheel tk4.2 User Commands - dialog

tk4.2 User Commands - dialog

NAME

     tk_dialog - Create modal dialog and wait for response

SYNOPSIS

     tk_dialog window title text bitmap default string string ...

DESCRIPTION

     This procedure is part of the Tk script library.  Its  argu-
     ments describe a dialog box:

     window
          Name of top-level window to use for dialog.  Any exist-
          ing window by this name is destroyed.

     title
          Text to appear in the window manager's  title  bar  for
          the dialog.

     text Message to appear in the top portion of the dialog box.

     bitmap
          If non-empty, specifies a bitmap to display in the  top
          portion  of  the  dialog,  to the left of the text.  If
          this is an empty string then no bitmap is displayed  in
          the dialog.

     default
          If this is an integer greater than or  equal  to  zero,
          then it gives the index of the button that is to be the
          default button for the dialog (0 for the leftmost  but-
          ton,  and so on).  If less than zero or an empty string
          then there won't be any default button.

     string
          There will be one button for each of  these  arguments.
          Each  string  specifies text to display in a button, in
          order from left to right.

     After creating a dialog box, tk_dialog waits for the user to
     select  one  of the buttons either by clicking on the button
     with the mouse or by typing return  to  invoke  the  default
     button  (if any).  Then it returns the index of the selected
     button:  0 for the leftmost button, 1 for the button next to
     it,  and  so on.  If the dialog's window is destroyed before
     the user selects one of the buttons, then -1 is returned.

     While waiting for the user  to  respond,  tk_dialog  sets  a
     local  grab.   This  prevents the user from interacting with
     the application in any way except to invoke the dialog box.

KEYWORDS

     bitmap, dialog, modal
itcl2.2/html/tk4.2/entry.n.html100666 1751 0 56427 6423554666 15203 0ustar kunkeewheel tk4.2 User Commands - entry

tk4.2 User Commands - entry

NAME

     entry - Create and manipulate entry widgets

SYNOPSIS

     entry pathName ?options?

STANDARD OPTIONS

     -background     -highlightbackground           -insertontime-selectforeground
     -borderwidth    -highlightcolor                -insertwidth-takefocus
     -cursor         -highlightthickness            -justify-textvariable
     -exportselection               -insertbackground-relief-xscrollcommand
     -font           -insertborderwidth             -selectbackground
     -foreground     -insertofftime -selectborderwidth

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

WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-show
     Database Name:  show
     Database Class: Show

          If this option is specified, then the true contents  of
          the  entry  are  not displayed in the window.  Instead,
          each character in the entry's value will  be  displayed
          as  the  first  character  in the value of this option,
          such as ``*''.  This is useful,  for  example,  if  the
          entry is to be used to enter a password.  If characters
          in the entry are selected  and  copied  elsewhere,  the
          information  copied  will be what is displayed, not the
          true contents of the entry.

     Command-Line Name:-state
     Database Name:  state
     Database Class: State

          Specifies one of two states for the entry:   normal  or
          disabled.   If the entry is disabled then the value may
          not be changed using widget commands and  no  insertion
          cursor will be displayed, even if the input focus is in
          the widget.

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

          Specifies an integer value indicating the desired width
          of  the entry window, in average-size characters of the
          widget's font.  If the value is less than or  equal  to
          zero, the widget picks a size just large enough to hold
          its current text.

DESCRIPTION

     The entry command creates a new window (given by  the  path-
     Name  argument)  and  makes  it into an entry widget.  Addi-
     tional options, described above, may  be  specified  on  the
     command  line or in the option database to configure aspects
     of the entry such as its  colors,  font,  and  relief.   The
     entry  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.

     An entry is a widget that displays a  one-line  text  string
     and  allows  that  string to be edited using widget commands
     described below, which are typically bound to keystrokes and
     mouse  actions.   When  first  created, an entry's string is
     empty.  A portion of the entry may be selected as  described
     below.   If  an  entry  is  exporting its selection (see the
     exportSelection option), then it will observe  the  standard
     X11  protocols for handling the selection;  entry selections
     are available as type  STRING.   Entries  also  observe  the
     standard Tk rules for dealing with the input focus.  When an
     entry has the input focus it displays an insertion cursor to
     indicate where new characters will be inserted.

     Entries are capable of displaying strings that are too  long
     to  fit  entirely within the widget's window.  In this case,
     only a portion of the string will  be  displayed;   commands
     described  below  may be used to change the view in the win-
     dow.  Entries use the standard xScrollCommand mechanism  for
     interacting  with  scrollbars  (see  the  description of the
     xScrollCommand option for details).  They also support scan-
     ning, as described below.

WIDGET COMMAND

     The entry 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 entries  take  one  or  more
     indices as arguments.  An index specifies a particular char-
     acter in the entry's string, in any of the following ways:

     number      Specifies the character as  a  numerical  index,
                 where  0  corresponds  to the first character in
                 the string.

     anchor      Indicates the anchor point  for  the  selection,
                 which  is  set  with  the select from and select
                 adjust widget commands.

     end         Indicates the character just after the last  one
                 in  the  entry's  string.  This is equivalent to
                 specifying a numerical index equal to the length
                 of the entry's string.

     insert      Indicates the character adjacent to and  immedi-
                 ately following the insertion cursor.

     sel.first   Indicates the first character in the  selection.
                 It is an error to use this form if the selection
                 isn't in the entry window.

     sel.last    Indicates the character just after the last  one
                 in  the  selection.   It is an error to use this
                 form if the selection isn't in the entry window.

     @number     In  this  form,  number  is  treated  as  an  x-
                 coordinate in the entry's window;  the character
                 spanning that x-coordinate is used.   For  exam-
                 ple, ``@0'' indicates the left-most character in
                 the window.

     Abbreviations may be used for any of the forms  above,  e.g.
     ``e''  or  ``sel.f''.   In general, out-of-range indices are
     automatically rounded to the nearest legal value.

     The following commands are possible for entry widgets:

     pathName bbox index
          Returns a list of four numbers describing the  bounding
          box  of  the  character  given by index.  The first two
          elements of the list give the x and  y  coordinates  of
          the upper-left corner of the screen area covered by the
          character (in pixels relative to the  widget)  and  the
          last  two  elements  give  the  width and height of the
          character, in pixels.  The bounding box may refer to  a
          region outside the visible area of the window.

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

     pathName delete first ?last?
          Delete one or more elements of the entry.  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.    If  last  isn't  specified  it  defaults  to
          first+1, i.e. a single character is deleted.  This com-
          mand returns an empty string.

     pathName get
          Returns the entry's string.

     pathName icursor index
          Arrange for the insertion cursor to be  displayed  just
          before  the character given by index.  Returns an empty
          string.

     pathName index index
          Returns the numerical index corresponding to index.

     pathName insert index string
          Insert the characters of string just before the charac-
          ter indicated by index.  Returns an empty string.

     pathName scan option args
          This command is used to implement scanning on  entries.
          It has two forms, depending on option:

          pathName scan mark x
               Records x and the current view in the  entry  win-
               dow;   used  in conjunction with later scan dragto
               commands.  Typically this  command  is  associated
               with  a  mouse  button  press  in  the widget.  It
               returns an empty string.

          pathName scan dragto x
               This command computes the difference between its x
               argument  and the x argument to the last scan mark
               command for the widget.  It then adjusts the  view
               left  or  right  by  10 times the difference in x-
               coordinates.  This command is typically associated
               with mouse motion events in the widget, to produce
               the effect of dragging the  entry  at  high  speed
               through  the window.  The return value is an empty
               string.

     pathName selection option arg
          This command is used to adjust the selection within  an
          entry.  It has several forms, depending on option:

          pathName selection adjust index
               Locate the end of the  selection  nearest  to  the
               character  given  by index, and adjust that end of
               the selection to be at index  (i.e  including  but
               not  going  beyond  index).   The other end of the
               selection is made  the  anchor  point  for  future
               select   to  commands.   If  the  selection  isn't
               currently in the entry, then a  new  selection  is
               created  to  include  the characters between index
               and  the  most  recent  selection  anchor   point,
               inclusive.  Returns an empty string.

          pathName selection clear
               Clear the selection if it  is  currently  in  this
               widget.   If  the  selection  isn't in this widget
               then the command has no effect.  Returns an  empty
               string.

          pathName selection from index
               Set the selection anchor point to just before  the
               character  given  by  index.   Doesn't  change the
               selection.  Returns an empty string.

          pathName selection present
               Returns 1 if there is are characters  selected  in
               the entry, 0 if nothing is selected.

          pathName selection range start end
               Sets  the  selection  to  include  the  characters
               starting  with the one indexed by start and ending
               with the one just before end.  If  end  refers  to
               the  same  character  as  start or an earlier one,
               then the entry's selection is cleared.

          pathName selection to index
               If index is  before  the  anchor  point,  set  the
               selection  to  the characters from index up to but
               not including the anchor point.  If index  is  the
               same as the anchor point, do nothing.  If index is
               after the anchor point, set the selection  to  the
               characters  from  the  anchor  point up to but not
               including index.  The anchor point  is  determined
               by  the  most  recent select from or select adjust
               command in this widget.  If the selection isn't in
               this  widget then a new selection is created using
               the most recent anchor  point  specified  for  the
               widget.  Returns an empty string.

     pathName xview args
          This command is used to query and change the horizontal
          position  of  the  text in the widget's window.  It can
          take any of the following forms:

          pathName xview
               Returns a list containing two elements.  Each ele-
               ment is a real fraction between 0 and 1;  together
               they describe the horizontal span that is  visible
               in  the window.  For example, if the first element
               is .2 and the second element is  .6,  20%  of  the
               entry's text is off-screen to the left, the middle
               40% is visible in the window, and 40% of the  text
               is  off-screen  to  the right.  These are the same
               values passed to scrollbars via the  - xscrollcom-
               mand option.

          pathName xview index
               Adjusts the view in the window so that the charac-
               ter  given  by index is displayed at the left edge
               of the window.

          pathName xview moveto fraction
               Adjusts the view in the window so that the charac-
               ter  fraction  of the way through the text appears
               at the left edge of the window.  Fraction must  be
               a fraction between 0 and 1.

          pathName xview scroll number what
               This command shifts the view in the window left or
               right  according  to number and what.  Number must
               be an integer.  What must be either units or pages
               or  an  abbreviation  of one of these.  If what is
               units, the view adjusts left or  right  by  number
               average-width characters on the display;  if it is
               pages then the view adjusts by number  screenfuls.
               If  number  is negative then characters farther to
               the left become visible;  if it is  positive  then
               characters farther to the right become visible.

DEFAULT BINDINGS

     Tk automatically creates class  bindings  for  entries  that
     give  them  the following default behavior.  In the descrip-
     tions below,  ``word''  refers  to  a  contiguous  group  of
     letters,  digits, or ``_'' characters, or any single charac-
     ter other than these.

     [1]  Clicking mouse button 1 positions the insertion  cursor
          just  before the character underneath the mouse cursor,
          sets the input focus to this  widget,  and  clears  any
          selection  in the widget.  Dragging with mouse button 1
          strokes out a selection between  the  insertion  cursor
          and the character under the mouse.

     [2]  Double-clicking with mouse button 1  selects  the  word
          under  the  mouse and positions the insertion cursor at
          the beginning of the word.   Dragging  after  a  double
          click  will  stroke out a selection consisting of whole
          words.

     [3]  Triple-clicking with mouse button 1 selects all of  the
          text  in  the  entry and positions the insertion cursor
          before the first character.

     [4]  The ends of the selection can be adjusted  by  dragging
          with  mouse button 1 while the Shift key is down;  this
          will adjust the end of the selection that  was  nearest
          to  the mouse cursor when button 1 was pressed.  If the
          button  is  double-clicked  before  dragging  then  the
          selection will be adjusted in units of whole words.

     [5]  Clicking mouse button 1 with the Control key down  will
          position  the  insertion  cursor  in  the entry without
          affecting the selection.

     [6]  If any normal  printing  characters  are  typed  in  an
          entry,  they are inserted at the point of the insertion
          cursor.

     [7]  The view in the entry can be adjusted by dragging  with
          mouse  button  2.  If mouse button 2 is clicked without
          moving the mouse, the  selection  is  copied  into  the
          entry at the position of the mouse cursor.

     [8]  If the mouse is dragged out of the entry on the left or
          right  sides  while button 1 is pressed, the entry will
          automatically scroll to  make  more  text  visible  (if
          there  is  more  text  off-screen on the side where the
          mouse left the window).

     [9]  The Left and Right keys move the insertion  cursor  one
          character  to  the  left or right;  they also clear any
          selection in the entry and set  the  selection  anchor.
          If Left or Right is typed with the Shift key down, then
          the  insertion  cursor  moves  and  the  selection   is
          extended  to  include  the new character.  Control-Left
          and Control-Right move the insertion cursor  by  words,
          and Control-Shift-Left and Control-Shift-Right move the
          insertion cursor by words and also  extend  the  selec-
          tion.   Control-b and Control-f behave the same as Left
          and Right, respectively.  Meta-b and Meta-f behave  the
          same as Control-Left and Control-Right, respectively.

     [10] The Home key, or Control-a,  will  move  the  insertion
          cursor  to  the  beginning  of  the entry and clear any
          selection in the entry.  Shift-Home moves the insertion
          cursor  to  the beginning of the entry and also extends
          the selection to that point.

     [11] The End key, or Control-e, will move the insertion cur-
          sor  to the end of the entry and clear any selection in
          the entry.  Shift-End moves the cursor to the  end  and
          extends the selection to that point.

     [12] The Select key  and  Control-Space  set  the  selection
          anchor  to  the position of the insertion cursor.  They
          don't affect the current selection.   Shift-Select  and
          Control-Shift-Space adjust the selection to the current
          position of the insertion cursor,  selecting  from  the
          anchor  to  the  insertion  cursor if there was not any
          selection previously.

     [13] Control-/ selects all the text in the entry.

     [14] Control-\ clears any selection in the entry.

     [15] The F16 key (labelled Copy on many Sun workstations) or
          Meta-w  copies the selection in the widget to the clip-
          board, if there is a selection.

     [16] The F20 key (labelled Cut on many Sun workstations)  or
          Control-w  copies  the  selection  in the widget to the
          clipboard and deletes the selection.  If  there  is  no
          selection in the widget then these keys have no effect.

     [17] The F18 key (labelled Paste on many  Sun  workstations)
          or  Control-y  inserts the contents of the clipboard at
          the position of the insertion cursor.

     [18] The Delete key deletes the selection, if there  is  one
          in the entry.  If there is no selection, it deletes the
          character to the right of the insertion cursor.

     [19] The BackSpace key and Control-h delete  the  selection,
          if  there  is  one in the entry.  If there is no selec-
          tion, it deletes the  character  to  the  left  of  the
          insertion cursor.

     [20] Control-d deletes the character to  the  right  of  the
          insertion cursor.

     [21] Meta-d deletes the word to the right of  the  insertion
          cursor.

     [22] Control-k deletes all the characters to  the  right  of
          the insertion cursor.

     [23] Control-w deletes the word to the left of the insertion
          cursor.

     [24] Control-t reverses the order of the two  characters  to
          the right of the insertion cursor.

     If the entry is disabled using the -state option,  then  the
     entry's view can still be adjusted and text in the entry can
     still be selected, but no insertion cursor will be displayed
     and no text modifications will take place.

     The behavior of entries can be changed by defining new bind-
     ings for individual widgets or by redefining the class bind-
     ings.

KEYWORDS

     entry, widget
itcl2.2/html/tk4.2/event.n.html100666 1751 0 47125 6423554666 15156 0ustar kunkeewheel tk4.2 User Commands - event

tk4.2 User Commands - event

NAME

     event  -  Miscellaneous  event  facilities:  define  virtual
     events and generate events

SYNOPSIS

     event option ?arg arg ...?

DESCRIPTION

     The event command provides several  facilities  for  dealing
     with  window  system events, such as defining virtual events
     and synthesizing events.  The command has several  different
     forms,  determined  by  the  first  argument.  The following
     forms are currently supported:

     event add <<virtual>> sequence ?sequence ...?
          Associates the virtual event virtual with the  physical
          event  sequence(s)  given by the sequence arguments, so
          that the virtual event will trigger whenever any one of
          the  sequences occurs.  Virtual may be any string value
          and sequence may have any of the values allowed for the
          sequence  argument  to the bind command.  If virtual is
          already defined, the new physical event  sequences  add
          to the existing sequences for the event.

     event delete <<virtual>> ?sequence sequence ...?
          Deletes each of the  sequences  from  those  associated
          with  the  virtual event given by virtual.  Virtual may
          be any string value and sequence may have  any  of  the
          values  allowed  for  the sequence argument to the bind
          command.  Any sequences not currently  associated  with
          virtual  are  ignored.  If no sequence argument is pro-
          vided, all physical event  sequences  are  removed  for
          virtual,  so  that  the  virtual event will not trigger
          anymore.

     event generate window event ?option value option value ...?
          Generates a window event and arranges for it to be pro-
          cessed  just  as if it had come from the window system.
          Window gives the path name of the window for which  the
          event  will  be  generated,  and event provides a basic
          description of the event, such as  <Shift-Button-2>  or
          <<Paste>>.  Event may have any of the forms allowed for
          the sequence argument of the bind command  except  that
          it  must  consist  of  a  single  event  pattern, not a
          sequence.  Option-value pairs may be  used  to  specify
          additional attributes of the event, such as the x and y
          mouse position;  see EVENT FIELDS below.  If the - when
          option   is  not  specified,  the  event  is  processed
          immediately:  all of the handlers for  the  event  will
          complete before the event generate command returns.  If
          the -when option is specified then it  determines  when
          the event is processed.

     event info ?<<virtual>>?
          Returns  information  about  virtual  events.   If  the
          <<virtual>>  argument is omitted, the return value is a
          list of all  the  virtual  events  that  are  currently
          defined.   If  <<virtual>> is specified then the return
          value is a list whose elements are the  physical  event
          sequences  currently  defined  for  the  given  virtual
          event;  if the virtual event is  not  defined  then  an
          empty string is returned.

EVENT FIELDS

     The following options are supported for the  event  generate
     command.   These  correspond to the ``%'' expansions allowed
     in binding scripts for the bind command.

     -above window
          Window specifies the above field for the event,  either
          as  a  window  path  name  or  as an integer window id.
          Valid for Configure events.  Corresponds to the %a sub-
          stitution for binding scripts.

     -borderwidth size
          Size must be  a  screen  distance;   it  specifies  the
          border_width  field for the event.  Valid for Configure
          events.  Corresponds to the %B substitution for binding
          scripts.

     -button number
          Number must be an integer;   it  specifies  the  detail
          field  for  a ButtonPress or ButtonRelease event, over-
          riding any button  number provided in  the  base  event
          argument.  Corresponds to the %b substitution for bind-
          ing scripts.

     -count number
          Number must be an  integer;   it  specifies  the  count
          field   for   the  event.   Valid  for  Expose  events.
          Corresponds to the %c substitution for binding scripts.

     -detail detail
          Detail specifies the detail field  for  the  event  and
          must be one of the following:

               NotifyAncestor          NotifyNonlinearVirtual
               NotifyDetailNone        NotifyPointer
               NotifyInferior          NotifyPointerRoot
               NotifyNonlinear         NotifyVirtual

          Valid for Enter, Leave, FocusIn  and  FocusOut  events.
          Corresponds to the %d substitution for binding scripts.

     -focus boolean
          Boolean must be a  boolean  value;   it  specifies  the
          focus  field  for the event.  Valid for Enter and Leave
          events.  Corresponds to the %f substitution for binding
          scripts.

     -height size
          Size must be  a  screen  distance;   it  specifies  the
          height  field  for  the  event.   Valid  for  Configure
          events.  Corresponds to the %h substitution for binding
          scripts.

     -keycode number
          Number  must be an integer;  it specifies  the  keycode
          field for the event.  Valid for KeyPress and KeyRelease
          events.  Corresponds to the %k substitution for binding
          scripts.

     -keysym name
          Name must be the name of a valid  keysym,  such  as  g,
          space,  or  Return;  its corresponding keycode value is
          used as the keycode field  for  event,  overriding  any
          detail specified in the base event argument.  Valid for
          KeyPress and KeyRelease events.  Corresponds to the  %K
          substitution for binding scripts.

     -mode notify
          Notify specifies the mode field for the event and  must
          be  one  of  NotifyNormal, NotifyGrab, NotifyUngrab, or
          NotifyWhileGrabbed.  Valid for Enter,  Leave,  FocusIn,
          and  FocusOut  events.  Corresponds to the %m substitu-
          tion for binding scripts.

     -override boolean
          Boolean must be a  boolean  value;   it  specifies  the
          override_redirect  field for the event.  Valid for Map,
          Reparent, and Configure events.  Corresponds to the  %o
          substitution for binding scripts.

     -place where
          Where specifies the place field for the event;  it must
          be  either PlaceOnTop or PlaceOnBottom.  Valid for Cir-
          culate events.  Corresponds to the %p substitution  for
          binding scripts.

     -root window
          Window must be either a window path name or an  integer
          window identifier;  it specifies the root field for the
          event.  Valid for  KeyPress,  KeyRelease,  ButtonPress,
          ButtonRelease,   Enter,   Leave,   and  Motion  events.
          Corresponds to the %R substitution for binding scripts.

     -rootx coord
          Coord must be a  screen  distance;   it  specifies  the
          x_root  field  for  the  event.   Valid  for  KeyPress,
          KeyRelease, ButtonPress, ButtonRelease,  Enter,  Leave,
          and  Motion events.  Corresponds to the %X substitution
          for binding scripts.

     -rooty coord
          Coord must be  a  screen  distance;   it  specifies  th
          y_root  field  for  the  event.   Valid  for  KeyPress,
          KeyRelease, ButtonPress, ButtonRelease,  Enter,  Leave,
          and  Motion events.  Corresponds to the %Y substitution
          for binding scripts.

     -sendevent boolean
          Boolean must be a  boolean  value;   it  specifies  the
          send_event  field for the event.  Valid for all events.
          Corresponds to the %E substitution for binding scripts.

     -serial number
          Number must be an integer;   it  specifies  the  serial
          field   for   the   event.    Valid   for  all  events.
          Corresponds to the %# substitution for binding scripts.

     -state state
          State specifies the state field  for  the  event.   For
          KeyPress,   KeyRelease,   ButtonPress,   ButtonRelease,
          Enter, Leave, and Motion events it must be  an  integer
          value.   For  Visibility events it must be one of Visi-
          bilityUnobscured, VisibilityPartiallyObscured, or Visi-
          bilityFullyObscured.   This option overrides any modif-
          iers such as Meta or  Control  specified  in  the  base
          event.   Corresponds to the %s substitution for binding
          scripts.

     -subwindow window
          Window specifies the subwindow  field  for  the  event,
          either  as a path name for a Tk widget or as an integer
          window identifier.   Valid  for  KeyPress,  KeyRelease,
          ButtonPress,  ButtonRelease,  Enter,  Leave, and Motion
          events.   Similar  to  %S  substitution   for   binding
          scripts.

     -time integer
          Integer must be an integer  value;   it  specifies  the
          time   field   for  the  event.   Valid  for  KeyPress,
          KeyRelease, ButtonPress, ButtonRelease,  Enter,  Leave,
          Motion,  and  Property  events.   Corresponds to the %t
          substitution for binding scripts.

     -width size
          Size must be a screen distance;  it specifies the width
          field  for  the  event.   Valid  for  Configure events.
          Corresponds to the %w substitution for binding scripts.

     -when when
          When determines when the event will be  processed;   it
          must have one of the following values:

          now       Process the  event  immediately,  before  the
                    command  returns.  This also happens if the -
                    when option is omitted.

          tail      Place the event on Tcl's event  queue  behind
                    any  events  already queued for this applica-
                    tion.

          head      Place the event at the front of  Tcl's  event
                    queue,  so that it will be handled before any
                    other events already queued.

          mark      Place the event at the front of  Tcl's  event
                    queue  but  behind  any  other events already
                    queued with -when mark.  This option is  use-
                    ful  when  generating a series of events that
                    should be processed in order but at the front
                    of the queue.

     -x coord
          Coord must be a screen distance;  it  specifies  the  x
          field  for  the event.  Valid for KeyPress, KeyRelease,
          ButtonPress,  ButtonRelease,  Motion,   Enter,   Leave,
          Expose,   Configure,   Gravity,  and  Reparent  events.
          Corresponds to the  the  %x  substitution  for  binding
          scripts.

     -y coord
          Coord must be a screen distance;  it  specifies  the  y
          field  for  the event.  Valid for KeyPress, KeyRelease,
          ButtonPress,  ButtonRelease,  Motion,   Enter,   Leave,
          Expose,   Configure,   Gravity,  and  Reparent  events.
          Corresponds to the  the  %y  substitution  for  binding
          scripts.

     Any options that are not specified when generating an  event
     are  filled  with  the  value 0, except for serial, which is
     filled with the next X event serial number.

VIRTUAL EVENT EXAMPLES

     In order for a virtual event binding to trigger, two  things
     must  happen.  First, the virtual event must be defined with
     the event add command.  Second, a binding  must  be  created
     for  the  virtual event with the bind command.  Consider the
     following virtual event definitions:
          event add <<Paste>> <Control-y>
          event add <<Paste>> <Button-2>
          event add <<Save>> <Control-X><Control-S>
          event add <<Save>> <Shift-F12>
     In the bind command, a virtual event can be bound  like  any
     other builtin event type as follows:
          bind Entry <<Paste>> {%W insert [selection get]}
     The double angle brackets are used to specify that a virtual
     event  is  being  bound.   If  the  user  types Control-y or
     presses button 2, or if a <<Paste>> virtual  event  is  syn-
     thesized  with  event  generate,  then the <<Paste>> binding
     will be invoked.

     If a virtual binding  has  the  exact  same  sequence  as  a
     separate  physical  binding,  then the physical binding will
     take precedence.  Consider the following example:
          event add <<Paste>> <Control-y> <Meta-Control-y>
          bind Entry <Control-y> {puts Control-y}
          bind Entry <<Paste>> {puts Paste}
     When the user types Control-y the <Control-y>  binding  will
     be  invoked,  because  a  physical  event is considered more
     specific than a virtual event, all other things being equal.
     However,  when  the  user types Meta-Control-y the <<Paste>>
     binding will be invoked, because the Meta  modifier  in  the
     physical pattern associated with the virtual binding is more
     specific than the  <Control-y>  sequence  for  the  physical
     event.

     Bindings on a virtual event may be created before  the  vir-
     tual event exists.  Indeed, the virtual event never actually
     needs to be defined, for instance, on  platforms  where  the
     specific virtual event would meaningless or ungeneratable.

     When a definition of a virtual event changes  at  run  time,
     all  windows will respond immediately to the new definition.
     Starting from the preceding example, if the  following  code
     is executed:
          bind <Entry> <Control-y> {}
          event add <<Paste>> <Key-F6>
     the behavior will change such in two ways.  First, the  sha-
     dowed  <<Paste>> binding will emerge.  Typing Control-y will
     no longer invoke the <Control-y> binding, but instead invoke
     the  virtual  event  <<Paste>>.  Second, pressing the F6 key
     will now also invoke the <<Paste>> binding.

SEE ALSO

     bind

KEYWORDS

     event, binding, define, handle, virtual event
itcl2.2/html/tk4.2/focus.n.html100666 1751 0 13461 6423554666 15150 0ustar kunkeewheel tk4.2 User Commands - focus

tk4.2 User Commands - focus

NAME

     focus - Manage the input focus

SYNOPSIS

     focus

     focus window

     focus option ?arg arg ...?

DESCRIPTION

     The focus command is used to manage the Tk input focus.   At
     any  given time, one window on each display is designated as
     the focus window;  any key press or key release  events  for
     the  display  are sent to that window.  It is normally up to
     the window manager to redirect the focus among the top-level
     windows  of  a  display.   For example, some window managers
     automatically set the input  focus  to  a  top-level  window
     whenever  the  mouse  enters  it;  others redirect the input
     focus only when the user clicks on a  window.   Usually  the
     window manager will set the focus only to top-level windows,
     leaving it up to the application to redirect the focus among
     the children of the top-level.

     Tk remembers one focus window for each top-level  (the  most
     recent  descendant  of that top-level to receive the focus);
     when the window manager gives the focus to a  top-level,  Tk
     automatically redirects it to the remembered window.  Within
     a top-level Tk uses an  explicit  focus  model  by  default.
     Moving the mouse within a top-level does not normally change
     the focus;  the focus changes only  when  a  widget  decides
     explicitly  to  claim  the  focus (e.g., because of a button
     click), or when the user types a key such as Tab that  moves
     the focus.

     The Tcl procedure tk_focusFollowsMouse  may  be  invoked  to
     create  an implicit focus model:  it reconfigures Tk so that
     the focus is set to a window whenever the mouse  enters  it.
     The Tcl procedures tk_focusNext and tk_focusPrev implement a
     focus order among the windows of a top-level;  they are used
     in  the  default bindings for Tab and Shift-Tab, among other
     things.

     The focus command can take any of the following forms:

     focus
          Returns the path  name  of  the  focus  window  on  the
          display  containing  the application's main window,  or
          an empty string if no window in  this  application  has
          the  focus  on  that  display.   Note:  it is better to
          specify the display explicitly using  - displayof  (see
          below) so that the code will work in applications using
          multiple displays.

     focus window
          If the application currently has  the  input  focus  on
          window's  display,  this command resets the input focus
          for window's display to window  and  returns  an  empty
          string.   If the application doesn't currently have the
          input focus on window's display, window will be  remem-
          bered  as  the  focus for its top-level;  the next time
          the focus arrives at the top-level, Tk will redirect it
          to  window.  If window is an empty string then the com-
          mand does nothing.

     focus -displayof window
          Returns the name of the focus  window  on  the  display
          containing  window.   If  the focus window for window's
          display isn't in this application, the return value  is
          an empty string.

     focus -force window
          Sets the focus of window's display to window,  even  if
          the  application doesn't currently have the input focus
          for the display.  This command  should  be  used  spar-
          ingly,  if  at  all.   In  normal usage, an application
          should not claim the focus  for  itself;   instead,  it
          should  wait  for  the  window  manager  to give it the
          focus.  If window is an empty string then  the  command
          does nothing.

     focus -lastfor window
          Returns the name of the most recent window to have  the
          input focus among all the windows in the same top-level
          as window.  If no window in that top-level has ever had
          the input focus, or if the most recent focus window has
          been  deleted,  then  the  name  of  the  top-level  is
          returned.   The  return  value  is the window that will
          receive the  input  focus  the  next  time  the  window
          manager gives the focus to the top-level.

QUIRKS

     When an internal window receives the input focus, Tk doesn't
     actually  set  the  X  focus to that window;  as far as X is
     concerned, the focus will stay on the top-level window  con-
     taining  the  window  with the focus.  However, Tk generates
     FocusIn and FocusOut events just as if the X focus  were  on
     the internal window.   This approach gets around a number of
     problems that would occur  if  the  X  focus  were  actually
     moved;  the  fact  that  the  X focus is on the top-level is
     invisible unless you use  C  code  to  query  the  X  server
     directly.

KEYWORDS

     events, focus, keyboard, top-level, window manager
itcl2.2/html/tk4.2/focusNext.n.html100666 1751 0 5330 6423554666 15763 0ustar kunkeewheel tk4.2 User Commands - focusNext

tk4.2 User Commands - focusNext

NAME

     tk_focusNext, tk_focusPrev, tk_focusFollowsMouse  -  Utility
     procedures for managing the input focus.

SYNOPSIS

     tk_focusNext window

     tk_focusPrev window

     tk_focusFollowsMouse

DESCRIPTION

     tk_focusNext  is  a  utility  procedure  used  for  keyboard
     traversal.   It  returns the ``next'' window after window in
     focus order.  The focus order is determined by the  stacking
     order  of windows and the structure of the window hierarchy.
     Among siblings, the focus order is the same as the  stacking
     order,  with the lowest window being first.  If a window has
     children, the window is visited first, followed by its chil-
     dren (recursively), followed by its next sibling.  Top-level
     windows other than window are skipped, so that  tk_focusNext
     never returns a window in a different top-level from window.

     After computing the next window, tk_focusNext  examines  the
     window's  - takefocus  option  to  see  whether it should be
     skipped.  If so, tk_focusNext continues on to the next  win-
     dow  in  the focus order, until it eventually finds a window
     that will accept the focus or returns back to window.

     tk_focusPrev is  similar  to  tk_focusNext  except  that  it
     returns the window just before window in the focus order.

     tk_focusFollowsMouse changes the focus model for the  appli-
     cation  to  an implicit one where the window under the mouse
     gets the focus.  After this procedure  is  called,  whenever
     the  mouse enters a window Tk will automatically give it the
     input focus.  The focus command may  be  used  to  move  the
     focus to a window other than the one under the mouse, but as
     soon as the mouse moves into a new  window  the  focus  will
     jump  to that window.  Note: at present there is no built-in
     support for returning the application to an  explicit  focus
     model;   to  do  this  you'll  have  to  write a script that
     deletes the bindings created by tk_focusFollowsMouse.

KEYWORDS

     focus, keyboard traversal, top-level
itcl2.2/html/tk4.2/frame.n.html100666 1751 0 15377 6423554667 15134 0ustar kunkeewheel tk4.2 User Commands - frame

tk4.2 User Commands - frame

NAME

     frame - Create and manipulate frame widgets

SYNOPSIS

     frame pathName ?options?

STANDARD OPTIONS

     -borderwidth    -highlightbackground           -highlightthickness-takefocus
     -cursor         -highlightcolor                -relief

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

WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-background
     Database Name:  background
     Database Class: Background

          This option is the  same  as  the  standard  background
          option  except  that its value may also be specified as
          an empty string.  In this case, the widget will display
          no background or border, and no colors will be consumed
          from its colormap for its background and border.

     Command-Line Name:-class
     Database Name:  class
     Database Class: Class

          Specifies a class for the window.  This class  will  be
          used when querying the option database for the window's
          other options, and it will also be used later for other
          purposes such as bindings.  The class option may not be
          changed with the configure widget command.

     Command-Line Name:-colormap
     Database Name:  colormap
     Database Class: Colormap

          Specifies a colormap to use for the window.  The  value
          may  be  either  new,  in  which case a new colormap is
          created for the window and its children, or the name of
          another  window  (which  must be on the same screen and
          have the same visual as pathName), in  which  case  the
          new  window  will  use  the colormap from the specified
          window.  If the colormap option is not  specified,  the
          new  window uses the same colormap as its parent.  This
          option may not be changed  with  the  configure  widget
          command.


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

          Specifies the desired height for the window in  any  of
          the  forms  acceptable to Tk_GetPixels.  If this option
          is less than or equal to zero then the window will  not
          request any size at all.

     Command-Line Name:-visual
     Database Name:  visual
     Database Class: Visual

          Specifies visual information for the new window in  any
          of  the forms accepted by Tk_GetVisual.  If this option
          is not specified, the new  window  will  use  the  same
          visual  as  its  parent.   The visual option may not be
          modified with the configure widget command.

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

          Specifies the desired width for the window  in  any  of
          the  forms  acceptable to Tk_GetPixels.  If this option
          is less than or equal to zero then the window will  not
          request any size at all.

DESCRIPTION

     The frame command creates a new window (given by  the  path-
     Name argument) and makes it into a frame widget.  Additional
     options, described above, may be specified  on  the  command
     line  or  in the option database to configure aspects of the
     frame such as its background color and  relief.   The  frame
     command returns the path name of the new window.

     A frame is a simple widget.  Its primary purpose is  to  act
     as  a  spacer  or container for complex window layouts.  The
     only features of a frame are its  background  color  and  an
     optional  3-D  border  to  make  the  frame appear raised or
     sunken.

WIDGET COMMAND

     The frame command creates a new Tcl command  whose  name  is
     the  same as the path name of the frame's window.  This com-
     mand may be used to invoke various operations on the widget.
     It has the following general form:
          pathName option ?arg arg ...?
     PathName is the name of the command, which is  the  same  as
     the frame widget's path name.  Option and the args determine
     the exact behavior of the command.  The  following  commands
     are possible for frame widgets:

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

BINDINGS

     When a new frame is created, it has no default  event  bind-
     ings:  frames are not intended to be interactive.

KEYWORDS

     frame, widget
itcl2.2/html/tk4.2/getOpenFile.n.html100666 1751 0 20332 6423554667 16226 0ustar kunkeewheel tk4.2 User Commands - getOpenFile

tk4.2 User Commands - getOpenFile

NAME

     tk_getOpenFile, tk_getSaveFile - pop up a dialog box for the
     user to select a file to open or save.

SYNOPSIS

     tk_getOpenFile ?option value ...?
     tk_getSaveFile ?option value ...?

DESCRIPTION

     The procedures tk_getOpenFile and tk_getSaveFile  pop  up  a
     dialog  box  for  the user to select a file to open or save.
     The tk_getOpenFile command is usually  associated  with  the
     Open  command  in the File menu. Its purpose is for the user
     to select an existing file only. If the user enters an  non-
     existent file, the dialog box gives the user an error prompt
     and requires the user to give an alternative  selection.  If
     an  application  allows  the  user  to  create new files, it
     should do so by providing a separate New menu command.

     The tk_getSaveFile command is usually  associated  with  the
     Save  as command in the File menu. If the user enters a file
     that already exists, the dialog box  prompts  the  user  for
     confirmation whether the existing file should be overwritten
     or not.

     The following option-value pairs  are  possible  as  command
     line arguments to these two commands:

     -defaultextension extension
          Specifies  a  string  that  will  be  appended  to  the
          filename  if  the  user  enters  a  filename without an
          extension. The defaut value is the empty string,  which
          means  no extension will be appended to the filename in
          any case. This option is ignored on the Macintosh plat-
          form, which does not require extensions to filenames.

     -filetypes filePatternList
          If a File types listbox exists in the  file  dialog  on
          the  particular  platform,  this option gives the file-
          types in this listbox. When the user choose a  filetype
          in the listbox, only the files of that type are listed.
          If this option is unspecified, or if it is set  to  the
          empty  list,  or  if the File types listbox is not sup-
          ported by the particular platform then  all  files  are
          listed  regardless  of  their  types.  See  the section
          SPECIFYING FILE PATTERNS below for a discussion on  the
          contents of filePatternList.

     -initialdir directory
          Specifies  that  the  files  in  directory  should   be
          displayed when the dialog pops up. If this parameter is
          not specified, then the files in  the  current  working
          directory  are  displayed.   This option may not always
          work on the Macintosh.  This is not a bug.  Rather, the
          General  Controls  control  panel on the Mac allows the
          end user to override the application default directory.

     -initialfile filename
          Specifies a filename to be displayed in the dialog when
          it   pops   up.   This   option   is   ignored  by  the
          tk_getOpenFile command.

     -parent window
          Makes window the logical parent of the file dialog. The
          file dialog is displayed on top of its parent window.

     -title titleString
          Specifies a string to display as the title of the  dia-
          log  box.  If  this  option  is  not  specified, then a
          default title is displayed. This option is  ignored  on
          the Macintosh platform.

     If  the  user  selects  a  file,  both  tk_getOpenFile   and
     tk_getSaveFile return the full pathname of this file. If the
     user cancels the operation, both commands return  the  empty
     string.

SPECIFYING FILE PATTERNS

     The filePatternList value given by the -filetypes option  is
     a  list of file patterns. Each file pattern is a list of the
     form
          typeName {extension ?extension ...?} ?{macType ?macType ...?}?
     typeName is the name of the file type described by this file
     pattern  and  is  the  text  string that appears in the File
     types listbox. extension is a file extension for  this  file
     pattern.   macType  is a four-character Macintosh file type.
     The list of macTypes is optional  and  may  be  omitted  for
     applications  that  do  not need to execute on the Macintosh
     platform.

     Several file patterns may have the same typeName,  in  which
     case  they  refer  to  the same file type and share the same
     entry in the listbox. When the user selects an entry in  the
     listbox,  all  the files that match at least one of the file
     patterns corresponding to that entry  are  listed.  Usually,
     each  file  pattern  corresponds to a distinct type of file.
     The use of more than one file patterns for one type of  file
     is necessary on the Macintosh platform only.


     On the Macintosh platform, a file matches a file pattern  if
     its  name  matches  at  least one of the extension(s) AND it
     belongs to at least one of the macType(s) of the  file  pat-
     tern.  For  example,  the C Source Files file pattern in the
     sample code matches with files that have a .c extension  AND
     belong  to the macType TEXT. To use the OR rule instead, you
     can use two file patterns, one with the extensions only  and
     the  other with the macType only. The GIF Files file type in
     the sample code matches files that EITHER have a .gif exten-
     sion OR belong to the macType GIFF.

     On the Unix and Windows platforms, a  file  matches  a  file
     pattern  if  its  name  matches  at  at  least  one  of  the
     extension(s) of the file pattern. The macTypes are ignored.

SPECIFYING EXTENSIONS

     On the Unix and Macintosh platforms, extensions are  matched
     using glob-style pattern matching. On the Windows platforms,
     extensions are matched by the underlying  operating  system.
     The types of possible extensions are: (1) the special exten-
     sion * matches  any  file;  (2)  the  special  extension  ""
     matches  any  files that do not have an extension (i.e., the
     filename contains no full stop character); (3) any character
     string that does not contain any wild card characters (* and
     ?).

     Due to the different pattern matching rules on  the  various
     platforms,  to  ensure portability, wild card characters are
     not allowed in the extensions,  except  as  in  the  special
     extension  *. Extensions without a full stop character (e.g,
     ~) are allowed but may not work on all platforms.

EXAMPLE

          set types {
              {{Text Files}       {.txt}        }
              {{TCL Scripts}      {.tcl}        }
              {{C Source Files}   {.c}      TEXT}
              {{GIF Files}        {.gif}        }
              {{GIF Files}        {}        GIFF}
              {{All Files}        *             }
          }
          set filename [tk_getOpenFile -filetypes $types]

          if {$filename != ""} {
              # Open the file ...
          }

KEYWORDS

     file selection dialog
itcl2.2/html/tk4.2/grab.n.html100666 1751 0 13716 6423554667 14750 0ustar kunkeewheel tk4.2 User Commands - grab

tk4.2 User Commands - grab

NAME

     grab - Confine pointer and keyboard events to a window  sub-
     tree

SYNOPSIS

     grab ?-global? window

     grab option ?arg arg ...?

DESCRIPTION

     This command implements simple pointer  and  keyboard  grabs
     for  Tk.   Tk's grabs are different than the grabs described
     in the Xlib documentation.  When a grab is set for a partic-
     ular  window,  Tk  restricts  all pointer events to the grab
     window and its descendants in Tk's window hierarchy.   When-
     ever  the  pointer  is within the grab window's subtree, the
     pointer will behave exactly the same as if there had been no
     grab  at  all  and all events will be reported in the normal
     fashion.  When the pointer is outside window's tree,  button
     presses and releases and mouse motion events are reported to
     window, and window entry and window exit events are ignored.
     The  grab subtree ``owns'' the pointer:  windows outside the
     grab subtree will be visible on the screen but they will  be
     insensitive until the grab is released.  The tree of windows
     underneath the grab window can include top-level windows, in
     which  case all of those top-level windows and their descen-
     dants will continue to receive mouse events during the grab.

     Two forms of grabs are possible:  local and global.  A local
     grab  affects only the grabbing application:  events will be
     reported to other applications as  if  the  grab  had  never
     occurred.   Grabs are local by default.  A global grab locks
     out all applications on the screen, so that only  the  given
     subtree  of  the  grabbing  application will be sensitive to
     pointer events (mouse button presses, mouse button releases,
     pointer  motions, window entries, and window exits).  During
     global grabs the window manager  will  not  receive  pointer
     events either.

     During local grabs, keyboard events  (key  presses  and  key
     releases)  are  delivered as usual:  the window manager con-
     trols which application receives  keyboard  events,  and  if
     they are sent to any window in the grabbing application then
     they are redirected to the focus window.   During  a  global
     grab  Tk  grabs the keyboard so that all keyboard events are
     always sent to the grabbing application.  The focus  command
     is  still  used to determine which window in the application
     receives the keyboard events.  The keyboard grab is released
     when the grab is released.

     Grabs apply to particular displays.  If an  application  has
     windows  on  multiple  displays  then  it  can  establish  a
     separate grab on each display.  The  grab  on  a  particular
     display  affects  only  the  windows on that display.  It is
     possible for different applications on a single  display  to
     have  simultaneous local grabs, but only one application can
     have a global grab on a given display at once.

     The grab command can take any of the following forms:

     grab ?-global? window
          Same as grab set, described below.

     grab current ?window?
          If window is specified, returns the name of the current
          grab  window  in this application for window's display,
          or an empty string if there is no such window.  If win-
          dow  is  omitted, the command returns a list whose ele-
          ments are all of the windows grabbed by  this  applica-
          tion for all displays, or an empty string if the appli-
          cation has no grabs.

     grab release window
          Releases the grab on window if there is one,  otherwise
          does nothing.  Returns an empty string.

     grab set ?-global? window
          Sets a grab on window.  If -global  is  specified  then
          the  grab  is global, otherwise it is local.  If a grab
          was already in effect for this application on  window's
          display then it is automatically released.  If there is
          already  a  grab  on  window  and  it  has   the   same
          global/local  form as the requested grab, then the com-
          mand does nothing.  Returns an empty string.

     grab status window
          Returns none if no grab is  currently  set  on  window,
          local if a local grab is set on window, and global if a
          global grab is set.

BUGS

     It took an incredibly complex and  gross  implementation  to
     produce  the  simple grab effect described above.  Given the
     current implementation, it isn't safe  for  applications  to
     use  the  Xlib  grab facilities at all except through the Tk
     grab procedures.  If applications try to manipulate X's grab
     mechanisms directly, things will probably break.


     If a single process is managing several different Tk  appli-
     cations,  only  one  of  those applications can have a local
     grab for a given display at any given time.  If the applica-
     tions  are  in different processes, this restriction doesn't
     exist.

KEYWORDS

     grab, keyboard events, pointer events, window
itcl2.2/html/tk4.2/grid.n.html100666 1751 0 47545 6423554667 14771 0ustar kunkeewheel tk4.2 User Commands - grid

tk4.2 User Commands - grid

NAME

     grid - Geometry manager that arranges widgets in a grid

SYNOPSIS

     grid option arg ?arg ...?

DESCRIPTION

     The grid command  is  used  to  communicate  with  the  grid
     geometry  manager  that arranges widgets in rows and columns
     inside of another window, called  the  geometry  master  (or
     master  window).   The  grid command can have any of several
     forms, depending on the option argument:

     grid slave ?slave ...? ?options?
          If the first argument to grid is  a  window  name  (any
          value  starting  with  ``.''), then the command is pro-
          cessed in the same way as grid configure.

     grid bbox master ?column row? ?column2 row2?
          With no arguments, the bounding box (in pixels) of  the  |
          grid  is  returned.   The  return  value  consists of 4  |
          integers.  The first two are the pixel offset from  the  |
          master  window (x then y) of the top-left corner of the  |
          grid, and the second two integers  are  the  width  and  |
          height of the grid, also in pixels.  If a single column  |
          and row is specified on  the  command  line,  then  the  |
          bounding  box  for that cell is returned, where the top  |
          left cell is numbered from zero.  If  both  column  and  |
          row  arguments  are  specified,  then  the bounding box  |
          spanning the rows and columns indicated is returned.

     grid columnconfigure master index ?-option value...?
          Query or set the column properties of the index  column
          of  the geometry master, master.  The valid options are
          -minsize, -weight and -pad.  The -minsize  option  sets
          the minimum size, in screen units, that will be permit-
          ted for this column.  The -weight  option  (an  integer
          value)  sets  the  relative weight for apportioning any
          extra spaces among columns.  A weight of zero (0) indi-
          cates  the  column  will not deviate from its requested
          size.  A column whose weight is two will grow at  twice
          the  rate as a column of weight one when extra space is
          allocated to the layout.  The -pad option specifies the  |
          number  of screen units that will be added to the larg-  |
          est window contained completely in that column when the  |
          grid geometry manager requests a size from the contain-  |
          ing window.  If only an option is  specified,  with  no
          value,  the  current  value of that option is returned.
          If only the master window and index is  specified,  all
          the  current  settings  are  returned  in an list of "-
          option value" pairs.

     grid configure slave ?slave ...? ?options?
          The arguments consist of the names of one or more slave
          windows followed by pairs of arguments that specify how
          to manage the slaves.  The characters -,  x and ^,  can
          be  specified  instead  of  a  window name to alter the
          default location  of  a  slave,  as  described  in  the
          ``RELATIVE  PLACEMENT''  section, below.  The following
          options are supported:

          -column n
               Insert the slave  so  that  it  occupies  the  nth
               column  in the grid.  Column numbers start with 0.
               If this option is not supplied, then the slave  is
               arranged  just  to  the  right  of  previous slave
               specified on this call to grid, or column  "0"  if
               it  is  the  first slave.  For each x that immedi-
               ately precedes the slave, the column  position  is
               incremented by one.  Thus the x represents a blank
               column for this row in the grid.

          -columnspan n
               Insert the slave so that it occupies n columns  in
               the  grid.   The default is one column, unless the
               window name is followed by a -, in which case  the
               columnspan  is  incremented  once for each immedi-
               ately following -.

          -in other
               Insert the slave(s) in the master window given  by
               other.   The  default  is the first slave's parent
               window.

          -ipadx amount
               The amount specifies how much horizontal  internal
               padding  to  leave  on  each side of the slave(s).
               This is space is added inside the slave(s) border.
               The  amount  must be a valid screen distance, such
               as 2 or .5c.  It defaults to 0.

          -ipady amount
               The amount specifies how  much  vertical  internal
               padding  to  leave on on the top and bottom of the
               slave(s).  This space is added inside the slave(s)
               border.  The amount  defaults to 0.

          -padx amount
               The amount specifies how much horizontal  external
               padding  to leave on each side of the slave(s), in
               screen units.  The amount  defaults  to  0.   This
               space is added outside the slave(s) border.

          -pady amount
               The amount specifies how  much  vertical  external
               padding  to  leave  on  the  top and bottom of the
               slave(s), in screen units.  The amount defaults to
               0.   This  space  is  added  outside  the slave(s)
               border.

          -row n
               Insert the slave so that it occupies the  nth  row
               in  the  grid.  Row numbers start with 0.  If this
               option is not supplied, then the slave is arranged
               on the same row as the previous slave specified on
               this call to grid, or the first unoccupied row  if
               this is the first slave.

          -rowspan n
               Insert the slave so that it occupies n rows in the
               grid.   The  default is one row.  If the next grid
               command contains ^ characters  instead  of  slaves
               that  line up with the columns of this slave, then
               the rowspan of this slave is extended by one.

          -sticky style
               If a slave's cell is  larger  than  its  requested
               dimensions,  this  option  may be used to position
               (or stretch) the slave within its cell.  Style  is
               a string that contains zero or more of the charac-
               ters n, s, e or w.  The string can optionally con-
               tains  spaces  or  commas,  but  they are ignored.
               Each letter refers to a side (north, south,  east,
               or  west) that the slave will "stick" to.  If both
               n and s (or e and w) are specified, the slave will
               be  stretched to fill the entire height (or width)
               of its cavity.  The  sticky  option  subsumes  the
               combination  of  -anchor and -fill that is used by
               pack.  The default is {}, which causes  the  slave
               to  be  centered  in  its cavity, at its requested
               size.

          If any  of  the  slaves  are  already  managed  by  the
          geometry  manager then any unspecified options for them
          retain their  previous  values  rather  than  receiving
          default values.

     grid forget slave ?slave ...?
          Removes each of the slaves from grid for its master and
          unmaps  their  windows.   The  slaves will no longer be
          managed by the grid geometry manager.   The  configura-
          tion  options for that window are forgotten, so that if
          the slave is managed once more  by  the  grid  geometry
          manager, the initial default settings are used.

     grid info slave
          Returns a list whose elements are  the  current  confi-
          guration  state of the slave given by slave in the same
          option-value form that might be specified to grid  con-
          figure.   The  first two elements of the list are ``-in
          master'' where master is the slave's master.

     grid location master x y
          Given  x and y values in screen units relative  to  the
          master  window, the column and row number at that x and
          y location is returned.  For locations that  are  above
          or to the left of the grid, -1 is returned.

     grid propagate master ?boolean?
          If boolean has a true boolean value such  as  1  or  on
          then propagation is enabled for master, which must be a
          window name (see ``GEOMETRY PROPAGATION''  below).   If
          boolean  has  a false boolean value then propagation is
          disabled for master.  In either of these cases an empty
          string  is  returned.   If  boolean is omitted then the
          command returns 0 or 1 to indicate whether  propagation
          is   currently  enabled  for  master.   Propagation  is
          enabled by default.

     grid rowconfigure master index ?-option value...?
          Query or set the row properties of the index row of the
          geometry  master,  master.  The valid options are -min-
          size, -weight and -pad.  The -minsize option  sets  the
          minimum  size,  in screen units, that will be permitted
          for this row.  The -weight option  (an  integer  value)
          sets  the  relative  weight  for apportioning any extra
          spaces among rows.  A weight of zero (0) indicates  the
          row  will  not  deviate from its requested size.  A row
          whose weight is two will grow at twice the  rate  as  a
          row  of weight one when extra space is allocated to the
          layout.  The -pad option specifies the number of screen  |
          units  that  will  be  added to the largest window con-  |
          tained completely in that row when  the  grid  geometry  |
          manager requests a size from the containing window.  If
          only an option is specified, with no value, the current
          value  of  that option is returned.  If only the master
          window and index is specified, all the current settings
          are returned in an list of "-option value" pairs.

     grid remove slave ?slave ...?
          Removes each of the slaves from grid for its master and
          unmaps  their  windows.   The  slaves will no longer be
          managed by the grid  geometry  manager.   However,  the
          configuration  options  for that window are remembered,
          so that if the slave is managed once more by  the  grid
          geometry manager, the previous values are retained.

     grid size master
          Returns the size of the grid (in columns then rows) for
          master.   The  size  is  determined either by the slave
          occupying the largest row or  column,  or  the  largest
          column  or  row  with a minsize, weight, or pad that is
          non-zero.

     grid slaves master ?-option value?
          If no options are supplied, a list of all of the slaves
          in  master  are  returned, most recently manages first.
          Option can be either -row or -column which causes  only
          the slaves in the row (or column) specified by value to
          be returned.

RELATIVE PLACEMENT

     The grid command contains a limited set of capabilities that
     permit  layouts to be created without specifying the row and
     column information for each slave.  This permits  slaves  to
     be  rearranged, added, or removed without the need to expli-
     citly specify row and column information.  When no column or
     row information is specified for a slave, default values are
     chosen for column, row, columnspan and rowspan at  the  time
     the  slave  is managed. The values are chosen based upon the
     current layout of the grid, the position of the slave  rela-
     tive to other slaves in the same grid command, and the pres-
     ence of the characters -, ^, and ^  in  grid  command  where
     slave names are normally expected.

          -     This increases the columnspan of the slave to the
               left.   Several  - 's  in  a row will successively
               increase the columnspan. A - may not follow a ^ or
               a x.

          x    This leaves an empty column between the  slave  on
               the left and the slave on the right.

          ^    This extends the rowspan of the  slave  above  the
               ^'s  in the grid.  The number of ^'s in a row must
               match the number of columns spanned by  the  slave
               above it.

THE GRID ALGORITHM

     The grid geometry manager  lays  out  its  slaves  in  three
     steps.   In  the  first step, the minimum size needed to fit
     all of the slaves  is  computed,  then  (if  propagation  is
     turned on), a request is made of the master window to become
     that size.  In the second step, the requested size  is  com-
     pared  against  the actual size of the master.  If the sizes
     are different, then spaces is added to or  taken  away  from
     the  layout  as  needed.   For the final step, each slave is
     positioned in its row(s) and column(s) based on the  setting
     of its sticky flag.

     To compute the minimum size of a layout, the  grid  geometry
     manager  first  looks  at  all  slaves  whose columnspan and
     rowspan values are one, and computes  the  nominal  size  of
     each  row or column to be either the minsize for that row or
     column, or the sum of the padding plus the size of the larg-
     est  slave,  whichever  is  greater.   Then the slaves whose
     rowspans or columnspans are greater than one  are  examined.
     If  a  group of rows or columns need to be increased in size
     in order to accommodate these slaves, then  extra  space  is
     added  to  each  row or column in the group according to its
     weight.  For each group whose  weights  are  all  zero,  the
     additional space is apportioned equally.

     For masters whose size is larger than the requested  layout,
     the additional space is apportioned according to the row and
     column weights.  If all of the weights are zero, the  layout
     is  centered  within  its master.  For masters whose size is
     smaller than the requested layout, space is taken away  from
     columns  and rows according to their weights.  However, once
     a column or row shrinks to its minsize, its weight is  taken
     to be zero.  If more space needs to be removed from a layout
     than would be permitted, as when all the rows or columns are
     at  there minimum sizes, the layout is clipped on the bottom
     and right.

GEOMETRY PROPAGATION

     The grid geometry manager normally computes how large a mas-
     ter  must  be  to just exactly meet the needs of its slaves,
     and it sets the requested width and height of the master  to
     these  dimensions.  This causes geometry information to pro-
     pagate up through a window hierarchy to a  top-level  window
     so that the entire sub-tree sizes itself to fit the needs of
     the leaf windows.  However, the grid propagate  command  may
     be used to turn off propagation for one or more masters.  If
     propagation is disabled then grid will not set the requested
     width  and  height of the master window.  This may be useful
     if, for example, you wish for a  master  window  to  have  a
     fixed size that you specify.

RESTRICTIONS ON MASTER WINDOWS

     The master for each slave must either be the slave's  parent
     (the  default)  or a descendant of the slave's parent.  This
     restriction is necessary to guarantee that the slave can  be
     placed  over  any part of its master that is visible without
     danger of the slave being clipped by its parent.   In  addi-  |
     tion, all slaves in one call to grid must have the same mas-  |
     ter.

STACKING ORDER

     If the master for a slave is not its parent  then  you  must
     make  sure  that  the  slave is higher in the stacking order
     than the master.  Otherwise  the  master  will  obscure  the
     slave and it will appear as if the slave hasn't been managed
     correctly.  The easiest way to make sure the slave is higher
     than  the  master is to create the master window first:  the
     most recently created window will be highest in the stacking
     order.

CREDITS

     The grid command is based on ideas taken  from  the  GridBag
     geometry  manager  written by Doug. Stein, and the blt_table
     geometry manager, written by George Howlett.

KEYWORDS

     geometry manager, location, grid, cell,  propagation,  size,
     pack
itcl2.2/html/tk4.2/image.n.html100666 1751 0 10177 6423554667 15115 0ustar kunkeewheel tk4.2 User Commands - image

tk4.2 User Commands - image

NAME

     image - Create and manipulate images

SYNOPSIS

     image option ?arg arg ...?

DESCRIPTION

     The image command is  used  to  create,  delete,  and  query
     images.   It  can take several different forms, depending on
     the option argument.  The legal forms are:

     image create type ?name? ?option value ...?
          Creates a new image and returns its name.  type  speci-
          fies  the  type  of the image, which must be one of the
          types currently defined (e.g., bitmap).  name specifies
          the name for the image;  if it is omitted then Tk picks
          a name of the form  imagex,  where  x  is  an  integer.
          There  may  be  any number of option-value pairs, which
          provide configuration options for the new  image.   The
          legal  set  of  options  is defined separately for each
          image type;  see below for details on the  options  for
          built-in  image  types.   If an image already exists by
          the given name then it is replaced with the  new  image
          and any instances of that image will redisplay with the
          new contents.

     image delete ?name name ...?
          Deletes each of the named images and returns  an  empty
          string.  If there are instances of the images displayed
          in widgets, the images won't actually be deleted  until
          all  of the instances are released.  However, the asso-
          ciation between the instances  and  the  image  manager
          will  be dropped.  Existing instances will retain their
          sizes but redisplay as empty areas.  If a deleted image
          is  recreated  with  another  call to image create, the
          existing instances will use the new image.

     image height name
          Returns a decimal string giving  the  height  of  image
          name in pixels.

     image names
          Returns a list containing the  names  of  all  existing
          images.

     image type name
          Returns the type of image name (the value of  the  type
          argument to image create when the image was created).

     image types
          Returns a list whose elements  are  all  of  the  valid
          image  types  (i.e., all of the values that may be sup-
          plied for the type argument to image create).

     image width name
          Returns a decimal string giving the width of image name
          in pixels.

BUILT-IN IMAGE TYPES

     The following image types are defined by Tk so they will  be
     available in any Tk application.  Individual applications or
     extensions may define additional types.

     bitmap
          Each pixel in the image displays a foreground color,  a
          background  color,  or  nothing.  See the bitmap manual
          entry for more information.

     photo
          Displays a variety of full-color images, using  dither-
          ing  to  approximate  colors  on  displays with limited
          color capabilities.  See the  photo  manual  entry  for
          more information.

KEYWORDS

     height, image, types of images, width
itcl2.2/html/tk4.2/label.n.html100666 1751 0 13064 6423554667 15110 0ustar kunkeewheel tk4.2 User Commands - label

tk4.2 User Commands - label

NAME

     label - Create and manipulate label widgets

SYNOPSIS

     label pathName ?options?

STANDARD OPTIONS

     -anchor         -font          -image          -takefocus
     -background     -foreground    -justify        -text
     -bitmap         -highlightbackground           -padx-textvariable
     -borderwidth    -highlightcolor                -pady-underline
     -cursor         -highlightthickness            -relief-wraplength

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

WIDGET-SPECIFIC OPTIONS

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

          Specifies a desired height for the label.  If an  image
          or  bitmap  is  being  displayed  in the label then the
          value is in screen units (i.e. any of the forms accept-
          able to Tk_GetPixels); for text it is in lines of text.
          If this option isn't  specified,  the  label's  desired
          height is computed from the size of the image or bitmap
          or text being displayed in it.

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

          Specifies a desired width for the label.  If  an  image
          or  bitmap  is  being  displayed  in the label then the
          value is in screen units (i.e. any of the forms accept-
          able  to  Tk_GetPixels);  for text it is in characters.
          If this option isn't  specified,  the  label's  desired
          width  is computed from the size of the image or bitmap
          or text being displayed in it.

DESCRIPTION

     The label command creates a new window (given by  the  path-
     Name argument) and makes it into a label widget.  Additional
     options, described above, may be specified  on  the  command
     line  or  in the option database to configure aspects of the
     label such as its colors, font, text,  and  initial  relief.
     The  label  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 label is a widget that displays a textual  string,  bitmap
     or  image.  If text is displayed, it must all be in a single
     font, but it can occupy multiple lines on the screen (if  it
     contains  newlines or if wrapping occurs because of the wra-
     pLength option) and one of the characters may optionally  be
     underlined  using  the  underline  option.  The label can be
     manipulated in a few  simple  ways,  such  as  changing  its
     relief or text, using the commands described below.

WIDGET COMMAND

     The label 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 label widg-
     ets:

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

BINDINGS

     When a new label is created, it has no default  event  bind-
     ings:  labels are not intended to be interactive.

KEYWORDS

     label, widget
itcl2.2/html/tk4.2/listbox.n.html100666 1751 0 63644 6423554667 15526 0ustar kunkeewheel tk4.2 User Commands - listbox

tk4.2 User Commands - listbox

NAME

     listbox - Create and manipulate listbox widgets

SYNOPSIS

     listbox pathName ?options?

STANDARD OPTIONS

     -background     -foreground    -relief         -takefocus
     -borderwidth    -height        -selectbackground-width
     -cursor         -highlightbackground           -selectborderwidth-xscrollcommand
     -exportselection               -highlightcolor -selectforeground-yscrollcommand
     -font           -highlightthickness            -setgrid

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

WIDGET-SPECIFIC OPTIONS

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

          Specifies the desired height for the window, in  lines.
          If zero or less, then the desired height for the window
          is made just large enough to hold all the  elements  in
          the listbox.

     Command-Line Name:-selectmode
     Database Name:  selectMode
     Database Class: SelectMode

          Specifies one of several styles  for  manipulating  the
          selection.   The  value of the option may be arbitrary,
          but the default bindings expect it to be either single,
          browse,  multiple,  or  extended;  the default value is
          browse.

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

          Specifies the desired width for the window  in  charac-
          ters.   If  the  font doesn't have a uniform width then
          the width of the character ``0'' is used in translating
          from character units to screen units.  If zero or less,
          then the desired width for  the  window  is  made  just
          large enough to hold all the elements in the listbox.

DESCRIPTION

     The listbox command creates a new window (given by the path-
     Name  argument)  and  makes it into a listbox widget.  Addi-
     tional options, described above, may  be  specified  on  the
     command  line or in the option database to configure aspects
     of the listbox such as its colors, font, text,  and  relief.
     The  listbox  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 listbox is a widget that displays a list of  strings,  one
     per  line.   When  first  created, a new listbox has no ele-
     ments.  Elements may be added or deleted using  widget  com-
     mands  described  below.   In addition, one or more elements
     may be selected as described below.  If a listbox is export-
     ing its selection (see exportSelection option), then it will
     observe the standard X11 protocols for handling  the  selec-
     tion.   Listbox selections are available as type STRING; the
     value of the selection will be the text of the selected ele-
     ments, with newlines separating the elements.

     It is not necessary for all the elements to be displayed  in
     the listbox window at once;  commands described below may be
     used to change the view  in  the  window.   Listboxes  allow
     scrolling  in both directions using the standard xScrollCom-
     mand and yScrollCommand options.  They  also  support  scan-
     ning, as described below.

INDICES

     Many of the widget commands for listboxes take one  or  more
     indices  as arguments.  An index specifies a particular ele-
     ment of the listbox, in any of the following ways:

     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.

     In the widget command descriptions  below,  arguments  named
     index, first, and last always contain text indices in one of
     the above forms.

WIDGET COMMAND

     The listbox 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 listbox widg-
     ets:

     pathName activate index
          Sets the active element to the one indicated by  index.
          The  active element is drawn with an underline when the
          widget has the  input  focus,  and  its  index  may  be
          retrieved with the index active.

     pathName bbox index
          Returns a list of four numbers describing the  bounding
          box  of  the  text  in the element given by index.  The
          first two elements of the list give the x and y coordi-
          nates  of  the  upper-left  corner  of  the screen area
          covered by the text (specified in  pixels  relative  to
          the  widget)  and  the last two elements give the width
          and height of the area, in pixels.  If no part  of  the
          element  given  by  index is visible on the screen then
          the result is an empty string;  if the element is  par-
          tially  visible,  the result gives the full area of the
          element, including any parts that are not visible.

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

     pathName curselection
          Returns a list containing the numerical indices of  all
          of  the  elements  in  the  listbox  that are currently
          selected.  If there are no  elements  selected  in  the
          listbox then an empty string is returned.

     pathName delete first ?last?
          Deletes one or more elements of the listbox.  First and
          last are indices specifying the first and last elements
          in the range to delete.  If  last  isn't  specified  it
          defaults to first, i.e. a single element is deleted.

     pathName get first ?last?
          If last is omitted, returns the contents of the listbox
          element  indicated by first.  If last is specified, the
          command returns a list whose elements are  all  of  the
          listbox  elements  between  first  and last, inclusive.
          Both first and last may have any of the standard  forms
          for indices.

     pathName index index
          Returns a decimal string giving the integer index value
          that corresponds to index.

     pathName insert index ?element element ...?
          Inserts zero or more new  elements  in  the  list  just
          before  the element given by index.  If index is speci-
          fied as end then the new elements are added to the  end
          of the list.  Returns an empty string.

     pathName nearest y
          Given a y-coordinate within the  listbox  window,  this
          command returns the index of the (visible) listbox ele-
          ment nearest to that y-coordinate.

     pathName scan option args
          This command is used to  implement  scanning  on  list-
          boxes.  It has two forms, depending on option:

          pathName scan mark x y
               Records x and y and the current view in the  list-
               box  window;   used in conjunction with later scan
               dragto commands.  Typically this command is  asso-
               ciated  with  a  mouse button press in the widget.
               It returns an empty string.

          pathName scan dragto x y.
               This command computes the difference between its x
               and  y  arguments and the x and y arguments to the
               last scan mark command for the  widget.   It  then
               adjusts  the  view  by  10 times the difference in
               coordinates.  This command is typically associated
               with mouse motion events in the widget, to produce
               the effect of dragging  the  list  at  high  speed
               through  the window.  The return value is an empty
               string.

     pathName see index
          Adjust the view in the  listbox  so  that  the  element
          given  by  index is visible.  If the element is already
          visible then the command has no effect; if the  element
          is near one edge of the window then the listbox scrolls
          to bring the element into view at the edge;   otherwise
          the listbox scrolls to center the element.

     pathName selection option arg
          This command is used to adjust the selection  within  a
          listbox.  It has several forms, depending on option:

          pathName selection anchor index
               Sets the selection anchor to the element given  by
               index.   The  selection  anchor  is the end of the
               selection that  is  fixed  while  dragging  out  a
               selection with the mouse.  The index anchor may be
               used to refer to the anchor element.

          pathName selection clear first ?last?
               If any of the  elements  between  first  and  last
               (inclusive)  are  selected,  they  are deselected.
               The selection state is not  changed  for  elements
               outside this range.

          pathName selection includes index
               Returns 1 if the element  indicated  by  index  is
               currently selected, 0 if it isn't.

          pathName selection set first ?last?
               Selects all of the elements in the  range  between
               first  and  last, inclusive, without affecting the
               selection state of elements outside that range.

     pathName size
          Returns a decimal string indicating the total number of
          elements in the listbox.

     pathName xview args
          This command is used to query and change the horizontal
          position of the information in the widget's window.  It
          can take any of the following forms:

          pathName xview
               Returns a list containing two elements.  Each ele-
               ment is a real fraction between 0 and 1;  together
               they describe the horizontal span that is  visible
               in  the window.  For example, if the first element
               is .2 and the second element is  .6,  20%  of  the
               listbox's text is off-screen to the left, the mid-
               dle 40% is visible in the window, and 40%  of  the
               text  is  off-screen  to the right.  These are the
               same  values  passed  to  scrollbars  via  the   -
               xscrollcommand option.

          pathName xview index
               Adjusts the view in the window so that the charac-
               ter  position  given  by index is displayed at the
               left edge of the window.  Character positions  are
               defined by the width of the character 0.

          pathName xview moveto fraction
               Adjusts the view in the window so that fraction of
               the  total width of the listbox text is off-screen
               to the left.  fraction must be a fraction  between
               0 and 1.

          pathName xview scroll number what
               This command shifts the view in the window left or
               right  according  to number and what.  Number must
               be an integer.  What must be either units or pages
               or  an  abbreviation  of one of these.  If what is
               units, the view adjusts left or  right  by  number
               character  units (the width of the 0 character) on
               the display;  if it is pages then the view adjusts
               by  number screenfuls.  If number is negative then
               characters farther to the left become visible;  if
               it  is  positive  then  characters  farther to the
               right become visible.

     pathName yview ?args?
          This command is used to query and change  the  vertical
          position  of  the  text in the widget's window.  It can
          take any of the following forms:

          pathName yview
               Returns a list containing two  elements,  both  of
               which  are  real  fractions  between 0 and 1.  The
               first element gives the position  of  the  listbox
               element  at the top of the window, relative to the
               listbox as  a  whole  (0.5  means  it  is  halfway
               through  the  listbox,  for  example).  The second
               element gives the position of the listbox  element
               just after the last one in the window, relative to
               the listbox as a whole.  These are the same values
               passed  to  scrollbars  via  the  - yscrollcommand
               option.

          pathName yview index
               Adjusts the view in the window so that the element
               given by index is displayed at the top of the win-
               dow.

          pathName yview moveto fraction
               Adjusts the view in the window so that the element
               given  by  fraction appears at the top of the win-
               dow.  Fraction is a fraction between 0 and  1;   0
               indicates  the  first element in the listbox, 0.33
               indicates the element one-third  the  way  through
               the listbox, and so on.

          pathName yview scroll number what
               This command adjusts the view in the window up  or
               down according to number and what.  Number must be
               an integer.  What must be either units  or  pages.
               If  what  is units, the view adjusts up or down by
               number lines;   if  it  is  pages  then  the  view
               adjusts  by number screenfuls.  If number is nega-
               tive then earlier elements become visible;  if  it
               is positive then later elements become visible.

DEFAULT BINDINGS

     Tk automatically creates class bindings for  listboxes  that
     give  them  Motif-like  behavior.  Much of the behavior of a
     listbox  is  determined  by  its  selectMode  option,  which
     selects one of four ways of dealing with the selection.

     If the selection mode is single or browse, at most one  ele-
     ment can be selected in the listbox at once.  In both modes,
     clicking button 1 on an element selects it and deselects any
     other  selected item.  In browse mode it is also possible to
     drag the selection with button 1.

     If the selection mode is multiple or extended, any number of
     elements  may  be  selected at once, including discontiguous
     ranges.  In multiple mode, clicking button 1 on  an  element
     toggles its selection state without affecting any other ele-
     ments.  In extended mode, pressing button 1  on  an  element
     selects  it,  deselects everything else, and sets the anchor
     to the element under the mouse;   dragging  the  mouse  with
     button  1 down extends the selection to include all the ele-
     ments between the anchor and the element  under  the  mouse,
     inclusive.

     Most people will probably want to use browse mode for single
     selections  and  extended  mode for multiple selections; the
     other modes appear to be useful only in special situations.

     In addition to the above behavior, the following  additional
     behavior is defined by the default bindings:

     [1]  In extended mode, the selected range can be adjusted by
          pressing  button 1 with the Shift key down:  this modi-
          fies the selection to consist of the  elements  between
          the  anchor and the element under the mouse, inclusive.
          The un-anchored end of this new selection can  also  be
          dragged with the button down.

     [2]  In extended mode, pressing button 1  with  the  Control
          key  down  starts a toggle operation: the anchor is set
          to the element under the mouse, and its selection state
          is  reversed.   The  selection  state of other elements
          isn't changed.  If the mouse is dragged with  button  1
          down,  then the selection state of all elements between
          the anchor and the element under the mouse  is  set  to
          match  that of the anchor element;  the selection state
          of all other elements remains what it  was  before  the
          toggle operation began.

     [3]  If the mouse leaves the listbox window  with  button  1
          down,  the  window  scrolls away from the mouse, making
          information visible that used to be off-screen  on  the
          side  of  the mouse.  The scrolling continues until the
          mouse re-enters the window, the button is released,  or
          the end of the listbox is reached.

     [4]  Mouse button 2 may be used  for  scanning.   If  it  is
          pressed  and  dragged over the listbox, the contents of
          the listbox drag at high speed  in  the  direction  the
          mouse moves.

     [5]  If the Up or Down key is pressed, the  location  cursor
          (active  element) moves up or down one element.  If the
          selection mode is  browse  or  extended  then  the  new
          active  element is also selected and all other elements
          are deselected.  In extended mode the new  active  ele-
          ment becomes the selection anchor.

     [6]  In extended mode,  Shift-Up  and  Shift-Down  move  the
          location cursor (active element) up or down one element
          and also extend the selection  to  that  element  in  a
          fashion similar to dragging with mouse button 1.

     [7]  The Left and Right keys scroll the  listbox  view  left
          and  right  by  the width of the character 0.  Control-
          Left and Control-Right scroll the listbox view left and
          right  by  the  width of the window.  Control-Prior and
          Control-Next also scroll left and right by the width of
          the window.

     [8]  The Prior and Next keys scroll the listbox view up  and
          down by one page (the height of the window).

     [9]  The Home and End keys scroll the  listbox  horizontally
          to the left and right edges, respectively.

     [10] Control-Home sets the location cursor to the the  first
          element  in  the  listbox,  selects  that  element, and
          deselects everything else in the listbox.

     [11] Control-End sets the location cursor to  the  the  last
          element  in  the  listbox,  selects  that  element, and
          deselects everything else in the listbox.

     [12] In extended mode, Control-Shift-Home extends the selec-
          tion  to  the first element in the listbox and Control-
          Shift-End extends the selection to the last element.

     [13] In multiple mode, Control-Shift-Home moves the location
          cursor   to  the  first  element  in  the  listbox  and
          Control-Shift-End moves the location cursor to the last
          element.

     [14] The space and Select keys make a selection at the loca-
          tion  cursor (active element) just as if mouse button 1
          had been pressed over this element.

     [15] In extended mode, Control-Shift-space and  Shift-Select
          extend  the  selection to the active element just as if
          button 1 had been pressed with the Shift key down.

     [16] In extended mode,  the  Escape  key  cancels  the  most
          recent  selection  and restores all the elements in the
          selected range to their previous selection state.

     [17] Control-slash selects everything in the widget,  except
          in  single  and  browse modes, in which case it selects
          the active element and deselects everything else.

     [18] Control-backslash deselects everything in  the  widget,
          except in browse mode where it has no effect.

     [19] The F16 key (labelled Copy on many Sun workstations) or
          Meta-w  copies the selection in the widget to the clip-
          board, if there is a selection.

     The behavior of listboxes can be  changed  by  defining  new
     bindings  for  individual widgets or by redefining the class
     bindings.

KEYWORDS

     listbox, widget
itcl2.2/html/tk4.2/lower.n.html100666 1751 0 2542 6423554667 15140 0ustar kunkeewheel tk4.2 User Commands - lower

tk4.2 User Commands - lower

NAME

     lower - Change a window's position in the stacking order

SYNOPSIS

     lower window ?belowThis?

DESCRIPTION

     If the belowThis argument is omitted then the command lowers
     window so that it is below all of its siblings in the stack-
     ing order (it will be obscured by any siblings that  overlap
     it  and  will  not  obscure  any siblings).  If belowThis is
     specified then it must be the path name of a window that  is
     either a sibling of window or the descendant of a sibling of
     window.  In this case the lower command will  insert  window
     into  the stacking order just below belowThis (or the ances-
     tor of belowThis that is a sibling of  window);  this  could
     end up either raising or lowering window.

SEE ALSO

     raise

KEYWORDS

     lower, obscure, stacking order
itcl2.2/html/tk4.2/menu.n.html100666 1751 0 107503 6423554670 15011 0ustar kunkeewheel tk4.2 User Commands - menu

tk4.2 User Commands - menu

NAME

     menu - Create and manipulate menu widgets

SYNOPSIS

     menu pathName ?options?

STANDARD OPTIONS

     -activebackground              -background     -disabledforeground-relief
     -activeborderwidth             -borderwidth    -font-takefocus
     -activeforeground              -cursor         -foreground

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

WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-postcommand
     Database Name:  postCommand
     Database Class: Command

          If this option is specified then it provides a Tcl com-
          mand to execute each time the menu is posted.  The com-
          mand is invoked by the post widget command before post-
          ing the menu.

     Command-Line Name:-selectcolor
     Database Name:  selectColor
     Database Class: Background

          For menu entries that are check buttons or  radio  but-
          tons, this option specifies the color to display in the
          indicator when the check  button  or  radio  button  is
          selected.

     Command-Line Name:-tearoff
     Database Name:  tearOff
     Database Class: TearOff

          This option must have a  proper  boolean  value,  which
          specifies  whether  or  not  the  menu should include a
          tear-off entry at the top.  If so,  it  will  exist  as
          entry  0  of the menu and the other entries will number
          starting at 1.  The default menu bindings  arrange  for
          the  menu  to  be  torn  off when the tear-off entry is
          invoked.

     Command-Line Name:-tearoffcommand
     Database Name:  tearOffCommand
     Database Class: TearOffCommand

          If this option has a non-empty value, then it specifies
          a  Tcl command to invoke whenever the menu is torn off.
          The actual command will consist of the  value  of  this
          option,  followed  by  a space, followed by the name of
          the menu window, followed by a space, followed  by  the
          name  of  the  name  of  the torn off menu window.  For
          example, if the option's is ``a b'' and  menu  .x.y  is
          torn  off  to  create  a new menu .x.tearoff1, then the
          command ``a b .x.y .x.tearoff1'' will be invoked.

     Command-Line Name:-transient
     Database Name:  transient
     Database Class: Transient

          This option must have a boolean value.  True means that
          the  menu  is used on a transient basis, e.g. as a pop-
          up, pull-down, or cascaded menu.  False means that  the
          menu  will be displayed on the screen continuously, for
          example as a torn-off menu.  If the option is true,  no
          window manager border will be displayed around the menu
          and  redisplay  will  be  optimized  using  X's  ``save
          under'' facility.

INTRODUCTION

     The menu command creates a new top-level  window  (given  by
     the  pathName  argument)  and  makes  it into a menu widget.
     Additional options, described above, may be specified on the
     command  line or in the option database to configure aspects
     of the menu such as its colors and font.  The  menu  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 menu is a widget that displays a  collection  of  one-line
     entries arranged in a column.  There exist several different
     types of entries, each with different  properties.   Entries
     of  different  types may be combined in a single menu.  Menu
     entries are not the same as entry widgets.   In  fact,  menu
     entries  are  not  even distinct widgets; the entire menu is
     one widget.

     Menu entries are displayed with up to three separate fields.
     The  main  field  is a label in the form of a text string, a
     bitmap, or an image, controlled by the -label, -bitmap,  and
     - image  options for the entry.  If the  -accelerator option
     is specified for an entry then a  second  textual  field  is
     displayed  to the right of the label.  The accelerator typi-
     cally describes a keystroke sequence that may  be  typed  in
     the  application  to  cause  the same result as invoking the
     menu entry.  The third field is an indicator.  The indicator
     is  present only for checkbutton or radiobutton entries.  It
     indicates whether the entry  is  selected  or  not,  and  is
     displayed to the left of the entry's string.

     In normal use, an entry becomes active (displays itself dif-
     ferently)  whenever the mouse pointer is over the entry.  If
     a mouse button is released over the entry then the entry  is
     invoked.   The  effect  of  invocation is different for each
     type of entry; these effects are described below in the sec-
     tions on individual entries.

     Entries may be  disabled,  which  causes  their  labels  and
     accelerators  to  be  displayed  with  dimmer  colors.   The
     default menu bindings will not allow a disabled entry to  be
     activated  or  invoked.  Disabled entries may be re-enabled,
     at which point it becomes possible to  activate  and  invoke
     them again.

COMMAND ENTRIES

     The most common kind of menu entry is a command entry, which
     behaves  much like a button widget.  When a command entry is
     invoked, a Tcl command is  executed.   The  Tcl  command  is
     specified with the -command option.

SEPARATOR ENTRIES

     A separator is an entry that is displayed  as  a  horizontal
     dividing line.  A separator may not be activated or invoked,
     and it has no behavior other than its display appearance.

CHECKBUTTON ENTRIES

     A checkbutton menu entry behaves  much  like  a  checkbutton
     widget.   When  it  is  invoked  it  toggles  back and forth
     between the selected and deselected states.  When the  entry
     is  selected,  a  particular value is stored in a particular
     global variable (as determined by the -onvalue and -variable
     options  for  the  entry);   when  the  entry  is deselected
     another value (determined by the -offvalue option) is stored
     in  the  global  variable.  An indicator box is displayed to
     the left of the label in a checkbutton entry.  If the  entry
     is  selected then the indicator's center is displayed in the
     color given by the -selectcolor option for the entry; other-
     wise  the  indicator's center is displayed in the background
     color for the menu.  If a -command option is specified for a
     checkbutton entry, then its value is evaluated as a Tcl com-
     mand each time the entry is  invoked;   this  happens  after
     toggling the entry's selected state.

RADIOBUTTON ENTRIES


     A radiobutton menu entry behaves  much  like  a  radiobutton
     widget.   Radiobutton  entries  are  organized  in groups of
     which only one entry may be selected at a time.  Whenever  a
     particular  entry  becomes  selected  it stores a particular
     value into a particular global variable  (as  determined  by
     the  - value  and  - variable  options for the entry).  This
     action causes any  previously-selected  entry  in  the  same
     group   to  deselect  itself.   Once  an  entry  has  become
     selected, any change to the entry's associated variable will
     cause the entry to deselect itself.  Grouping of radiobutton
     entries is determined by their associated variables:  if two
     entries  have  the same associated variable then they are in
     the same group.  An indicator diamond is  displayed  to  the
     left  of  the label in each radiobutton entry.  If the entry
     is selected then the indicator's center is displayed in  the
     color given by the -selectcolor option for the entry; other-
     wise the indicator's center is displayed in  the  background
     color for the menu.  If a -command option is specified for a
     radiobutton entry, then its value is evaluated as a Tcl com-
     mand  each  time  the  entry is invoked;  this happens after
     selecting the entry.

CASCADE ENTRIES

     A cascade entry is one with an associated  menu  (determined
     by  the  -menu option).  Cascade entries allow the construc-
     tion of cascading menus.  The postcascade widget command can
     be  used  to post and unpost the associated menu just to the
     right of the cascade entry.  The associated menu must  be  a
     child  of  the  menu  containing  the cascade entry (this is
     needed in order for menu traversal to work correctly).

     A cascade entry posts its associated menu by invoking a  Tcl
     command of the form
          menu post x y
     where menu is the path name of the associated  menu,  and  x
     and  y  are  the  root-window coordinates of the upper-right
     corner of  the  cascade  entry.   The  lower-level  menu  is
     unposted by executing a Tcl command with the form
          menu unpost
     where menu is the name of the associated menu.

     If a -command option is specified for a cascade  entry  then
     it  is  evaluated  as  a  Tcl  command whenever the entry is
     invoked.

TEAR-OFF ENTRIES

     A tear-off entry appears at the top of the menu  if  enabled
     with  the tearOff option.  It is not like other menu entries
     in that it cannot be created with the add widget command and
     cannot  be  deleted  with the delete widget command.  When a
     tear-off entry is created it appears as a dashed line at the
     top  of  the menu.  Under the default bindings, invoking the
     tear-off entry causes a torn-off copy to be made of the menu
     and all of its submenus.

WIDGET COMMAND

     The menu 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 menu take as one  argument
     an  indicator  of  which  entry  of  the 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 menu, 1
                 to the entry below it, and so on.

     active      Indicates the entry that  is  currently  active.
                 If   no  entry  is  active  then  this  form  is
                 equivalent to none.  This form may not be abbre-
                 viated.

     end         Indicates the bottommost entry in the menu.   If
                 there  are no entries in the menu then this form
                 is equivalent to none.  This  form  may  not  be
                 abbreviated.

     last        Same as end.

     none        Indicates ``no entry at  all'';   this  is  used
                 most  commonly with the activate option to deac-
                 tivate all the entries in  the  menu.   In  most
                 cases  the  specification of none causes nothing
                 to happen in the widget command.  This form  may
                 not be abbreviated.

     @number     In  this  form,  number  is  treated  as  a   y-
                 coordinate  in  the  menu's  window;   the entry
                 closest to that y-coordinate is used.  For exam-
                 ple,  ``@0'' indicates the top-most entry in the
                 window.

     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 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 menu widgets:

     pathName activate index
          Change the state of the entry  indicated  by  index  to
          active  and  redisplay it using its active colors.  Any
          previously-active entry is deactivated.   If  index  is
          specified  as  none,  or if the specified entry is dis-
          abled, then the menu ends  up  with  no  active  entry.
          Returns an empty string.

     pathName add type ?option value option value ...?
          Add a new entry to the bottom of  the  menu.   The  new
          entry's  type  is given by type and must be one of cas-
          cade, checkbutton, command, radiobutton, or  separator,
          or a unique abbreviation of one of the above.  If addi-
          tional arguments are present, they specify any  of  the
          following options:

          -activebackground value
               Specifies a background color to use for displaying
               this  entry  when it is active.  If this option is
               specified as an empty string (the  default),  then
               the  activeBackground  option for the overall menu
               is used.  If the tk_strictMotif variable has  been
               set  to request strict Motif compliance, then this
               option is ignored and the - background  option  is
               used  in  its place.  This option is not available
               for separator or tear-off entries.

          -activeforeground value
               Specifies a foreground color to use for displaying
               this  entry  when it is active.  If this option is
               specified as an empty string (the  default),  then
               the  activeForeground  option for the overall menu
               is used.  This option is not available for separa-
               tor or tear-off entries.

          -accelerator value
               Specifies a string to display at the right side of
               the menu entry.  Normally describes an accelerator
               keystroke sequence that may be typed to invoke the
               same  function  as the menu entry.  This option is
               not available for separator or tear-off entries.

          -background value
               Specifies a background color to use for displaying
               this entry when it is in the normal state (neither
               active nor disabled).  If this option is specified
               as   an  empty  string  (the  default),  then  the
               background option for the overall  menu  is  used.
               This  option  is  not  available  for separator or
               tear-off entries.

          -bitmap value
               Specifies a bitmap to display in the menu  instead
               of  a  textual label, in any of the forms accepted
               by Tk_GetBitmap.  This option overrides the -label
               option  but  may  be  reset  to an empty string to
               enable a textual label to be displayed.   If  a  -
               image  option  has  been specified, it overrides -
               bitmap.  This option is not available for  separa-
               tor or tear-off entries.

          -command value
               Specifies a Tcl command to execute when  the  menu
               entry  is invoked.  Not available for separator or
               tear-off entries.

          -font value
               Specifies the font to use when drawing  the  label
               or  accelerator  string  in  this  entry.  If this
               option  is  specified  as  an  empty  string  (the
               default) then the font option for the overall menu
               is used.  This option is not available for separa-
               tor or tear-off entries.

          -foreground value
               Specifies a foreground color to use for displaying
               this entry when it is in the normal state (neither
               active nor disabled).  If this option is specified
               as  an  empty string (the default), then the fore-
               ground option for the overall menu is used.   This
               option  is not available for separator or tear-off
               entries.

          -image value
               Specifies an image to display in the menu  instead
               of  a  text  string  or bitmap The image must have
               been created by some previous invocation of  image
               create.   This  option  overrides the -label and -
               bitmap options but may be reset to an empty string
               to   enable  a  textual  or  bitmap  label  to  be
               displayed.   This  option  is  not  available  for
               separator or tear-off entries.

          -indicatoron value
               Available only  for  checkbutton  and  radiobutton
               entries.   Value  is  a  boolean  that  determines
               whether or not the indicator should be displayed.

          -label value
               Specifies a string to display  as  an  identifying
               label  in  the  menu  entry.   Not  available  for
               separator or tear-off entries.

          -menu value
               Available only for cascade entries.  Specifies the
               path  name  of  the  submenu  associated with this
               entry.  The submenu must be a child of the menu.

          -offvalue value
               Available only for checkbutton entries.  Specifies
               the value to store in the entry's associated vari-
               able when the entry is deselected.

          -onvalue value
               Available only for checkbutton entries.  Specifies
               the value to store in the entry's associated vari-
               able when the entry is selected.

          -selectcolor value
               Available only  for  checkbutton  and  radiobutton
               entries.   Specifies  the  color to display in the
               indicator when the  entry  is  selected.   If  the
               value  is  an  empty string (the default) then the
               selectColor option for  the  menu  determines  the
               indicator color.

          -selectimage value
               Available only  for  checkbutton  and  radiobutton
               entries.   Specifies  an  image  to display in the
               entry (in place of the -image option) when  it  is
               selected.   Value  is  the name of an image, which
               must have been created by some previous invocation
               of  image  create.   This option is ignored unless
               the -image option has been specified.

          -state value
               Specifies one of three states for the entry:  nor-
               mal,  active,  or  disabled.   In normal state the
               entry is displayed using the foreground option for
               the  menu and the background option from the entry
               or the menu.  The active state is  typically  used
               when  the  pointer  is  over the entry.  In active
               state the entry is displayed using the activeFore-
               ground   option   for  the  menu  along  with  the
               activebackground option from the entry.   Disabled
               state  means that the entry should be insensitive:
               the default bindings will refuse  to  activate  or
               invoke  the  entry.   In  this  state the entry is
               displayed  according  to  the   disabledForeground
               option for the menu and the background option from
               the entry.   This  option  is  not  available  for
               separator entries.

          -underline value
               Specifies the integer  index  of  a  character  to
               underline  in  the  entry.   This  option  is also
               queried by the default bindings and used to imple-
               ment  keyboard  traversal.   0  corresponds to the
               first character  of  the  text  displayed  in  the
               entry,  1  to the next character, and so on.  If a
               bitmap or image is displayed  in  the  entry  then
               this option is ignored.  This option is not avail-
               able for separator or tear-off entries.

          -value value
               Available only for radiobutton entries.  Specifies
               the value to store in the entry's associated vari-
               able when the entry  is  selected.   If  an  empty
               string  is  specified,  then the -label option for
               the entry as the value to store in the variable.

          -variable value
               Available only  for  checkbutton  and  radiobutton
               entries.   Specifies the name of a global value to
               set when the entry is selected.   For  checkbutton
               entries the variable is also set when the entry is
               deselected.  For radiobutton entries, changing the
               variable  causes  the  currently-selected entry to
               deselect itself.

          The add widget command returns an empty string.

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

     pathName delete index1 ?index2?
          Delete all of  the  menu  entries  between  index1  and
          index2   inclusive.   If  index2  is  omitted  then  it
          defaults to index1.  Attempts to delete a tear-off menu
          entry are ignored (instead, you should change the tear-
          Off option to remove the tear-off entry).

     pathName entrycget index option
          Returns the current value of a configuration option for
          the  entry  given by index.  Option may have any of the
          values accepted by the add widget command.

     pathName entryconfigure index ?options?
          This command  is  similar  to  the  configure  command,
          except that it applies to the options for an individual
          entry, whereas configure applies to the options for the
          menu  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 index index
          Returns the numerical index corresponding to index,  or
          none if index was specified as none.

     pathName insert index type ?option value option value ...?
          Same as the add widget command except that  it  inserts
          the  new  entry  just  before the entry given by index,
          instead of appending to the end of the menu.  The type,
          option,  and  value arguments have the same interpreta-
          tion as for the add widget command.  It is not possible
          to  insert  new menu entries before the tear-off entry,
          if the menu has one.

     pathName invoke index
          Invoke the action of the menu entry.  See the  sections
          on  the  individual  entries  above for details on what
          happens.  If the menu entry is  disabled  then  nothing
          happens.  If the entry has a command associated 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.   Note:   invoking  a  menu
          entry  does  not  automatically  unpost  the menu;  the
          default bindings normally  take  care  of  this  before
          invoking the invoke widget command.

     pathName post x y
          Arrange for the menu to be displayed on the  screen  at
          the  root-window  coordinates  given by x and y.  These
          coordinates are adjusted if necessary to guarantee that
          the entire menu is visible on the screen.  This command
          normally returns an empty string.  If  the  postCommand
          option  has  been specified, then its value is executed
          as a Tcl script before posting the menu and the  result
          of  that  script  is returned as the result of the post
          widget command.  If an error  returns  while  executing
          the command, then the error is returned without posting
          the menu.

     pathName postcascade index
          Posts the submenu associated  with  the  cascade  entry
          given  by index, and unposts any previously posted sub-
          menu.  If index doesn't correspond to a cascade  entry,
          or  if pathName isn't posted, the command has no effect
          except to unpost any currently posted submenu.

     pathName type index
          Returns the type of the  menu  entry  given  by  index.
          This is the type argument passed to the add widget com-
          mand when the entry was created,  such  as  command  or
          separator, or tearoff for a tear-off entry.

     pathName unpost
          Unmap the window so that it is no longer displayed.  If
          a  lower-level  cascaded  menu  is  posted, unpost that
          menu.  Returns an empty string.

     pathName yposition index
          Returns a decimal string giving the y-coordinate within
          the  menu  window  of  the  topmost  pixel in the entry
          specified by index.

MENU CONFIGURATIONS

     The default bindings support four different  ways  of  using
     menus:

     Pulldown Menus
          This is the most common case.  You create one  menubut-
          ton  widget  for each top-level menu, and typically you
          arrange a series of menubuttons in a row in  a  menubar
          window.   You  also  create the top-level menus and any
          cascaded submenus, and tie them  together  with  - menu
          options  in  menubuttons and cascade menu entries.  The
          top-level menu must be a child of the  menubutton,  and
          each submenu must be a child of the menu that refers to
          it.  Once you have done this, the default bindings will
          allow  users  to  traverse and invoke the tree of menus
          via its menubutton;  see the  menubutton  manual  entry
          for details.

     Popup Menus
          Popup menus typically post in response to a mouse  but-
          ton press or keystroke.  You create the popup menus and
          any cascaded submenus, then you call the tk_popup  pro-
          cedure  at  the  appropriate time to post the top-level
          menu.

     Option Menus
          An option menu consists of a menubutton with an associ-
          ated  menu  that  allows  you  to select one of several
          values.  The current value is displayed in the menubut-
          ton  and  is also stored in a global variable.  Use the
          tk_optionMenu procedure to  create  option  menubuttons
          and their menus.

     Torn-off Menus
          You create a torn-off menu  by  invoking  the  tear-off
          entry  at  the  top  of  an existing menu.  The default
          bindings will create a new menu that is a copy  of  the
          original  menu  and  leave  it  permanently posted as a
          top-level window.  The torn-off menu behaves  just  the
          same as the original menu.

DEFAULT BINDINGS

     Tk automatically creates class bindings for menus that  give
     them the following default behavior:

     [1]  When the mouse enters a menu, the entry underneath  the
          mouse  cursor activates;  as the mouse moves around the
          menu, the active entry changes to track the mouse.

     [2]  When the mouse leaves a menu all of the entries in  the
          menu  deactivate,  except in the special case where the
          mouse moves from a menu to a cascaded submenu.

     [3]  When a button is released over a menu, the active entry
          (if  any)  is invoked.  The menu also unposts unless it
          is a torn-off menu.

     [4]  The Space and Return keys invoke the active  entry  and
          unpost the menu.

     [5]  If any of the entries in a menu have letters underlined
          with  with  -underline option, then pressing one of the
          underlined letters (or  its  upper-case  or  lower-case
          equivalent) invokes that entry and unposts the menu.

     [6]  The Escape key aborts  a  menu  selection  in  progress
          without  invoking  any entry.  It also unposts the menu
          unless it is a torn-off menu.

     [7]  The Up and Down keys activate the next higher or  lower
          entry  in  the  menu.   When  one  end  of  the menu is
          reached, the active entry wraps  around  to  the  other
          end.

     [8]  The Left key moves to the next menu to  the  left.   If
          the  current  menu is a cascaded submenu, then the sub-
          menu is unposted and the current menu entry becomes the
          cascade  entry in the parent.  If the current menu is a
          top-level menu  posted  from  a  menubutton,  then  the
          current  menubutton is unposted and the next menubutton
          to the left  is  posted.   Otherwise  the  key  has  no
          effect.   The left-right order of menubuttons is deter-
          mined by their stacking order:   Tk  assumes  that  the
          lowest  menubutton  (which  by default is the first one
          created) is on the left.

     [9]  The Right key moves to the next menu to the right.   If
          the  current entry is a cascade entry, then the submenu
          is posted and the  current menu entry becomes the first
          entry  in  the submenu.  Otherwise, if the current menu
          was posted from a menubutton, then the current menubut-
          ton is unposted and the next menubutton to the right is
          posted.

     Disabled  menu  entries  are  non-responsive:   they   don't
     activate and they ignore mouse button presses and releases.

     The behavior of menus can be changed by defining  new  bind-
     ings for individual widgets or by redefining the class bind-
     ings.

BUGS

     At present it isn't possible to use the option  database  to
     specify values for the options to individual entries.

KEYWORDS

     menu, widget
itcl2.2/html/tk4.2/menubar.n.html100666 1751 0 2216 6423554670 15431 0ustar kunkeewheel tk4.2 User Commands - menubar

tk4.2 User Commands - menubar

NAME

     tk_menuBar, tk_bindForTraversal - Obsolete support for  menu
     bars

SYNOPSIS

     tk_menuBar frame ?menu menu ...?

     tk_bindForTraversal arg arg ...

DESCRIPTION

     These procedures were used in Tk 3.6 and earlier releases to
     help manage pulldown menus and to implement keyboard traver-
     sal of menus.  In Tk 4.0 and  later  releases  they  are  no
     longer   needed.   Stubs  for  these  procedures  have  been
     retained  for  backward  compatibility,  but  they  have  no
     effect.   You  should  remove calls to these procedures from
     your code, since eventually the procedures will go away.

KEYWORDS

     keyboard traversal, menu, menu bar, post
itcl2.2/html/tk4.2/message.n.html100666 1751 0 20463 6423554670 15450 0ustar kunkeewheel tk4.2 User Commands - message

tk4.2 User Commands - message

NAME

     message - Create and manipulate message widgets

SYNOPSIS

     message pathName ?options?

STANDARD OPTIONS

     -anchor         -font          -highlightthickness-takefocus
     -background     -foreground    -padx           -text
     -borderwidth    -highlightbackground           -pady-textvariable
     -cursor         -highlightcolor                -relief-width

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

WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-aspect
     Database Name:  aspect
     Database Class: Aspect

          Specifies  a  non-negative  integer  value   indicating
          desired aspect ratio for the text.  The aspect ratio is
          specified as  100*width/height.   100  means  the  text
          should  be  as  wide  as it is tall, 200 means the text
          should be twice as wide as it is  tall,  50  means  the
          text  should be twice as tall as it is wide, and so on.
          Used to choose line length for  text  if  width  option
          isn't specified.  Defaults to 150.

     Command-Line Name:-justify
     Database Name:  justify
     Database Class: Justify

          Specifies how to justify lines of text.  Must be one of
          left, center, or right.  Defaults to left.  This option
          works together with the anchor, aspect, padX, padY, and
          width  options  to provide a variety of arrangements of
          the text within  the  window.   The  aspect  and  width
          options  determine the amount of screen space needed to
          display the text.  The anchor, padX, and  padY  options
          determine  where  this  rectangular  area  is displayed
          within the widget's  window,  and  the  justify  option
          determines  how each line is displayed within that rec-
          tangular region.  For example, suppose anchor is e  and
          justify  is  left,  and that the message window is much
          larger than needed for the text.   The  the  text  will
          displayed  so that the left edges of all the lines line
          up and the right edge of the longest line is padX  from
          the  right  side  of the window;  the entire text block
          will be centered in the vertical span of the window.

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

          Specifies the length of lines in the window.  The value
          may  have  any of the forms acceptable to Tk_GetPixels.
          If this option has a value greater than zero  then  the
          aspect  option  is  ignored and the width option deter-
          mines the line length.  If this option has a value less
          than  or  equal  to zero, then the aspect option deter-
          mines the line length.

DESCRIPTION

     The message command creates a new window (given by the path-
     Name  argument)  and  makes it into a message widget.  Addi-
     tional options, described above, may  be  specified  on  the
     command  line or in the option database to configure aspects
     of the message such as its colors, font, text,  and  initial
     relief.   The message 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 message is a widget that displays  a  textual  string.   A
     message widget has three special features.  First, it breaks
     up its string into lines in order to produce a given  aspect
     ratio  for  the  window.  The line breaks are chosen at word
     boundaries wherever possible (if  not  even  a  single  word
     would  fit  on  a  line,  then the word will be split across
     lines).  Newline characters in the string  will  force  line
     breaks;  they can be used, for example, to leave blank lines
     in the display.

     The second feature of a  message  widget  is  justification.
     The  text  may be displayed left-justified (each line starts
     at the left side of the window), centered on a  line-by-line
     basis,  or right-justified (each line ends at the right side
     of the window).

     The third feature of a message widget  is  that  it  handles
     control  characters  and  non-printing characters specially.
     Tab characters are replaced with enough blank space to  line
     up  on  the  next 8-character boundary.  Newlines cause line
     breaks.  Other control  characters  (ASCII  code  less  than
     0x20)  and  characters not defined in the font are displayed
     as a four-character sequence \xhh where hh is the  two-digit
     hexadecimal  number  corresponding to the character.  In the
     unusual case where the font doesn't contain all of the char-
     acters in ``0123456789abcdef\x'' then control characters and
     undefined characters are not displayed at all.

WIDGET COMMAND

     The message 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 message widg-
     ets:

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

DEFAULT BINDINGS

     When a new message is created, it has no default event bind-
     ings:  messages are intended for output purposes only.

BUGS

     Tabs don't work very well with  text  that  is  centered  or
     right-justified.  The most common result is that the line is
     justified wrong.

KEYWORDS

     message, widget
itcl2.2/html/tk4.2/menubutton.n.html100666 1751 0 25714 6423554670 16230 0ustar kunkeewheel tk4.2 User Commands - menubutton

tk4.2 User Commands - menubutton

NAME

     menubutton - Create and manipulate menubutton widgets

SYNOPSIS

     menubutton pathName ?options?

STANDARD OPTIONS

     -activebackground              -cursor         -highlightthickness-takefocus
     -activeforeground              -disabledforeground-image-text
     -anchor         -font          -justify        -textvariable
     -background     -foreground    -padx           -underline
     -bitmap         -highlightbackground           -pady-wraplength
     -borderwidth    -highlightcolor                -relief

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

WIDGET-SPECIFIC OPTIONS

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

          Specifies a desired height for the menubutton.   If  an
          image  or  bitmap  is being displayed in the menubutton
          then the value is in screen  units  (i.e.  any  of  the
          forms  acceptable  to  Tk_GetPixels); for text it is in
          lines of text.  If this  option  isn't  specified,  the
          menubutton's  desired  height is computed from the size
          of the image or bitmap or text being displayed in it.

     Command-Line Name:-indicatoron
     Database Name:  indicatorOn
     Database Class: IndicatorOn

          The value must be a proper boolean  value.   If  it  is
          true then a small indicator rectangle will be displayed
          on the right side of the  menubutton  and  the  default
          menu  bindings will treat this as an option menubutton.
          If false then no indicator will be displayed.

     Command-Line Name:-menu
     Database Name:  menu
     Database Class: MenuName

          Specifies the path name of  the  menu  associated  with
          this menubutton.  The menu must be a child of the menu-
          button.

     Command-Line Name:-state
     Database Name:  state
     Database Class: State

          Specifies one of three states for the menubutton:  nor-
          mal, active, or disabled.  In normal state the menubut-
          ton is displayed using the  foreground  and  background
          options.   The  active state is typically used when the
          pointer is over the menubutton.  In  active  state  the
          menubutton  is displayed using the activeForeground and
          activeBackground options.  Disabled  state  means  that
          the  menubutton  should  be  insensitive:   the default
          bindings will refuse to activate the  widget  and  will
          ignore  mouse  button presses.  In this state the disa-
          bledForeground and background options determine how the
          button is displayed.

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

          Specifies a desired width for the  menubutton.   If  an
          image  or  bitmap  is being displayed in the menubutton
          then the value is in screen  units  (i.e.  any  of  the
          forms  acceptable  to  Tk_GetPixels); for text it is in
          characters.   If  this  option  isn't  specified,   the
          menubutton's desired width is computed from the size of
          the image or bitmap or text being displayed in it.

INTRODUCTION

     The menubutton command creates a new window  (given  by  the
     pathName  argument)  and  makes it into a menubutton widget.
     Additional options, described above, may be specified on the
     command  line or in the option database to configure aspects
     of the menubutton such as its colors, font, text,  and  ini-
     tial  relief.   The  menubutton 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 menubutton is a widget that  displays  a  textual  string,
     bitmap,  or  image and is associated with a menu widget.  If
     text is displayed, it must all be in a single font,  but  it
     can occupy multiple lines on the screen (if it contains new-
     lines or  if  wrapping  occurs  because  of  the  wrapLength
     option)  and  one of the characters may optionally be under-
     lined using the underline option.  In normal usage, pressing
     mouse  button  1  over  the menubutton causes the associated
     menu to be posted just underneath the  menubutton.   If  the
     mouse is moved over the menu before releasing the mouse but-
     ton, the button release causes the underlying menu entry  to
     be  invoked.   When  the  button  is  released,  the menu is
     unposted.

     Menubuttons are typically organized into groups called  menu
     bars  that  allow  scanning:  if the mouse button is pressed
     over one menubutton (causing it to post its  menu)  and  the
     mouse  is moved over another menubutton in the same menu bar
     without releasing the mouse button, then  the  menu  of  the
     first  menubutton  is unposted and the menu of the new menu-
     button is posted instead.

     There  are  several  interactions  between  menubuttons  and
     menus;  see the menu manual entry for information on various
     menu configurations,  such  as  pulldown  menus  and  option
     menus.

WIDGET COMMAND

     The menubutton 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 menubutton
     widgets:

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

DEFAULT BINDINGS

     Tk automatically creates class bindings for menubuttons that
     give them the following default behavior:

     [1]  A menubutton activates whenever the mouse  passes  over
          it and deactivates whenever the mouse leaves it.

     [2]  Pressing mouse button 1 over  a  menubutton  posts  the
          menubutton:  its relief changes to raised and its asso-
          ciated menu is posted under  the  menubutton.   If  the
          mouse  is  dragged  down  into the menu with the button
          still down, and if the mouse button  is  then  released
          over  an  entry in the menu, the menubutton is unposted
          and the menu entry is invoked.

     [3]  If button 1 is  pressed  over  a  menubutton  and  then
          released  over  that  menubutton,  the menubutton stays
          posted: you can still move the mouse over the menu  and
          click  button  1 on an entry to invoke it.  Once a menu
          entry has been invoked, the menubutton unposts itself.

     [4]  If button 1 is  pressed  over  a  menubutton  and  then
          dragged  over some other menubutton, the original menu-
          button unposts itself and the new menubutton posts.

     [5]  If button 1 is pressed over a menubutton  and  released
          outside  any menubutton or menu, the menubutton unposts
          without invoking any menu entry.

     [6]  When a menubutton is posted, its associated menu claims
          the input focus to allow keyboard traversal of the menu
          and its  submenus.   See  the  menu  manual  entry  for
          details on these bindings.

     [7]  If the underline option has been specified for a  menu-
          button  then keyboard traversal may be used to post the
          menubutton:  Alt+x, where x is the underlined character
          (or  its  lower-case  or upper-case equivalent), may be
          typed in any window under the menubutton's toplevel  to
          post the menubutton.

     [8]  The F10 key may be typed in  any  window  to  post  the
          first  menubutton  under its toplevel window that isn't
          disabled.

     [9]  If a menubutton has the  input  focus,  the  space  and
          return keys post the menubutton.

     If the menubutton's state is disabled then none of the above
     actions occur:  the menubutton is completely non-responsive.

     The behavior of menubuttons can be changed by  defining  new
     bindings  for  individual widgets or by redefining the class
     bindings.

KEYWORDS

     menubutton, widget
itcl2.2/html/tk4.2/messageBox.n.html100666 1751 0 7551 6423554670 16104 0ustar kunkeewheel tk4.2 User Commands - messageBox

tk4.2 User Commands - messageBox

NAME

     tk_messageBox - pops up a message window and waits for  user
     response.

SYNOPSIS

     tk_messageBox ?option value ...?

DESCRIPTION

     This procedure creates and displays a message window with an
     application-specified message, an icon and a set of buttons.
     Each of the buttons in the message window is identified by a
     unique  symbolic  name  (see  the -type options).  After the
     message window is popped up,  tk_messageBox  waits  for  the
     user  to select one of the buttons. Then it returns the sym-
     bolic name of the selected button.

     The following option-value pairs are supported:

     -default name
          Name gives the symbolic name of the default button  for
          this  message window ('ok', 'cancel', and so on). See -
          type for a list of the symbolic names.  If the  message
          box  has  just one button it will automatically be made
          the default, otherwise if this option is not specified,
          there won't be any default button.

     -icon iconImage
          Specifies an icon to display. IconImage must be one  of
          the  following:  error,  info,  question or warning. If
          this option is not specified,  then  no  icon  will  be
          displayed.

     -message string
          Specifies the message to display in this message box.

     -parent window
          Makes window the logical parent of the message box. The
          message box is displayed on top of its parent window.

     -title titleString
          Specifies a string to display as the title of the  mes-
          sage box. The default value is an empty string.

     -type predefinedType
          Arranges  for  a  predefined  set  of  buttons  to   be
          displayed. The following values are possible for prede-
          finedType:

          abortretryignore  Displays three buttons whose symbolic
                            names are abort, retry and ignore.

          ok                Displays one  button  whose  symbolic
                            name is ok.

          okcancel          Displays two buttons  whose  symbolic
                            names are ok and cancel.

          retrycancel       Displays two buttons  whose  symbolic
                            names are retry and cancel.

          yesno             Displays two buttons  whose  symbolic
                            names are yes and no.

          yesnocancel       Displays three buttons whose symbolic
                            names are yes, no and cancel.

EXAMPLE

          set answer [tk_messageBox -message "Really quit?" -type yesno -icon question]
          case $answer {
              yes exit
              no {tk_messageBox -message "I know you like this application!" -type ok}
          }

KEYWORDS

     message box
itcl2.2/html/tk4.2/option.n.html100666 1751 0 10570 6423554670 15332 0ustar kunkeewheel tk4.2 User Commands - option

tk4.2 User Commands - option

NAME

     option - Add/retrieve  window  options  to/from  the  option
     database

SYNOPSIS

     option add pattern value ?priority?

     option clear

     option get window name class

     option readfile fileName ?priority?

DESCRIPTION

     The option command allows you  to  add  entries  to  the  Tk
     option  database  or  to retrieve options from the database.
     The add form of the command adds a new option to  the  data-
     base.  Pattern contains the option being specified, and con-
     sists of names and/or  classes  separated  by  asterisks  or
     dots,  in  the usual X format.  Value contains a text string
     to associate with pattern;  this is the value that  will  be
     returned  in  calls to Tk_GetOption or by invocations of the
     option get command.  If priority is specified, it  indicates
     the  priority  level  for  this  option (see below for legal
     values);  it defaults to interactive.  This  command  always
     returns an empty string.

     The  option  clear  command  clears  the  option   database.
     Default  options  (from the RESOURCE_MANAGER property or the
     .Xdefaults file) will be  reloaded  automatically  the  next
     time  an option is added to the database or removed from it.
     This command always returns an empty string.

     The option get command  returns  the  value  of  the  option
     specified  for  window  under  name  and  class.  If several
     entries in the  option  database  match  window,  name,  and
     class,  then  the command returns whichever was created with
     highest priority  level.   If  there  are  several  matching
     entries  at  the same priority level, then it returns which-
     ever entry was most recently entered into the  option  data-
     base.   If  there  are  no  matching entries, then the empty
     string is returned.

     The readfile form  of  the  command  reads  fileName,  which
     should  have  the standard format for an X resource database
     such as .Xdefaults, and adds all the  options  specified  in
     that file to the option database.  If priority is specified,
     it indicates the  priority  level  at  which  to  enter  the
     options;  priority defaults to interactive.

     The priority arguments to the option  command  are  normally
     specified symbolically using one of the following values:

     widgetDefault
          Level 20.  Used  for  default  values  hard-coded  into
          widgets.

     startupFile
          Level 40.  Used for options specified  in  application-
          specific startup files.

     userDefault
          Level 60.  Used for options specified in  user-specific
          defaults  files, such as .Xdefaults, resource databases
          loaded into the  X  server,  or  user-specific  startup
          files.

     interactive
          Level 80.  Used  for  options  specified  interactively
          after  the  application  starts  running.   If priority
          isn't specified, it defaults to this level.

     Any of the above keywords may be abbreviated.  In  addition,
     priorities  may  be  specified  numerically  using  integers
     between 0 and 100, inclusive.  The numeric form is  probably
     a  bad  idea  except  for new priority levels other than the
     ones given above.

KEYWORDS

     database, option, priority, retrieve
itcl2.2/html/tk4.2/optionMenu.n.html100666 1751 0 3045 6423554670 16136 0ustar kunkeewheel tk4.2 User Commands - optionMenu

tk4.2 User Commands - optionMenu

NAME

     tk_optionMenu - Create an option menubutton and its menu

SYNOPSIS

     tk_optionMenu w varName value ?value value ...?

DESCRIPTION

     This procedure creates an option menubutton whose name is w,
     plus  an  associated  menu.  Together they allow the user to
     select one of the values given by the value arguments.   The
     current  value  will  be stored in the global variable whose
     name is given by varName and it will also  be  displayed  as
     the  label  in the option menubutton.  The user can click on
     the menubutton to display  a  menu  containing  all  of  the
     values  and thereby select a new value.  Once a new value is
     selected, it will be stored in the variable  and  appear  in
     the  option  menubutton.   The  current  value  can  also be
     changed by setting the variable.

     The return value from tk_optionMenu is the name of the  menu
     associated  with w, so that the caller can change its confi-
     guration options or manipulate it in other ways.

KEYWORDS

     option menu
itcl2.2/html/tk4.2/options.n.html100666 1751 0 64221 6423554670 15517 0ustar kunkeewheel tk4.2 User Commands - options

tk4.2 User Commands - options

NAME

     options - Standard options supported by widgets

DESCRIPTION

     This manual entry describes the common configuration options
     supported  by  widgets in the Tk toolkit.  Every widget does
     not necessarily support every option (see the manual entries
     for  individual  widgets  for a list of the standard options
     supported by that widget), but if a widget does  support  an
     option  with  one of the names listed below, then the option
     has exactly the effect described below.

     In the descriptions below, ``Command-Line Name''  refers  to
     the  switch used in class commands and configure widget com-
     mands to set  this  value.   For  example,  if  an  option's
     command-line switch is -foreground and there exists a widget
     .a.b.c, then the command
          .a.b.c  configure  -foreground black
     may be used to specify the value black for the option in the
     the  widget  .a.b.c.   Command-line switches may be abbrevi-
     ated, as long as the abbreviation is  unambiguous.   ``Data-
     base  Name'' refers to the option's name in the option data-
     base (e.g.  in .Xdefaults files).  ``Database Class'' refers
     to the option's class value in the option database.

     Command-Line Name:-activebackground
     Database Name:  activeBackground
     Database Class: Foreground

          Specifies background color to use when  drawing  active
          elements.  An element (a widget or portion of a widget)
          is active if the mouse cursor is  positioned  over  the
          element  and  pressing  a  mouse button will cause some
          action to occur.  If strict Motif compliance  has  been
          requested  by setting the tk_strictMotif variable, this
          option will normally be ignored;  the normal background
          color will be used instead.

     Command-Line Name:-activeborderwidth
     Database Name:  activeBorderWidth
     Database Class: BorderWidth

          Specifies a non-negative value indicating the width  of
          the 3-D border drawn around active elements.  See above
          for definition of active elements.  The value may  have
          any  of  the  forms  acceptable  to Tk_GetPixels.  This
          option is typically only available in widgets  display-
          ing more than one element at a time (e.g. menus but not
          buttons).

     Command-Line Name:-activeforeground
     Database Name:  activeForeground
     Database Class: Background

          Specifies foreground color to use when  drawing  active
          elements.  See above for definition of active elements.

     Command-Line Name:-anchor
     Database Name:  anchor
     Database Class: Anchor

          Specifies how the information in a widget (e.g. text or
          a  bitmap)  is  to be displayed in the widget.  Must be
          one of the values n, ne,  e,  se,  s,  sw,  w,  nw,  or
          center.   For example, nw means display the information
          such that its top-left corner is at the top-left corner
          of the widget.

     Command-Line Name:-background or -bg
     Database Name:  background
     Database Class: Background

          Specifies the  normal  background  color  to  use  when
          displaying the widget.

     Command-Line Name:-bitmap
     Database Name:  bitmap
     Database Class: Bitmap

          Specifies a bitmap to display in the widget, in any  of
          the forms acceptable to Tk_GetBitmap.  The exact way in
          which the bitmap is displayed may be affected by  other
          options  such as anchor or justify.  Typically, if this
          option is specified then  it  overrides  other  options
          that  specify a textual value to display in the widget;
          the bitmap option may be reset to an  empty  string  to
          re-enable a text display.  In widgets that support both
          bitmap and image options, image will  usually  override
          bitmap.

     Command-Line Name:-borderwidth or -bd
     Database Name:  borderWidth
     Database Class: BorderWidth

          Specifies a non-negative value indicating the width  of
          the 3-D border to draw around the outside of the widget
          (if such a border is being drawn;   the  relief  option
          typically determines this).  The value may also be used
          when drawing 3-D effects in the interior of the widget.
          The  value  may  have  any  of  the forms acceptable to
          Tk_GetPixels.

     Command-Line Name:-cursor
     Database Name:  cursor
     Database Class: Cursor

          Specifies the mouse cursor to be used for  the  widget.
          The  value  may  have  any  of  the forms acceptable to
          Tk_GetCursor.

     Command-Line Name:-disabledforeground
     Database Name:  disabledForeground
     Database Class: DisabledForeground

          Specifies foreground color to use when drawing  a  dis-
          abled  element.  If the option is specified as an empty
          string (which  is  typically  the  case  on  monochrome
          displays),  disabled elements are drawn with the normal
          foreground color but they are dimmed  by  drawing  them
          with a stippled fill pattern.

     Command-Line Name:-exportselection
     Database Name:  exportSelection
     Database Class: ExportSelection

          Specifies whether or not  a  selection  in  the  widget
          should also be the X selection.  The value may have any
          of the forms accepted by Tcl_GetBoolean, such as  true,
          false, 0, 1, yes, or no.  If the selection is exported,
          then selecting in the widget deselects  the  current  X
          selection,  selecting  outside the widget deselects any
          widget selection, and the widget will respond to selec-
          tion  retrieval  requests when it has a selection.  The
          default is usually for widgets to export selections.

     Command-Line Name:-font
     Database Name:  font
     Database Class: Font

          Specifies the font to use when drawing text inside  the
          widget.

     Command-Line Name:-foreground or -fg
     Database Name:  foreground
     Database Class: Foreground

          Specifies the  normal  foreground  color  to  use  when
          displaying the widget.

     Command-Line Name:-geometry
     Database Name:  geometry
     Database Class: Geometry
          Specifies the desired geometry for the widget's window,
          in  the  form  widthxheight, where width is the desired
          width of the window and height is the  desired  height.
          The units for width and height depend on the particular
          widget.  For widgets displaying text the units are usu-
          ally  the  size  of  the  characters  in the font being
          displayed;  for other widgets  the  units  are  usually
          pixels.

     Command-Line Name:-highlightbackground
     Database Name:  highlightBackground
     Database Class: HighlightBackground

          Specifies  the  color  to  display  in  the   traversal
          highlight  region  when  the  widget  does not have the
          input focus.

     Command-Line Name:-highlightcolor
     Database Name:  highlightColor
     Database Class: HighlightColor

          Specifies the color to use for the traversal  highlight
          rectangle  that  is drawn around the widget when it has
          the input focus.

     Command-Line Name:-highlightthickness
     Database Name:  highlightThickness
     Database Class: HighlightThickness

          Specifies a non-negative value indicating the width  of
          the  highlight  rectangle to draw around the outside of
          the widget when it has the input focus.  The value  may
          have  any  of the forms acceptable to Tk_GetPixels.  If
          the value is zero, no focus highlight is  drawn  around
          the widget.

     Command-Line Name:-image
     Database Name:  image
     Database Class: Image

          Specifies an image to display in the widget, which must
          have been created with the image create command.  Typi-
          cally, if the image option is specified then  it  over-
          rides  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.

     Command-Line Name:-insertbackground
     Database Name:  insertBackground
     Database Class: Foreground

          Specifies the color to use as background  in  the  area
          covered  by the insertion cursor.  This color will nor-
          mally override either the  normal  background  for  the
          widget  (or  the  selection background if the insertion
          cursor happens to fall in the selection).

     Command-Line Name:-insertborderwidth
     Database Name:  insertBorderWidth
     Database Class: BorderWidth

          Specifies a non-negative value indicating the width  of
          the  3-D  border  to  draw around the insertion cursor.
          The value may have  any  of  the  forms  acceptable  to
          Tk_GetPixels.

     Command-Line Name:-insertofftime
     Database Name:  insertOffTime
     Database Class: OffTime

          Specifies a non-negative integer value  indicating  the
          number  of  milliseconds  the  insertion  cursor should
          remain ``off'' in each blink cycle.  If this option  is
          zero  then  the cursor doesn't blink:  it is on all the
          time.

     Command-Line Name:-insertontime
     Database Name:  insertOnTime
     Database Class: OnTime

          Specifies a non-negative integer value  indicating  the
          number  of  milliseconds  the  insertion  cursor should
          remain ``on'' in each blink cycle.

     Command-Line Name:-insertwidth
     Database Name:  insertWidth
     Database Class: InsertWidth

          Specifies a  value indicating the total  width  of  the
          insertion  cursor.  The value may have any of the forms
          acceptable to  Tk_GetPixels.   If  a  border  has  been
          specified  for  the insertion cursor (using the insert-
          BorderWidth option), the border will  be  drawn  inside
          the width specified by the insertWidth option.

     Command-Line Name:-jump
     Database Name:  jump
     Database Class: Jump

          For widgets with a slider that can be dragged to adjust
          a  value,  such  as  scrollbars, this option determines
          when notifications are made about changes in the value.
          The  option's  value  must  be  a  boolean  of the form
          accepted by Tcl_GetBoolean.  If  the  value  is  false,
          updates are made continuously as the slider is dragged.
          If the value is true, updates  are  delayed  until  the
          mouse  button  is  released  to  end the drag;  at that
          point  a  single  notification  is  made   (the   value
          ``jumps'' rather than changing smoothly).

     Command-Line Name:-justify
     Database Name:  justify
     Database Class: Justify

          When there are multiple lines of text  displayed  in  a
          widget,  this  option  determines how the lines line up
          with each other.  Must  be  one  of  left,  center,  or
          right.   Left means that the lines' left edges all line
          up, center means that the lines' centers  are  aligned,
          and right means that the lines' right edges line up.

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

          For widgets that can lay themselves out with  either  a
          horizontal or vertical orientation, such as scrollbars,
          this option specifies which orientation should be used.
          Must  be  either horizontal or vertical or an abbrevia-
          tion of one of these.

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

          Specifies a  non-negative  value  indicating  how  much
          extra  space  to  request  for  the  widget  in  the X-
          direction.  The value may have any of the forms accept-
          able  to Tk_GetPixels.  When computing how large a win-
          dow it needs, the widget will add this  amount  to  the
          width  it  would  normally  need  (as determined by the
          width of the things displayed in the widget);   if  the
          geometry  manager  can satisfy this request, the widget
          will end up with  extra  internal  space  to  the  left
          and/or  right of what it displays inside.  Most widgets
          only use this option for padding  text:   if  they  are
          displaying  a bitmap or image, then they usually ignore
          padding options.

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

          Specifies a  non-negative  value  indicating  how  much
          extra  space  to  request  for  the  widget  in  the Y-
          direction.  The value may have any of the forms accept-
          able  to Tk_GetPixels.  When computing how large a win-
          dow it needs, the widget will add this  amount  to  the
          height  it  would  normally  need (as determined by the
          height of the things displayed in the widget);  if  the
          geometry  manager  can satisfy this request, the widget
          will end up with  extra  internal  space  above  and/or
          below  what  it displays inside.  Most widgets only use
          this option for padding text:  if they are displaying a
          bitmap  or  image,  then  they  usually  ignore padding
          options.

     Command-Line Name:-relief
     Database Name:  relief
     Database Class: Relief

          Specifies  the  3-D  effect  desired  for  the  widget.
          Acceptable  values are raised, sunken, flat, ridge, and
          groove.  The value indicates how the  interior  of  the
          widget  should  appear  relative  to its exterior;  for
          example, raised means the interior of the widget should
          appear  to  protrude  from  the screen, relative to the
          exterior of the widget.

     Command-Line Name:-repeatdelay
     Database Name:  repeatDelay
     Database Class: RepeatDelay

          Specifies the number of milliseconds a  button  or  key
          must  be  held  down  before  it begins to auto-repeat.
          Used, for  example,  on  the  up-  and  down-arrows  in
          scrollbars.

     Command-Line Name:-repeatinterval
     Database Name:  repeatInterval
     Database Class: RepeatInterval

          Used in conjunction with repeatDelay:  once auto-repeat
          begins,  this  option  determines  the  number  of mil-
          liseconds between auto-repeats.

     Command-Line Name:-selectbackground
     Database Name:  selectBackground
     Database Class: Foreground

          Specifies the background color to use  when  displaying
          selected items.

     Command-Line Name:-selectborderwidth
     Database Name:  selectBorderWidth
     Database Class: BorderWidth

          Specifies a non-negative value indicating the width  of
          the  3-D  border  to  draw  around selected items.  The
          value  may  have  any  of  the  forms   acceptable   to
          Tk_GetPixels.

     Command-Line Name:-selectforeground
     Database Name:  selectForeground
     Database Class: Background

          Specifies the foreground color to use  when  displaying
          selected items.

     Command-Line Name:-setgrid
     Database Name:  setGrid
     Database Class: SetGrid

          Specifies a boolean value that determines whether  this
          widget  controls  the  resizing  grid for its top-level
          window.  This option is typically used in text widgets,
          where  the information in the widget has a natural size
          (the size of a character) and it makes  sense  for  the
          window's  dimensions  to  be  integral numbers of these
          units.  These natural window sizes form a grid.  If the
          setGrid option is set to true then the widget will com-
          municate with the window manager so that when the  user
          interactively  resizes  the  top-level window that con-
          tains the widget, the dimensions of the window will  be
          displayed to the user in grid units and the window size
          will be constrained to integral numbers of grid  units.
          See  the  section GRIDDED GEOMETRY MANAGEMENT in the wm
          manual entry for more details.

     Command-Line Name:-takefocus
     Database Name:  takeFocus
     Database Class: TakeFocus

          Determines whether the window accepts the focus  during
          keyboard  traversal  (e.g., Tab and Shift-Tab).  Before
          setting the focus to a window,  the  traversal  scripts
          consult  the value of the takeFocus option.  A value of
          0 means that the window should be skipped entirely dur-
          ing  keyboard traversal. 1 means that the window should
          receive the input focus as long as it is  viewable  (it
          and  all  of its ancestors are mapped).  An empty value
          for the option means that the  traversal  scripts  make
          the  decision about whether or not to focus on the win-
          dow:  the current algorithm is to skip the window if it
          is disabled, if it has no key bindings, or if it is not
          viewable.  If the value has any other  form,  then  the
          traversal  scripts  take  the value, append the name of
          the window to it (with a separator space), and evaluate
          the  resulting string as a Tcl script.  The script must
          return 0, 1, or an empty string:  a 0 or 1 value speci-
          fies  whether  the window will receive the input focus,
          and an empty string results  in  the  default  decision
          described  above.   Note:  this  interpretation  of the
          option is defined entirely  by  the  Tcl  scripts  that
          implement traversal:  the widget implementations ignore
          the option entirely, so you can change its  meaning  if
          you redefine the keyboard traversal scripts.

     Command-Line Name:-text
     Database Name:  text
     Database Class: Text

          Specifies a string to be displayed inside  the  widget.
          The way in which the string is displayed depends on the
          particular  widget  and  may  be  determined  by  other
          options, such as anchor or justify.

     Command-Line Name:-textvariable
     Database Name:  textVariable
     Database Class: Variable

          Specifies the name of a variable.   The  value  of  the
          variable  is  a  text string to be displayed inside the
          widget;  if the variable value changes then the  widget
          will  automatically  update  itself  to reflect the new
          value.  The way in which the string is displayed in the
          widget  depends  on  the  particular  widget and may be
          determined by other options, such as anchor or justify.

     Command-Line Name:-troughcolor
     Database Name:  troughColor
     Database Class: Background

          Specifies the color to use for the  rectangular  trough
          areas in widgets such as scrollbars and scales.

     Command-Line Name:-underline
     Database Name:  underline
     Database Class: Underline

          Specifies the integer index of a character to underline
          in  the  widget.   This  option  is used by the default
          bindings to implement keyboard traversal for menu  but-
          tons  and  menu  entries.   0  corresponds to the first
          character of the text displayed in the widget, 1 to the
          next character, and so on.

     Command-Line Name:-wraplength
     Database Name:  wrapLength
     Database Class: WrapLength

          For widgets that can perform word-wrapping, this option
          specifies  the  maximum  line length.  Lines that would
          exceed this length are wrapped onto the next  line,  so
          that  no line is longer than the specified length.  The
          value may be specified in any of the standard forms for
          screen  distances.  If this value is less than or equal
          to 0 then no wrapping is done:  lines will  break  only
          at newline characters in the text.

     Command-Line Name:-xscrollcommand
     Database Name:  xScrollCommand
     Database Class: ScrollCommand

          Specifies the prefix for a command used to  communicate
          with  horizontal  scrollbars.   When  the  view  in the
          widget's window  changes  (or  whenever  anything  else
          occurs  that  could  change the display in a scrollbar,
          such as a change in the total size of the widget's con-
          tents),  the widget will generate a Tcl command by con-
          catenating the scroll command and two numbers.  Each of
          the  numbers is a fraction between 0 and 1, which indi-
          cates a position in  the  document.   0  indicates  the
          beginning  of  the  document, 1 indicates the end, .333
          indicates a position one  third  the  way  through  the
          document,  and so on.  The first fraction indicates the
          first information in the document that  is  visible  in
          the  window,  and  the  second  fraction  indicates the
          information just after the last portion that  is  visi-
          ble.  The command is then passed to the Tcl interpreter
          for execution.   Typically  the  xScrollCommand  option
          consists  of  the  path name of a scrollbar widget fol-
          lowed by ``set'', e.g. ``.x.scrollbar set'':  this will
          cause  the scrollbar to be updated whenever the view in
          the window changes.  If this option is  not  specified,
          then no command will be executed.

     Command-Line Name:-yscrollcommand
     Database Name:  yScrollCommand
     Database Class: ScrollCommand

          Specifies the prefix for a command used to  communicate
          with  vertical  scrollbars.   This option is treated in
          the same way as the xScrollCommand option, except  that
          it  is  used for vertical scrollbars and is provided by
          widgets  that  support  vertical  scrolling.   See  the
          description  of  xScrollCommand for details on how this
          option is used.

KEYWORDS

     class, name, standard option, switch
itcl2.2/html/tk4.2/pack-old.n.html100666 1751 0 24266 6423554670 15523 0ustar kunkeewheel tk4.2 User Commands - pack-old

tk4.2 User Commands - pack-old

NAME

     pack - Obsolete syntax for packer geometry manager

SYNOPSIS

     pack after sibling window options ?window options ...?

     pack append parent window options ?window options ...?

     pack before sibling window options ?window options ...?

     pack unpack window

DESCRIPTION

     Note: this manual entry describes the syntax  for  the  pack
     command  as it existed before Tk version 3.3.  Although this
     syntax continues to be supported for backward compatibility,
     it  is  obsolete  and  should  not be used anymore.  At some
     point in the future it may cease to be supported.

     The packer is a geometry manager that arranges the  children
     of a parent by packing them in order around the edges of the
     parent.  The first child is placed against one side  of  the
     window,  occupying  the entire span of the window along that
     side.  This reduces the space remaining for  other  children
     as  if  the  side had been moved in by the size of the first
     child.  Then the next child is placed against  one  side  of
     the remaining cavity, and so on until all children have been
     placed or there is no space left in the cavity.

     The before, after, and append forms of the pack command  are
     used  to  insert one or more children into the packing order
     for their parent.  The  before  form  inserts  the  children
     before  window  sibling in the order;  all of the other win-
     dows must be siblings of sibling.  The  after  form  inserts
     the  windows  after sibling, and the append form appends one
     or more windows to the end of the packing order for  parent.
     If a window named in any of these commands is already packed
     in its parent, it is removed from its  current  position  in
     the  packing order and repositioned as indicated by the com-
     mand.  All of these  commands  return  an  empty  string  as
     result.

     The unpack form of the pack command removes window from  the
     packing order of its parent and unmaps it.  After the execu-
     tion of this  command  the  packer  will  no  longer  manage
     window's geometry.


     The placement of each child is actually a four-step process;
     the  options  argument  following  each window consists of a
     list of one or more fields that govern the placement of that
     window.   In the discussion below, the term cavity refers to
     the space left in a parent when a particular child is placed
     (i.e.  all the space that wasn't claimed by earlier children
     in the packing order).  The term parcel refers to the  space
     allocated  to  a  particular child;  this is not necessarily
     the same as the child window's final geometry.

     The first step in placing a child is to determine which side
     of the cavity it will lie against.  Any one of the following
     options may be used to specify a side:

     top  Position the child's parcel against the top of the cav-
          ity, occupying the full width of the cavity.

     bottom
          Position the child's parcel against the bottom  of  the
          cavity, occupying the full width of the cavity.

     left Position the child's parcel against the  left  side  of
          the cavity, occupying the full height of the cavity.

     right
          Position the child's parcel against the right  side  of
          the cavity, occupying the full height of the cavity.

     At most one of these options should  be  specified  for  any
     given  window.  If no side is specified, then the default is
     top.

     The second step is to decide on a parcel for the child.  For
     top and bottom windows, the desired parcel width is normally
     the cavity width  and  the  desired  parcel  height  is  the
     window's  requested height, as passed to Tk_GeometryRequest.
     For left and right windows, the  desired  parcel  height  is
     normally  the  cavity  height  and  the desired width is the
     window's requested  width.   However,  extra  space  may  be
     requested for the window using any of the following options:

     padx num    Add num pixels to the window's  requested  width
                 before  computing  the  parcel size as described
                 above.

     pady num    Add num pixels to the window's requested  height
                 before  computing  the  parcel size as described
                 above.

     expand      This option requests that  the  window's  parcel
                 absorb any extra space left over in the parent's
                 cavity after  packing  all  the  children.   The
                 amount  of  space left over depends on the sizes
                 requested by the  other  children,  and  may  be
                 zero.   If  several  windows  have all specified
                 expand then the  extra  width  will  be  divided
                 equally  among  all  the  left and right windows
                 that specified expand and the extra height  will
                 be  divided equally among all the top and bottom
                 windows that specified expand.

     If the desired width or height for a parcel is  larger  than
     the corresponding dimension of the cavity, then the cavity's
     dimension is used instead.

     The third step in placing the window is  to  decide  on  the
     window's width and height.  The default is for the window to
     receive either its requested width and height or  the  those
     of  the  parcel,  whichever  is  smaller.   If the parcel is
     larger than the window's requested size, then the  following
     options  may  be  used  to expand the window to partially or
     completely fill the parcel:

     fill Set the window's size to equal the parcel size.

     fillx
          Increase the  window's  width  to  equal  the  parcel's
          width, but retain the window's requested height.

     filly
          Increase the window's  height  to  equal  the  parcel's
          height, but retain the window's requested width.

     The last step is to decide the window's location within  its
     parcel.  If the window's size equals the parcel's size, then
     the window simply fills the entire parcel.  If the parcel is
     larger  than  the  window, then one of the following options
     may be used to specify where the window should be positioned
     within its parcel:

     frame center   Center the window in its parcel.  This is the
                    default if no framing option is specified.

     frame n        Position the window with its  top  edge  cen-
                    tered on the top edge of the parcel.

     frame ne       Position  the  window  with  its  upper-right
                    corner  at the upper-right corner of the par-
                    cel.

     frame e        Position the window with its right edge  cen-
                    tered on the right edge of the parcel.

     frame se       Position  the  window  with  its  lower-right
                    corner  at the lower-right corner of the par-
                    cel.

     frame s        Position the window with its bottom edge cen-
                    tered on the bottom edge of the parcel.

     frame sw       Position  the  window  with  its   lower-left
                    corner  at  the lower-left corner of the par-
                    cel.

     frame w        Position the window with its left  edge  cen-
                    tered on the left edge of the parcel.

     frame nw       Position  the  window  with  its   upper-left
                    corner  at  the upper-left corner of the par-
                    cel.

     The packer manages the  mapped/unmapped  state  of  all  the
     packed  children windows.  It automatically maps the windows
     when it packs them, and it  unmaps  any  windows  for  which
     there was no space left in the cavity.

     The packer makes geometry requests on behalf of  the  parent
     windows  it  manages.   For each parent window it requests a
     size large enough to accommodate all the  options  specified
     by  all  the  packed children, such that zero space would be
     leftover for expand options.

KEYWORDS

     geometry manager, location, packer, parcel, size
itcl2.2/html/tk4.2/pack.n.html100666 1751 0 33434 6423554671 14745 0ustar kunkeewheel tk4.2 User Commands - pack

tk4.2 User Commands - pack

NAME

     pack - Geometry manager that packs around edges of cavity

SYNOPSIS

     pack option arg ?arg ...?

DESCRIPTION

     The pack command is used to communicate with the  packer,  a
     geometry  manager  that arranges the children of a parent by
     packing them in order around the edges of the  parent.   The
     pack command can have any of several forms, depending on the
     option argument:

     pack slave ?slave ...? ?options?
          If the first argument to pack is  a  window  name  (any
          value  starting  with  ``.''), then the command is pro-
          cessed in the same way as pack configure.

     pack configure slave ?slave ...? ?options?
          The arguments consist of the names of one or more slave
          windows followed by pairs of arguments that specify how
          to manage the slaves.   See  ``THE  PACKER  ALGORITHM''
          below  for  details  on how the options are used by the
          packer.  The following options are supported:

          -after other
               Other must the name of another  window.   Use  its
               master  as  the  master for the slaves, and insert
               the slaves just after other in the packing order.

          -anchor anchor
               Anchor must be a valid anchor position such  as  n
               or  sw;  it specifies where to position each slave
               in its parcel.  Defaults to center.

          -before other
               Other must the name of another  window.   Use  its
               master  as  the  master for the slaves, and insert
               the slaves just before other in the packing order.

          -expand boolean
               Specifies whether the slaves should be expanded to
               consume  extra space in their master.  Boolean may
               have any proper boolean value, such as  1  or  no.
               Defaults to 0.

          -fill style
               If a slave's parcel is larger than  its  requested
               dimensions, this option may be used to stretch the
               slave.  Style  must  have  one  of  the  following
               values:

               none Give the slave its requested dimensions  plus
                    any internal padding requested with -ipadx or
                    -ipady.  This is the default.

               x    Stretch the slave horizontally  to  fill  the
                    entire  width  of  its  parcel  (except leave
                    external padding as specified by -padx).

               y    Stretch the  slave  vertically  to  fill  the
                    entire  height  of  its  parcel (except leave
                    external padding as specified by -pady).

               both Stretch the slave both horizontally and vert-
                    ically.

          -in other
               Insert the slave(s) at  the  end  of  the  packing
               order for the master window given by other.

          -ipadx amount
               Amount specifies how much horizontal internal pad-
               ding  to  leave  on  each  side  of  the slave(s).
               Amount must be a valid screen distance, such as  2
               or .5c.  It defaults to 0.

          -ipady amount
               Amount specifies how much vertical  internal  pad-
               ding  to  leave  on  each  side  of  the slave(s).
               Amount  defaults to 0.

          -padx amount
               Amount specifies how much horizontal external pad-
               ding  to  leave  on  each  side  of  the slave(s).
               Amount defaults to 0.

          -pady amount
               Amount specifies how much vertical  external  pad-
               ding  to  leave  on  each  side  of  the slave(s).
               Amount defaults to 0.

          -side side
               Specifies which side of the  master  the  slave(s)
               will be packed against.  Must be left, right, top,
               or bottom.  Defaults to top.

          If no -in, -after or -before option is  specified  then
          each  of  the slaves will be inserted at the end of the
          packing list  for  its  parent  unless  it  is  already
          managed  by  the  packer (in which case it will be left
          where it is).  If one of  these  options  is  specified
          then  all  the slaves will be inserted at the specified
          point.  If any of the slaves are already managed by the
          geometry  manager then any unspecified options for them
          retain their  previous  values  rather  than  receiving
          default values.

     pack forget slave ?slave ...?
          Removes each of the slaves from the packing  order  for
          its  master  and unmaps their windows.  The slaves will
          no longer be managed by the packer.

     pack info slave
          Returns a list whose elements are  the  current  confi-
          guration  state of the slave given by slave in the same
          option-value form that might be specified to pack  con-
          figure.   The  first two elements of the list are ``-in
          master'' where master is the slave's master.

     pack propagate master ?boolean?
          If boolean has a true boolean value such  as  1  or  on
          then propagation is enabled for master, which must be a
          window name (see ``GEOMETRY PROPAGATION''  below).   If
          boolean  has  a false boolean value then propagation is
          disabled for master.  In either of these cases an empty
          string  is  returned.   If  boolean is omitted then the
          command returns 0 or 1 to indicate whether  propagation
          is   currently  enabled  for  master.   Propagation  is
          enabled by default.

     pack slaves master
          Returns a list of all of  the  slaves  in  the  packing
          order  for master.  The order of the slaves in the list
          is the same as their order in the  packing  order.   If
          master has no slaves then an empty string is returned.

THE PACKER ALGORITHM

     For each master the packer  maintains  an  ordered  list  of
     slaves  called  the  packing  list.   The -in, -after, and -
     before configuration options are used to specify the  master
     for each slave and the slave's position in the packing list.
     If none of these options is given for a slave then the slave
     is added to the end of the packing list for its parent.

     The packer arranges the slaves for a master by scanning  the
     packing list in order.  At the time it processes each slave,
     a rectangular area within the master is  still  unallocated.
     This  area  is called the cavity;  for the first slave it is
     the entire area of the master.

     For each slave the packer carries out the following steps:

     [1]  The packer allocates a rectangular parcel for the slave
          along the side of the cavity given by the slave's -side
          option.  If the side is top or bottom then the width of
          the parcel is the width of the cavity and its height is
          the requested height of the slave plus the -ipady and -
          pady options.  For the left or right side the height of
          the parcel is the height of the cavity and the width is
          the  requested width of the slave plus the -ipadx and -
          padx options.   The  parcel  may  be  enlarged  further
          because of the -expand option (see ``EXPANSION'' below)

     [2]  The packer chooses the dimensions of  the  slave.   The
          width will normally be the slave's requested width plus
          twice its -ipadx option and the height will normally be
          the  slave's  requested  height  plus  twice its -ipady
          option.  However, if the -fill option is x or both then
          the width of the slave is expanded to fill the width of
          the parcel, minus twice the -padx option.  If the -fill
          option  is  y  or  both then the height of the slave is
          expanded to fill the width of the parcel,  minus  twice
          the -pady option.

     [3]  The packer positions the slave over its parcel.  If the
          slave  is  smaller  than  the  parcel  then the -anchor
          option determines where in the parcel the slave will be
          placed.   If -padx or -pady is non-zero, then the given
          amount of external padding will always be left  between
          the slave and the edges of the parcel.

     Once a given slave has been packed, the area of  its  parcel
     is subtracted from the cavity, leaving a smaller rectangular
     cavity for the next slave.  If a slave doesn't  use  all  of
     its  parcel, the unused space in the parcel will not be used
     by subsequent slaves.  If the cavity should become too small
     to  meet  the  needs of a slave then the slave will be given
     whatever space is left in the cavity.  If the cavity shrinks
     to  zero size, then all remaining slaves on the packing list
     will be unmapped from the screen  until  the  master  window
     becomes large enough to hold them again.

EXPANSION

     If a master window is so large  that  there  will  be  extra
     space  left  over  after all of its slaves have been packed,
     then the extra space is distributed uniformly among  all  of
     the  slaves for which the -expand option is set.  Extra hor-
     izontal space is distributed  among  the  expandable  slaves
     whose  - side  is left or right, and extra vertical space is
     distributed among the expandable slaves whose -side  is  top
     or bottom.

GEOMETRY PROPAGATION

     The packer normally computes how large a master must  be  to
     just  exactly  meet the needs of its slaves, and it sets the
     requested width and height of the  master  to  these  dimen-
     sions.   This  causes  geometry  information to propagate up
     through a window hierarchy to a top-level window so that the
     entire  sub-tree  sizes  itself to fit the needs of the leaf
     windows.  However, the pack propagate command may be used to
     turn  off  propagation for one or more masters.  If propaga-
     tion is disabled then the packer will not set the  requested
     width  and height of the packer.  This may be useful if, for
     example, you wish for a master window to have a  fixed  size
     that you specify.

RESTRICTIONS ON MASTER WINDOWS

     The master for each slave must either be the slave's  parent
     (the  default)  or a descendant of the slave's parent.  This
     restriction is necessary to guarantee that the slave can  be
     placed  over  any part of its master that is visible without
     danger of the slave being clipped by its parent.

PACKING ORDER

     If the master for a slave is not its parent  then  you  must
     make  sure  that  the  slave is higher in the stacking order
     than the master.  Otherwise  the  master  will  obscure  the
     slave  and it will appear as if the slave hasn't been packed
     correctly.  The easiest way to make sure the slave is higher
     than  the  master is to create the master window first:  the
     most recently created window will be highest in the stacking
     order.   Or,  you  can  use  the raise and lower commands to
     change the stacking order of either the master or the slave.

KEYWORDS

     geometry manager,  location,  packer,  parcel,  propagation,
     size
itcl2.2/html/tk4.2/palette.n.html100666 1751 0 7523 6423554671 15445 0ustar kunkeewheel tk4.2 User Commands - palette

tk4.2 User Commands - palette

NAME

     tk_setPalette, tk_bisque - Modify the Tk color palette

SYNOPSIS

     tk_setPalette background

     tk_setPalette name value ?name value ...?

     tk_bisque

DESCRIPTION

     The tk_setPalette procedure changes the color scheme for Tk.
     It does this by modifying the colors of existing widgets and
     by changing the option database so that future widgets  will
     use  the new color scheme.  If tk_setPalette is invoked with
     a single argument, the argument is the name of  a  color  to
     use as the normal background color;  tk_setPalette will com-
     pute a complete color palette from  this  background  color.
     Alternatively, the arguments to tk_setPalette may consist of
     any number of name-value pairs, where the first argument  of
     the  pair is the name of an option in the Tk option database
     and the second argument is the new value  to  use  for  that
     option.   The  following  database  names are currently sup-
     ported:

          activeBackground               foregroundselectColor
          activeForeground               highlightBackgroundselectBackground
          background      highlightColor selectForeground
          disabledForeground             insertBackgroundtroughColor

     tk_setPalette tries to compute reasonable defaults  for  any
     options  that  you  don't  specify.  You can specify options
     other than the above ones and Tk will change  those  options
     on  widgets  as well.  This feature may be useful if you are
     using custom widgets with additional color options.

     Once it has computed the new value to use for  each  of  the
     color  options,  tk_setPalette scans the widget hierarchy to
     modify the  options  of  all  existing  widgets.   For  each
     widget,  it  checks  to  see  if any of the above options is
     defined for the widget.  If so, and if the option's  current
     value  is  the  default,  then the value is changed;  if the
     option has a value other  than  the  default,  tk_setPalette
     will  not  change  it.  The default for an option is the one
     provided by the widget ([lindex [$w configure  $option]  3])
     unless  tk_setPalette has been run previously, in which case
     it is the value specified  in  the  previous  invocation  of
     tk_setPalette.
     After  modifying  all  the  widgets  in   the   application,
     tk_setPalette  adds options to the option database to change
     the defaults for widgets created in  the  future.   The  new
     options are added at priority widgetDefault, so they will be
     overridden by options from the .Xdefaults  file  or  options
     specified on the command-line that creates a widget.

     The procedure tk_bisque is provided for backward compatibil-
     ity:   it  restores  the  application's  colors to the light
     brown (``bisque'') color scheme used in Tk 3.6  and  earlier
     versions.

KEYWORDS

     bisque, color, palette
itcl2.2/html/tk4.2/photo.n.html100666 1751 0 50501 6423554671 15152 0ustar kunkeewheel tk4.2 User Commands - photo

tk4.2 User Commands - photo

NAME

     photo - Full-color images

SYNOPSIS

     image create photo ?name? ?options?

DESCRIPTION

     A photo is an image whose pixels can display any color or be
     transparent.   A  photo  image  is stored internally in full
     color (24 bits per pixel), and is displayed using  dithering
     if  necessary.  Image data for a photo image can be obtained
     from a file or a string, or it can be supplied from  C  code
     through  a  procedural  interface.  At present, only GIF and
     PPM/PGM formats are supported, but an  interface  exists  to
     allow  additional  image file formats to be added easily.  A
     photo image is transparent in regions where  no  image  data
     has been supplied.

CREATING PHOTOS

     Like all images, photos are created using the  image  create
     command.  Photos support the following options:

     -data string
          Specifies the contents of the image as a  string.   The
          format  of  the  string  must be one of those for which
          there is an image file format handler that will  accept
          string  data.   If both the -data and -file options are
          specified, the -file option takes precedence.

     -format format-name
          Specifies the name of the  file  format  for  the  data
          specified with the -data or -file option.

     -file name
          name gives the name of a file that is  to  be  read  to
          supply  data for the photo image.  The file format must
          be one of those for which there is an image file format
          handler that can read data from a file.

     -gamma value
          Specifies that the colors allocated for displaying this
          image  in a window should be corrected for a non-linear
          display with the specified gamma exponent value.   (The
          intensity  produced  by  most  CRT  displays is a power
          function of the input value, to a  good  approximation;
          gamma  is the exponent and is typically around 2).  The
          value specified must be greater than zero.  The default
          value  is  one  (no  correction).   In  general, values
          greater than one  will  make  the  image  lighter,  and
          values less than one will make it darker.

     -height number
          Specifies the height of the  image,  in  pixels.   This
          option is useful primarily in situations where the user
          wishes to build up the contents of the image  piece  by
          piece.   A value of zero (the default) allows the image
          to expand or shrink vertically to fit the  data  stored
          in it.

     -palette palette-spec
          Specifies the resolution of the color cube to be  allo-
          cated for displaying this image, and thus the number of
          colors used from the colormaps of the windows where  it
          is  displayed.  The palette-spec string may be either a
          single decimal number, specifying the number of  shades
          of  gray  to use, or three decimal numbers separated by
          slashes (/), specifying the number of  shades  of  red,
          green and blue to use, respectively.  If the first form
          (a single number) is used, the image will be  displayed
          in monochrome (i.e., grayscale).

     -width number
          Specifies the width of the image,  in  pixels.     This
          option is useful primarily in situations where the user
          wishes to build up the contents of the image  piece  by
          piece.   A value of zero (the default) allows the image
          to expand or shrink horizontally to fit the data stored
          in it.

IMAGE COMMAND

     When a photo image is created, Tk also creates a new command
     whose  name  is  the same as the image.  This command may be
     used to invoke various operations on the image.  It has  the
     following general form:
          imageName option ?arg arg ...?
     Option and the args determine the exact behavior of the com-
     mand.

     Those options that write data to the image generally  expand
     the size of the image, if necessary, to accommodate the data
     written to the image, unless the user has specified non-zero
     values  for the -width and/or -height configuration options,
     in which case the width and/or height, respectively, of  the
     image will not be changed.

     The following commands are possible for photo images:

     imageName blank
          Blank the image; that is, set the entire image to  have
          no  data,  so  it will be displayed as transparent, and
          the background of whatever window it  is  displayed  in
          will show through.

     imageName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the image create photo command.

     imageName configure ?option? ?value option value ...?
          Query or  modify  the  configuration  options  for  the
          image.   If  no  option  is  specified,  returns a list
          describing all of the available options  for  imageName
          (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
          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 image create  photo  com-
          mand.

     imageName copy sourceImage ?option value(s) ...?
          Copies a  region  from  the  image  called  sourceImage
          (which  must  be  a  photo  image)  to the image called
          imageName, possibly with pixel zooming  and/or  subsam-
          pling.   If  no  options  are  specified,  this command
          copies the whole of sourceImage into imageName,  start-
          ing  at  coordinates (0,0) in imageName.  The following
          options may be specified:

          -from x1 y1 x2 y2
               Specifies a rectangular sub-region of  the  source
               image  to  be copied.  (x1,y1) and (x2,y2) specify
               diagonally opposite corners of the rectangle.   If
               x2  and y2 are not specified, the default value is
               the bottom-right corner of the source image.   The
               pixels  copied will include the left and top edges
               of the specified rectangle but not the  bottom  or
               right  edges.   If  the -from option is not given,
               the default is the whole source image.

          -to x1 y1 x2 y2
               Specifies a rectangular sub-region of the destina-
               tion  image  to  be affected.  (x1,y1) and (x2,y2)
               specify diagonally opposite corners of the rectan-
               gle.   If x2 and y2 are not specified, the default
               value is (x1,y1)  plus  the  size  of  the  source
               region  (after  subsampling and zooming, if speci-
               fied).  If x2 and y2  are  specified,  the  source
               region will be replicated if necessary to fill the
               destination region in a tiled fashion.

          -shrink
               Specifies that the size of the  destination  image
               should  be  reduced,  if  necessary,  so  that the
               region being copied into is  at  the  bottom-right
               corner  of the image.  This option will not affect
               the width or height of the image if the  user  has
               specified  a  non-zero  value  for the -width or -
               height configuration option, respectively.

          -zoom x y
               Specifies that the source region should be  magni-
               fied  by a factor of x in the X direction and y in
               the Y direction.  If y is not given,  the  default
               value  is  the  same as x.  With this option, each
               pixel in the source image will be expanded into  a
               block  of  x  x y pixels in the destination image,
               all the same color.  x and y must be greater  than
               0.

          -subsample x y
               Specifies that the source image should be  reduced
               in  size  by  using  only every xth pixel in the X
               direction and yth pixel in the Y direction.  Nega-
               tive  values  will  cause  the image to be flipped
               about the Y or X axes, respectively.  If y is  not
               given, the default value is the same as x.

     imageName get x y
          Returns the color of the pixel at coordinates (x,y)  in
          the  image  as  a  list of three integers between 0 and
          255, representing the red, green  and  blue  components
          respectively.

     imageName put data ?-to x1 y1 x2 y2?
          Sets pixels in imageName to  the  colors  specified  in
          data.   data is used to form a two-dimensional array of
          pixels that are then copied into the  imageName.   data
          is structured as a list of horizontal rows, from top to
          bottom, each of which is a list of colors, listed  from
          left  to  right.   Each  color may be specified by name
          (e.g., blue) or in hexadecimal  form  (e.g.,  #2376af).
          The  - to  option  can  be  used to specify the area of
          imageName to be affected.  If only x1 and y1 are given,
          the  area  affected  has its top-left corner at (x1,y1)
          and is the same size as the array given  in  data.   If
          all four coordinates are given, they specify diagonally
          opposite corners of the  affected  rectangle,  and  the
          array  given in data will be replicated as necessary in
          the X and Y directions to fill the rectangle.

     imageName read filename ?option value(s) ...?
          Reads image data from the file named filename into  the
          image.   This  command first searches the list of image
          file format handlers for a handler that  can  interpret
          the  data  in  filename,  and  then  reads the image in
          filename into imageName (the destination  image).   The
          following options may be specified:

          -format format-name
               Specifies  the  format  of  the  image   data   in
               filename.   Specifically,  only  image file format
               handlers whose names begin with  format-name  will
               be  used  while searching for an image data format
               handler to read the data.

          -from x1 y1 x2 y2
               Specifies a rectangular sub-region  of  the  image
               file  data  to be copied to the destination image.
               If only  x1  and  y1  are  specified,  the  region
               extends from (x1,y1) to the bottom-right corner of
               the image in the image file.  If all four  coordi-
               nates are specified, they specify diagonally oppo-
               site corners or the region.  The default, if  this
               option is not specified, is the whole of the image
               in the image file.

          -shrink
               If this option, the  size  of  imageName  will  be
               reduced,  if  necessary,  so  that the region into
               which the image file  data  are  read  is  at  the
               bottom-right corner of the imageName.  This option
               will not affect the width or height of  the  image
               if the user has specified a non-zero value for the
               -width or -height  configuration  option,  respec-
               tively.

          -to x y
               Specifies the coordinates of the  top-left  corner
               of  the  region  of imageName into which data from
               filename are to be read.  The default is (0,0).

     imageName redither
          The dithering algorithm used in displaying photo images
          propagates  quantization  errors  from one pixel to its
          neighbors.  If the image data for imageName is supplied
          in  pieces,  the  dithered  image  may  not  be exactly
          correct.  Normally the difference  is  not  noticeable,
          but  if  it  is  a problem, this command can be used to
          recalculate the dithered image in each window where the
          image is displayed.

     imageName write filename ?option value(s) ...?
          Writes image  data  from  imageName  to  a  file  named
          filename.  The following options may be specified:

          -format format-name
               Specifies  the  name  of  the  image  file  format
               handler  to be used to write the data to the file.
               Specifically, this  subcommand  searches  for  the
               first  handler  whose  name matches a initial sub-
               string of format-name and which has the capability
               to  write  an  image  file.  If this option is not
               given, this subcommand uses the first handler that
               has the capability to write an image file.

          -from x1 y1 x2 y2
               Specifies a rectangular region of imageName to  be
               written  to the image file.  If only x1 and y1 are
               specified, the region extends from (x1,y1) to  the
               bottom-right  corner  of  imageName.   If all four
               coordinates are  given,  they  specify  diagonally
               opposite  corners  of the rectangular region.  The
               default, if this option is not given, is the whole
               image.

IMAGE FORMATS

     The photo image code is structured  to  allow  handlers  for
     additional image file formats to be added easily.  The photo
     image code maintains a list of these handlers.  Handlers are
     added  to  the  list  by  registering  them  with  a call to
     Tk_CreatePhotoImageFormat.   The  standard  Tk  distribution
     comes  with  handlers for PPM/PGM and GIF formats, which are
     automatically registered on initialization.

     When reading an image file or processing string data  speci-
     fied  with  the  -data configuration option, the photo image
     code invokes each handler in turn until one  is  found  that
     claims  to  be  able to read the data in the file or string.
     Usually this will  find  the  correct  handler,  but  if  it
     doesn't,  the  user  may give a format name with the -format
     option to specify which handler to use.  In fact  the  photo
     image  code  will  try those handlers whose names begin with
     the string specified for the -format option (the  comparison
     is  case-insensitive).  For example, if the user specifies -
     format gif, then a handler  named  GIF87  or  GIF89  may  be
     invoked,  but  a  handler  named JPEG may not (assuming that
     such handlers had been registered).

     When writing image data to a file, the processing of  the  -
     format  option is slightly different: the string value given
     for the -format option must begin with the complete name  of
     the  requested  handler, and may contain additional informa-
     tion following that, which the handler can use, for example,
     to  specify which variant to use of the formats supported by
     the handler.

COLOR ALLOCATION

     When a photo image is displayed in a window, the photo image
     code  allocates colors to use to display the image and dith-
     ers the image, if necessary, to display a reasonable approx-
     imation  to  the  image using the colors that are available.
     The colors are allocated as  a  color  cube,  that  is,  the
     number  of  colors allocated is the product of the number of
     shades of red, green and blue.

     Normally, the number of colors allocated is chosen based  on
     the  depth  of  the  window.  For example, in an 8-bit Pseu-
     doColor window, the photo image code will attempt  to  allo-
     cate  seven  shades  of  red, seven shades of green and four
     shades of blue, for a total of 198 colors.  In a 1-bit  Sta-
     ticGray  (monochrome)  window,  it will allocate two colors,
     black and white.  In a 24-bit DirectColor or TrueColor  win-
     dow,  it  will  allocate  256  shades each of red, green and
     blue.  Fortunately, because of the way that pixel values can
     be  combined in DirectColor and TrueColor windows, this only
     requires 256 colors to be allocated.   If  not  all  of  the
     colors  can  be  allocated, the photo image code reduces the
     number of shades of each primary color and tries again.

     The user can exercise some control over the number of colors
     that  a  photo  image  uses  with the -palette configuration
     option.  If this option is used, it  specifies  the  maximum
     number  of  shades of each primary color to try to allocate.
     It can also be used to force the image to  be  displayed  in
     shades  of gray, even on a color display, by giving a single
     number rather than three numbers separated by slashes.

CREDITS

     The photo image type was designed and  implemented  by  Paul
     Mackerras,  based  on  his  earlier  photo  widget  and some
     suggestions from John Ousterhout.

KEYWORDS

     photo, image, color
itcl2.2/html/tk4.2/place.n.html100666 1751 0 32637 6423554671 15117 0ustar kunkeewheel tk4.2 User Commands - place

tk4.2 User Commands - place

NAME

     place - Geometry manager for fixed or rubber-sheet placement

SYNOPSIS

     place window option value ?option value ...?

     place configure window option value ?option value ...?

     place forget window

     place info window

     place slaves window

DESCRIPTION

     The placer is a geometry manager for Tk.  It provides simple
     fixed placement of windows, where you specify the exact size
     and location of one window, called the slave, within another
     window,   called  the  master.   The  placer  also  provides
     rubber-sheet placement, where you specify the size and loca-
     tion  of the slave in terms of the dimensions of the master,
     so that the slave changes size and location in  response  to
     changes  in  the  size  of  the  master.  Lastly, the placer
     allows you to mix these styles of  placement  so  that,  for
     example,  the slave has a fixed width and height but is cen-
     tered inside the master.

     If the first argument to the place command is a window  path
     name  or  configure then the command arranges for the placer
     to manage the geometry of a slave whose path name is window.
     The  remaining arguments consist of one or more option-value
     pairs that specify the way in  which  window's  geometry  is
     managed.  If the placer is already managing window, then the
     option-value pairs modify the configuration for window.   In
     this  form  the  place  command  returns  an empty string as
     result.  The following option-value pairs are supported:

     -in master
          Master specifes the path name of the window relative to
          which  window  is  to be placed.  Master must either be
          window's parent or a descendant of window's parent.  In
          addition, master and window must both be descendants of
          the same  top-level  window.   These  restrictions  are
          necessary  to guarantee that window is visible whenever
          master is visible.  If this option isn't specified then
          the master defaults to window's parent.

     -x location
          Location specifies the x-coordinate within  the  master
          window of the anchor point for window.  The location is
          specified in  screen  units  (i.e.  any  of  the  forms
          accepted  by  Tk_GetPixels) and need not lie within the
          bounds of the master window.

     -relx location
          Location specifies the x-coordinate within  the  master
          window  of  the  anchor point for window.  In this case
          the location is specified in a relative  fashion  as  a
          floating-point  number:   0.0  corresponds  to the left
          edge of the master and 1.0  corresponds  to  the  right
          edge  of the master.  Location need not be in the range
          0.0-1.0.  If both -x and - relx  are  specified  for  a
          slave then their values are summed.  For example, -relx
          0.5 -x -2 positions the left edge of the slave 2 pixels
          to the left of the center of its master.

     -y location
          Location specifies the y-coordinate within  the  master
          window of the anchor point for window.  The location is
          specified in  screen  units  (i.e.  any  of  the  forms
          accepted  by  Tk_GetPixels) and need not lie within the
          bounds of the master window.

     -rely location
          Location specifies the y-coordinate within  the  master
          window  of  the  anchor point for window.  In this case
          the value is specified  in  a  relative  fashion  as  a
          floating-point number:  0.0 corresponds to the top edge
          of the master and 1.0 corresponds to the bottom edge of
          the master.  Location need not be in the range 0.0-1.0.
          If both -y and -rely are specified  for  a  slave  then
          their  values  are summed.  For example, -rely 0.5 -x 3
          positions the top edge of the slave 3 pixels below  the
          center of its master.

     -anchor where
          Where specifies which point of window is  to  be  posi-
          tioned  at the (x,y) location selected by the -x, -y, -
          relx, and -rely options.  The anchor point is in  terms
          of  the  outer  area of window including its border, if
          any.  Thus if where is se then the  lower-right  corner
          of window's border will appear at the given (x,y) loca-
          tion in the master.  The anchor  position  defaults  to
          nw.

     -width size
          Size specifies the width for  window  in  screen  units
          (i.e.  any of the forms accepted by Tk_GetPixels).  The
          width will be the outer width of window  including  its
          border, if any.  If size is an empty string, or if no -
          width or -relwidth option is specified, then the  width
          requested internally by the window will be used.

     -relwidth size
          Size specifies the width for window.  In this case  the
          width  is specified as a floating-point number relative
          to the width of the master: 0.5 means  window  will  be
          half  as wide as the master, 1.0 means window will have
          the same width as the master, and so  on.   If  both  -
          width  and  - relwidth are specified for a slave, their
          values are summed.  For example, -relwidth 1.0 -width 5
          makes the slave 5 pixels wider than the master.

     -height size
          Size specifies the height for window  in  screen  units
          (i.e.  any of the forms accepted by Tk_GetPixels).  The
          height will be the outer dimension of window  including
          its  border, if any.  If size is an empty string, or if
          no -height or -relheight option is specified, then  the
          height requested internally by the window will be used.

     -relheight size
          Size specifies the height for window.  In this case the
          height is specified as a floating-point number relative
          to the height of the master: 0.5 means window  will  be
          half  as high as the master, 1.0 means window will have
          the same height as the master, and so on.   If  both  -
          height  and -relheight are specified for a slave, their
          values are summed.  For example, -relheight 1.0 -height
          -2 makes the slave 2 pixels shorter than the master.

     -bordermode mode
          Mode determines the degree to which borders within  the
          master  are  used  in  determining the placement of the
          slave.  The default and most common  value  is  inside.
          In  this case the placer considers the area of the mas-
          ter to be the innermost area of the master, inside  any
          border:   an  option  of  - x  0  corresponds  to an x-
          coordinate just inside the border and an  option  of  -
          relwidth 1.0 means window will fill the area inside the
          master's border.  If mode is outside  then  the  placer
          considers the area of the master to include its border;
          this mode is typically used when placing window outside
          its  master,  as with the options -x 0 -y 0 -anchor ne.
          Lastly, mode may be specified as ignore, in which  case
          borders  are  ignored:   the area of the master is con-
          sidered to be its official X area, which  includes  any
          internal  border  but no external border.  A bordermode
          of ignore is probably not very useful.

     If the same value is specified separately with two different
     options,  such  as -x and -relx, then the most recent option
     is used and the older one is ignored.

     The place slaves command returns a list  of  all  the  slave
     windows  for  which  window  is the master.  If there are no
     slaves for window then an empty string is returned.

     The place forget command causes the placer to stop  managing
     the  geometry  of  window.  As a side effect of this command
     window will be unmapped so that it  doesn't  appear  on  the
     screen.   If  window  isn't  currently managed by the placer
     then the command has no effect.   Place  forget  returns  an
     empty string as result.

     The place info command returns a  list  giving  the  current
     configuration  of window.  The list consists of option-value
     pairs in exactly the same form as might be specified to  the
     place  configure  command.  If the configuration of a window
     has been retrieved with place info, that  configuration  can
     be  restored  later by first using place forget to erase any
     existing information for the window and then invoking  place
     configure with the saved information.

FINE POINTS

     It is not necessary for the master window to be  the  parent
     of the slave window.  This feature is useful in at least two
     situations.  First, for complex window layouts it means  you
     can  create  a hierarchy of subwindows whose only purpose is
     to assist in the layout of the  parent.   The  ``real  chil-
     dren''  of the parent (i.e. the windows that are significant
     for the application's user interface) can be children of the
     parent  yet  be  placed  inside the windows of the geometry-
     management hierarchy.  This means that the path names of the
     ``real  children''  don't  reflect  the  geometry-management
     hierarchy and users can specify options for the  real  chil-
     dren  without  being aware of the structure of the geometry-
     management hierarchy.

     A second reason for  having  a  master  different  than  the
     slave's  parent  is to tie two siblings together.  For exam-
     ple, the placer can be used to force a window always  to  be
     positioned centered just below one of its siblings by speci-
     fying the configuration
          -in sibling -relx 0.5 -rely 1.0 -anchor n -bordermode outside
     Whenever the sibling is  repositioned  in  the  future,  the
     slave will be repositioned as well.

     Unlike many other geometry managers (such as the packer) the
     placer  does not make any attempt to manipulate the geometry
     of the master windows or the parents of slave windows  (i.e.
     it doesn't set their requested sizes).  To control the sizes
     of these windows, make them windows like frames and canvases
     that provide configuration options for this purpose.

KEYWORDS

     geometry manager, height, location,  master,  place,  rubber
     sheet, slave, width
itcl2.2/html/tk4.2/popup.n.html100666 1751 0 2261 6423554671 15144 0ustar kunkeewheel tk4.2 User Commands - popup

tk4.2 User Commands - popup

NAME

     tk_popup - Post a popup menu

SYNOPSIS

     tk_popup menu x y ?entry?

DESCRIPTION

     This procedure posts a menu  at  a  given  position  on  the
     screen  and  configures Tk so that the menu and its cascaded
     children can be traversed with the mouse  or  the  keyboard.
     Menu  is  the name of a menu widget and x and y are the root
     coordinates at which to display the menu.  If entry is omit-
     ted  or  an  empty  string,  the menu's upper left corner is
     positioned at the given point.  Otherwise  entry  gives  the
     index of an entry in menu and the menu will be positioned so
     that the entry is positioned over the given point.

KEYWORDS

     menu, popup
itcl2.2/html/tk4.2/radiobutton.n.html100666 1751 0 32203 6423554671 16352 0ustar kunkeewheel tk4.2 User Commands - radiobutton

tk4.2 User Commands - radiobutton

NAME

     radiobutton - Create and manipulate radiobutton widgets

SYNOPSIS

     radiobutton pathName ?options?

STANDARD OPTIONS

     -activebackground              -cursor         -highlightthickness-takefocus
     -activeforeground              -disabledforeground-image-text
     -anchor         -font          -justify        -textvariable
     -background     -foreground    -padx           -underline
     -bitmap         -highlightbackground           -pady-wraplength
     -borderwidth    -highlightcolor                -relief

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

WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-command
     Database Name:  command
     Database Class: Command

          Specifies a Tcl command to associate with  the  button.
          This  command  is typically invoked when mouse button 1
          is released over the button window.  The button's  glo-
          bal  variable (-variable option) will be updated before
          the command is invoked.

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

          Specifies a desired height for the button.  If an image
          or  bitmap  is  being  displayed in the button then the
          value is in screen units (i.e. any of the forms accept-
          able to Tk_GetPixels); for text it is in lines of text.
          If this option isn't specified,  the  button's  desired
          height is computed from the size of the image or bitmap
          or text being displayed in it.

     Command-Line Name:-indicatoron
     Database Name:  indicatorOn
     Database Class: IndicatorOn

          Specifies whether or not the indicator should be drawn.
          Must  be  a proper boolean value.  If false, the relief
          option is ignored and the  widget's  relief  is  always
          sunken if the widget is selected and raised otherwise.


     Command-Line Name:-selectcolor
     Database Name:  selectColor
     Database Class: Background

          Specifies a background color to use when the button  is
          selected.   If indicatorOn is true, the color applicies
          to the indicator.  If indicatorOn is false, this  color
          is  used  as  the  background for the entire widget, in
          place of background or activeBackground,  whenever  the
          widget  is  selected.  If specified as an empty string,
          no special color is used for displaying when the widget
          is selected.

     Command-Line Name:-selectimage
     Database Name:  selectImage
     Database Class: SelectImage

          Specifies an image to display (in place  of  the  image
          option)  when the radiobutton is selected.  This option
          is ignored unless the image option has been specified.

     Command-Line Name:-state
     Database Name:  state
     Database Class: State

          Specifies one of  three  states  for  the  radiobutton:
          normal,  active,  or  disabled.   In  normal  state the
          radiobutton is displayed using the foreground and back-
          ground  options.   The  active  state is typically used
          when the pointer is over the  radiobutton.   In  active
          state   the   radiobutton   is   displayed   using  the
          activeForeground and  activeBackground  options.   Dis-
          abled state means that the radiobutton should be insen-
          sitive:  the default bindings will refuse  to  activate
          the  widget  and  will ignore mouse button presses.  In
          this  state  the  disabledForeground   and   background
          options determine how the radiobutton is displayed.

     Command-Line Name:-value
     Database Name:  value
     Database Class: Value

          Specifies value to store  in  the  button's  associated
          variable whenever this button is selected.

     Command-Line Name:-variable
     Database Name:  variable
     Database Class: Variable

          Specifies name of global variable to set whenever  this
          button  is  selected.   Changes  in  this variable also
          cause  the  button  to  select  or   deselect   itself.
          Defaults to the value selectedButton.

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

          Specifies a desired width for the button.  If an  image
          or  bitmap  is being displayed in the button, the value
          is in screen units (i.e. any of the forms acceptable to
          Tk_GetPixels);  for  text it is in characters.  If this
          option isn't specified, the button's desired  width  is
          computed  from  the size of the image or bitmap or text
          being displayed in it.

DESCRIPTION

     The radiobutton command creates a new window (given  by  the
     pathName  argument)  and makes it into a radiobutton widget.
     Additional options, described above, may be specified on the
     command  line or in the option database to configure aspects
     of the radiobutton such as its colors, font, text, and  ini-
     tial  relief.   The radiobutton 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 radiobutton is a widget that displays  a  textual  string,
     bitmap  or image and a diamond called an indicator.  If text
     is displayed, it must all be in a single font,  but  it  can
     occupy multiple lines on the screen (if it contains newlines
     or if wrapping occurs because of the wrapLength option)  and
     one of the characters may optionally be underlined using the
     underline option.  A radiobutton has all of the behavior  of
     a  simple  button:  it can display itself in either of three
     different ways, according to the state  option;  it  can  be
     made  to  appear  raised, sunken, or flat; it can be made to
     flash; and it invokes a Tcl command whenever mouse button  1
     is clicked over the check button.

     In addition, radiobuttons can be selected.  If a radiobutton
     is  selected,  the indicator is normally drawn with a sunken
     relief and a special color, and a  Tcl  variable  associated
     with  the  radiobutton is set to a particular value.  If the
     radiobutton is not selected, the indicator is drawn  with  a
     raised  relief  and  no  special  color.  Typically, several
     radiobuttons share a single variable and the  value  of  the
     variable  indicates  which  radiobutton  is  to be selected.
     When a radiobutton is selected it  sets  the  value  of  the
     variable to indicate that fact;  each radiobutton also moni-
     tors the value of the variable and automatically selects and
     deselects  itself  when  the  variable's  value changes.  By
     default the variable selectedButton is used;   its  contents
     give  the  name of the button that is selected, or the empty
     string  if  no  button  associated  with  that  variable  is
     selected.   The name of the variable for a radiobutton, plus
     the variable to be stored into  it,  may  be  modified  with
     options on the command line or in the option database.  Con-
     figuration options may also be used to modify  the  way  the
     indicator  is displayed (or whether it is displayed at all).
     By default a radiobutton is configured to select  itself  on
     button clicks.

WIDGET COMMAND

     The radiobutton 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 radiobutton
     widgets:

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

     pathName deselect
          Deselects the radiobutton and sets the associated vari-
          able  to  an empty string.  If this radiobutton was not
          currently selected, the command has no effect.

     pathName flash
          Flashes  the  radiobutton.   This  is  accomplished  by
          redisplaying the radiobutton several times, alternating
          between active and normal colors.  At the  end  of  the
          flash the radiobutton is left in the same normal/active
          state as when the command was invoked.  This command is
          ignored if the radiobutton's state is disabled.

     pathName invoke
          Does just what would have happened if the user  invoked
          the  radiobutton with the mouse: selects the button and
          invokes its associated Tcl command, if  there  is  one.
          The  return value is the return value from the Tcl com-
          mand, or an empty string if there is no command associ-
          ated  with the radiobutton.  This command is ignored if
          the radiobutton's state is disabled.

     pathName select
          Selects the radiobutton and sets the  associated  vari-
          able to the value corresponding to this widget.

BINDINGS

     Tk automatically creates  class  bindings  for  radiobuttons
     that give them the following default behavior:

     [1]  The radiobutton activates  whenever  the  mouse  passes
          over  it  and deactivates whenever the mouse leaves the
          radiobutton.

     [2]  When mouse button 1 is pressed over a radiobutton it is
          invoked (it becomes selected and the command associated
          with the button is invoked, if there is one).

     [3]  When a radiobutton has the input focus, the  space  key
          causes the radiobutton to be invoked.

     If the radiobutton's state is  disabled  then  none  of  the
     above  actions  occur:   the  radiobutton is completely non-
     responsive.

     The behavior of radiobuttons can be changed by defining  new
     bindings  for  individual widgets or by redefining the class
     bindings.

KEYWORDS

     radiobutton, widget
itcl2.2/html/tk4.2/raise.n.html100666 1751 0 2542 6423554671 15106 0ustar kunkeewheel tk4.2 User Commands - raise

tk4.2 User Commands - raise

NAME

     raise - Change a window's position in the stacking order

SYNOPSIS

     raise window ?aboveThis?

DESCRIPTION

     If the aboveThis argument is omitted then the command raises
     window so that it is above all of its siblings in the stack-
     ing order (it will not be obscured by any siblings and  will
     obscure  any  siblings  that  overlap  it).  If aboveThis is
     specified then it must be the path name of a window that  is
     either a sibling of window or the descendant of a sibling of
     window.  In this case the raise command will  insert  window
     into  the stacking order just above aboveThis (or the ances-
     tor of aboveThis that is a sibling of  window);  this  could
     end up either raising or lowering window.

SEE ALSO

     lower

KEYWORDS

     obscure, raise, stacking order
itcl2.2/html/tk4.2/scale.n.html100666 1751 0 35437 6423554671 15123 0ustar kunkeewheel tk4.2 User Commands - scale

tk4.2 User Commands - scale

NAME

     scale - Create and manipulate scale widgets

SYNOPSIS

     scale pathName ?options?

STANDARD OPTIONS

     -activebackground              -font           -highlightthickness-repeatinterval
     -background     -foreground    -orient         -takefocus
     -borderwidth    -highlightbackground           -relief-troughcolor
     -cursor         -highlightcolor                -repeatdelay

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

WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-bigincrement
     Database Name:  bigIncrement
     Database Class: BigIncrement

          Some interactions with the scale  cause  its  value  to
          change  by ``large'' increments;  this option specifies
          the size of the large increments.  If specified  as  0,
          the  large  increments default to 1/10 the range of the
          scale.

     Command-Line Name:-command
     Database Name:  command
     Database Class: Command

          Specifies the prefix of a Tcl command to  invoke  when-
          ever the scale's value is changed via a widget command.
          The actual command consists of this option followed  by
          a  space  and a real number indicating the new value of
          the scale.

     Command-Line Name:-digits
     Database Name:  digits
     Database Class: Digits

          An  integer  specifying  how  many  significant  digits
          should  be  retained  when  converting the value of the
          scale to a string.  If the number is less than or equal
          to  zero,  then the scale picks the smallest value that
          guarantees that every possible slider  position  prints
          as a different string.

     Command-Line Name:-from
     Database Name:  from
     Database Class: From
          A real value corresponding to the left or  top  end  of
          the scale.

     Command-Line Name:-label
     Database Name:  label
     Database Class: Label

          A string to display as a  label  for  the  scale.   For
          vertical  scales  the  label  is  displayed just to the
          right of the top end  of  the  scale.   For  horizontal
          scales  the  label is displayed just above the left end
          of the scale.  If the option is specified as  an  empty
          string, no label is displayed.

     Command-Line Name:-length
     Database Name:  length
     Database Class: Length

          Specifies the desired long dimension of  the  scale  in
          screen  units  (i.e.  any  of  the  forms acceptable to
          Tk_GetPixels).  For vertical scales this is the scale's
          height;  for horizontal scales it is the scale's width.

     Command-Line Name:-resolution
     Database Name:  resolution
     Database Class: Resolution

          A real value specifying the resolution for  the  scale.
          If  this  value  is  greater than zero then the scale's
          value will always be rounded to  an  even  multiple  of
          this value, as will tick marks and the endpoints of the
          scale.  If the value is less than zero then no rounding
          occurs.   Defaults  to  1  (i.e.,  the  value  will  be
          integral).

     Command-Line Name:-showvalue
     Database Name:  showValue
     Database Class: ShowValue

          Specifies a boolean value indicating whether or not the
          current value of the scale is to be displayed.

     Command-Line Name:-sliderlength
     Database Name:  sliderLength
     Database Class: SliderLength

          Specfies the size of the  slider,  measured  in  screen
          units along the slider's long dimension.  The value may
          be  specified  in  any  of  the  forms  acceptable   to
          Tk_GetPixels.


     Command-Line Name:-sliderrelief
     Database Name:  sliderRelief
     Database Class: SliderRelief

          Specifies the relief to use when  drawing  the  slider,
          such as raised or sunken.

     Command-Line Name:-state
     Database Name:  state
     Database Class: State

          Specifies one of three states for the  scale:   normal,
          active, or disabled.  If the scale is disabled then the
          value may not be changed and the scale won't  activate.
          If  the  scale is active, the slider is displayed using
          the color specified by the activeBackground option.

     Command-Line Name:-tickinterval
     Database Name:  tickInterval
     Database Class: TickInterval

          Must be a real value.  Determines the  spacing  between
          numerical  tick marks displayed below or to the left of
          the slider.  If 0, no tick marks will be displayed.

     Command-Line Name:-to
     Database Name:  to
     Database Class: To

          Specifies a real value corresponding to  the  right  or
          bottom end of the scale.  This value may be either less
          than or greater than the from option.

     Command-Line Name:-variable
     Database Name:  variable
     Database Class: Variable

          Specifies the name of a global variable to link to  the
          scale.  Whenever the value of the variable changes, the
          scale will update to reflect this value.  Whenever  the
          scale  is  manipulated interactively, the variable will
          be modified to reflect the scale's new value.

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

          Specifies the desired narrow dimension of the trough in
          screen  units  (i.e.  any  of  the  forms acceptable to
          Tk_GetPixels).   For  vertical  scales  this   is   the
          trough's  width;   for  horizontal  scales  this is the
          trough's height.

DESCRIPTION

     The scale command creates a new window (given by  the  path-
     Name argument) and makes it into a scale widget.  Additional
     options, described above, may be specified  on  the  command
     line  or  in the option database to configure aspects of the
     scale such as its  colors,  orientation,  and  relief.   The
     scale  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 scale is a widget that displays a rectangular trough and a
     small  slider.   The  trough  corresponds to a range of real
     values (determined by the from, to, and resolution options),
     and  the  position  of  the slider selects a particular real
     value.  The slider's position (and hence the scale's  value)
     may  be  adjusted with the mouse or keyboard as described in
     the BINDINGS section below.  Whenever the scale's  value  is
     changed, a Tcl command is invoked (using the command option)
     to notify other interested widgets of the change.  In  addi-
     tion, the value of the scale can be linked to a Tcl variable
     (using the variable option), so that changes in  either  are
     reflected in the other.

     Three annotations may be displayed in  a  scale  widget:   a
     label appearing at the top right of the widget (top left for
     horizontal scales), a number displayed just to the  left  of
     the  slider  (just  above the slider for horizontal scales),
     and a collection of numerical tick marks just to the left of
     the  current  value  (just  below  the trough for horizontal
     scales).  Each of these three annotations may be enabled  or
     disabled using the configuration options.

WIDGET COMMAND

     The scale 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 scale widg-
     ets:

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

     pathName coords ?value?
          Returns a list whose elements are the x and  y  coordi-
          nates  of  the point along the centerline of the trough
          that corresponds to value.  If value  is  omitted  then
          the scale's current value is used.

     pathName get ?x y?
          If x and y are omitted, returns the  current  value  of
          the  scale.   If x and y are specified, they give pixel
          coordinates within the widget;  the command returns the
          scale value corresponding to the given pixel.  Only one
          of x or y is used:  for horizontal scales y is ignored,
          and for vertical scales x is ignored.

     pathName identify x y
          Returns a string indicating what part of the scale lies
          under the coordinates given by x and y.  A return value
          of slider means that the  point  is  over  the  slider;
          trough1 means that the point is over the portion of the
          slider above  or to the left of the slider; and trough2
          means  that the point is over the portion of the slider
          below or to the right of  the  slider.   If  the  point
          isn't  over  one  of these elements, an empty string is
          returned.

     pathName set value
          This command is invoked to change the current value  of
          the  scale,  and hence the position at which the slider
          is displayed.  Value gives the new value for the scale.
          The command has no effect if the scale is disabled.

BINDINGS

     Tk automatically creates class bindings for scales that give
     them  the following default behavior.  Where the behavior is
     different for vertical and horizontal scales, the horizontal
     behavior is described in parentheses.

     [1]  If button 1 is pressed in the trough, the scale's value
          will  be incremented or decremented by the value of the
          resolution option so  that  the  slider  moves  in  the
          direction  of  the  cursor. If the button is held down,
          the action auto-repeats.

     [2]  If button 1 is pressed over the slider, the slider  can
          be dragged with the mouse.

     [3]  If button 1 is pressed in the trough with  the  Control
          key  down,  the  slider moves all the way to the end of
          its range, in the direction towards the mouse cursor.

     [4]  If button 2 is pressed, the scale's value is set to the
          mouse  position.  If the mouse is dragged with button 2
          down, the scale's value changes with the drag.

     [5]  The Up and Left keys move the slider up (left)  by  the
          value of the resolution option.

     [6]  The Down and Right keys move the slider down (right) by
          the value of the resolution option.

     [7]  Control-Up and Control-Left move the slider  up  (left)
          by the value of the bigIncrement option.

     [8]  Control-Down and Control-Right  move  the  slider  down
          (right) by the value of the bigIncrement option.

     [9]  Home moves the slider to the  top  (left)  end  of  its
          range.

     [10] End moves the slider to the bottom (right) end  of  its
          range.

     If the scale is disabled using the state option then none of
     the above bindings have any effect.

     The behavior of scales can be changed by defining new  bind-
     ings for individual widgets or by redefining the class bind-
     ings.

KEYWORDS

     scale, slider, trough, widget
itcl2.2/html/tk4.2/scrollbar.n.html100666 1751 0 46047 6423554672 16017 0ustar kunkeewheel tk4.2 User Commands - scrollbar

tk4.2 User Commands - scrollbar

NAME

     scrollbar - Create and manipulate scrollbar widgets

SYNOPSIS

     scrollbar pathName ?options?

STANDARD OPTIONS

     -activebackground              -highlightbackground-orient-takefocus
     -background     -highlightcolor                -relief-troughcolor
     -borderwidth    -highlightthickness            -repeatdelay
     -cursor         -jump          -repeatinterval

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

WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-activerelief
     Database Name:  activeRelief
     Database Class: ActiveRelief

          Specifies the relief to use when displaying the element
          that is active, if any.  Elements other than the active
          element are always displayed with a raised relief.

     Command-Line Name:-command
     Database Name:  command
     Database Class: Command

          Specifies the prefix of a  Tcl  command  to  invoke  to
          change  the  view  in  the  widget  associated with the
          scrollbar.  When a user requests a view change by mani-
          pulating  the scrollbar, a Tcl command is invoked.  The
          actual command consists  of  this  option  followed  by
          additional information as described later.  This option
          almost always has a value such as .t xview or .t yview,
          consisting of the name of a widget and either xview (if
          the scrollbar is for  horizontal  scrolling)  or  yview
          (for  vertical scrolling).  All scrollable widgets have
          xview and yview commands that take  exactly  the  addi-
          tional arguments appended by the scrollbar as described
          in SCROLLING COMMANDS below.

     Command-Line Name:-elementborderwidth
     Database Name:  elementBorderWidth
     Database Class: BorderWidth

          Specifies the width of borders drawn around the  inter-
          nal  elements  of the scrollbar (the two arrows and the
          slider).  The value may have any of the  forms  accept-
          able to Tk_GetPixels.  If this value is less than zero,
          the value of the borderWidth  option  is  used  in  its
          place.

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

          Specifies the desired narrow dimension of the scrollbar
          window, not including 3-D border, if any.  For vertical
          scrollbars this will be the width  and  for  horizontal
          scrollbars this will be the height.  The value may have
          any of the forms acceptable to Tk_GetPixels.

DESCRIPTION

     The scrollbar command creates a new  window  (given  by  the
     pathName  argument)  and  makes  it into a scrollbar widget.
     Additional options, described above, may be specified on the
     command  line or in the option database to configure aspects
     of the  scrollbar  such  as  its  colors,  orientation,  and
     relief.   The  scrollbar  command returns its pathName argu-
     ment.  At the time this command is invoked, there  must  not
     exist  a  window  named pathName, but pathName's parent must
     exist.

     A scrollbar is a widget that displays  two  arrows,  one  at
     each  end  of the scrollbar, and a slider in the middle por-
     tion of the scrollbar.  It provides information  about  what
     is visible in an associated window that displays an document
     of some sort (such as a file being  edited  or  a  drawing).
     The  position  and size of the slider indicate which portion
     of the document is visible in the  associated  window.   For
     example,  if  the  slider in a vertical scrollbar covers the
     top third of the area between the two arrows, it means  that
     the  associated  window  displays the top third of its docu-
     ment.

     Scrollbars can be used to adjust the view in the  associated
     window  by  clicking  or  dragging  with the mouse.  See the
     BINDINGS section below for details.

ELEMENTS

     A scrollbar displays five elements, which are referred to in
     the widget commands for the scrollbar:

     arrow1    The top or left arrow in the scrollbar.

     trough1   The region between the slider and arrow1.

     slider    The rectangle that indicates what  is  visible  in
               the associated widget.

     trough2   The region between the slider and arrow2.

     arrow2    The bottom or right arrow in the scrollbar.

WIDGET COMMAND

     The scrollbar 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 scrollbar
     widgets:

     pathName activate ?element?
          Marks the element indicated by element as active, which
          causes   it   to  be  displayed  as  specified  by  the
          activeBackground and activeRelief  options.   The  only
          element  values  understood by this command are arrow1,
          slider, or arrow2.  If any  other  value  is  specified
          then  no  element  of the scrollbar will be active.  If
          element is not specified, the command returns the  name
          of  the  element  that is currently active, or an empty
          string if no element is active.

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

     pathName delta deltaX deltaY
          Returns a real number indicating the fractional  change
          in  the  scrollbar  setting that corresponds to a given
          change  in  slider  position.   For  example,  if   the
          scrollbar  is horizontal, the result indicates how much
          the scrollbar setting must change to  move  the  slider
          deltaX  pixels  to the right (deltaY is ignored in this
          case).  If the scrollbar is vertical, the result  indi-
          cates  how  much  the  scrollbar setting must change to
          move the slider deltaY pixels down.  The arguments  and
          the result may be zero or negative.

     pathName fraction x y
          Returns a real number between 0 and 1 indicating  where
          the  point  given by x and y lies in the trough area of
          the scrollbar.  The value 0 corresponds to the  top  or
          left of the trough, the value 1 corresponds to the bot-
          tom or right, 0.5 corresponds to the middle, and so on.
          X  and  y  must  be  pixel  coordinates relative to the
          scrollbar widget.  If x and y refer to a point  outside
          the trough, the closest point in the trough is used.

     pathName get
          Returns the scrollbar settings in the form  of  a  list
          whose elements are the arguments to the most recent set
          widget command.

     pathName identify x y
          Returns the name of the element under the  point  given
          by  x and y (such as arrow1), or an empty string if the
          point does not lie in any element of the scrollbar.   X
          and  y  must  be  pixel  coordinates  relative  to  the
          scrollbar widget.

     pathName set first last
          This command is invoked by the  scrollbar's  associated
          widget  to tell the scrollbar about the current view in
          the widget.  The command takes two arguments,  each  of
          which  is  a  real fraction between 0 and 1.  The frac-
          tions describe the range of the document that is  visi-
          ble in the associated widget.  For example, if first is
          0.2 and last is 0.4, it means that the  first  part  of
          the  document  visible  in the window is 20% of the way
          through the document, and the last visible part is  40%
          of the way through.

SCROLLING COMMANDS

     When the user interacts with the scrollbar, for  example  by
     dragging  the  slider, the scrollbar notifies the associated
     widget that it must change its view.   The  scrollbar  makes
     the  notification by evaluating a Tcl command generated from
     the scrollbar's -command option.  The command may  take  any
     of  the  following  forms.  In each case, prefix is the con-
     tents of the -command option, which usually has a form  like
     .t yview
     prefix moveto fraction
          Fraction is a real number between 0 and 1.  The  widget
          should adjust its view so that the point given by frac-
          tion appears at the beginning of the widget.  If  frac-
          tion  is  0 it refers to the beginning of the document.
          1.0 refers to the end of the document, 0.333 refers  to
          a  point one-third of the way through the document, and
          so on.

     prefix scroll number unit
          The widget should adjust its view by number units.  The
          units  are  defined in whatever way makes sense for the
          widget, such as characters or lines in a  text  widget.
          Number  is either 1, which means one unit should scroll
          off the top or left of the window, or -1,  which  means
          that  one unit should scroll off the bottom or right of
          the window.

     prefix scroll number page
          The widget should adjust its view by number pages.   It
          is  up  to  the widget to define the meaning of a page;
          typically it is slightly less than  what  fits  in  the
          window,  so  that there is a slight overlap between the
          old and new views.  Number is either 1, which means the
          next  page  should  become  visible, or -1, which means
          that the previous page should become visible.

OLD COMMAND SYNTAX

     In versions of Tk before 4.0, the set and  get  widget  com-
     mands  used  a different form.  This form is still supported
     for backward compatibility, but it is  deprecated.   In  the
     old command syntax, the set widget command has the following
     form:

     pathName set totalUnits windowUnits firstUnit lastUnit
          In this form the arguments are all integers.   TotalUn-
          its  gives the total size of the object being displayed
          in the associated widget.   The  meaning  of  one  unit
          depends  on  the  associated widget;  for example, in a
          text editor widget units might correspond to  lines  of
          text.   WindowUnits indicates the total number of units
          that can fit in the  associated  window  at  one  time.
          FirstUnit  and  lastUnit  give the indices of the first
          and last units currently visible in the associated win-
          dow (zero corresponds to the first unit of the object).

     Under the old syntax the get widget command returns  a  list
     of four integers, consisting of the totalUnits, windowUnits,
     firstUnit, and lastUnit values from the last set widget com-
     mand.

     The commands generated by scrollbars also have  a  different
     form when the old syntax is being used:

     prefix unit
          Unit is an integer that indicates what should appear at
          the  top or left of the associated widget's window.  It
          has the same meaning  as  the  firstUnit  and  lastUnit
          arguments to the set widget command.

     The most recent set widget command determines whether or not
     to  use  the  old syntax.  If it is given two real arguments
     then the new syntax will be used in the future, and if it is
     given  four  integer  arguments  then the old syntax will be
     used.

BINDINGS

     Tk automatically creates class bindings for scrollbars  that
     give  them  the following default behavior.  If the behavior
     is different for vertical  and  horizontal  scrollbars,  the
     horizontal behavior is described in parentheses.


     [1]  Pressing button 1 over arrow1 causes the  view  in  the
          associated  widget  to  shift  up (left) by one unit so
          that the document appears  to  move  down  (right)  one
          unit.   If  the  button  is held down, the action auto-
          repeats.

     [2]  Pressing button 1 over trough1 causes the view  in  the
          associated  widget  to shift up (left) by one screenful
          so that the document appears to move down  (right)  one
          screenful.   If  the  button  is  held down, the action
          auto-repeats.

     [3]  Pressing button 1 over the slider and  dragging  causes
          the  view  to drag with the slider.  If the jump option
          is true, then the view  doesn't  drag  along  with  the
          slider;   it  changes  only  when  the  mouse button is
          released.

     [4]  Pressing button 1 over trough2 causes the view  in  the
          associated  widget to shift down (right) by one screen-
          ful so that the document appears to move up (left)  one
          screenful.   If  the  button  is  held down, the action
          auto-repeats.

     [5]  Pressing button 1 over arrow2 causes the  view  in  the
          associated  widget to shift down (right) by one unit so
          that the document appears to move up (left)  one  unit.
          If the button is held down, the action auto-repeats.

     [6]  If button 2 is pressed over the trough or  the  slider,
          it  sets  the view to correspond to the mouse position;
          dragging the mouse with button 2 down causes  the  view
          to  drag  with  the mouse.  If button 2 is pressed over
          one of the arrows,  it  causes  the  same  behavior  as
          pressing button 1.

     [7]  If button 1 is pressed with the Control key down,  then
          if the mouse is over arrow1 or trough1 the view changes
          to the very top (left) of the document;  if  the  mouse
          is  over arrow2 or trough2 the view changes to the very
          bottom (right) of the document;  if the mouse  is  any-
          where else then the button press has no effect.

     [8]  In vertical scrollbars the Up and Down  keys  have  the
          same  behavior  as mouse clicks over arrow1 and arrow2,
          respectively.  In horizontal scrollbars these keys have
          no effect.

     [9]  In vertical scrollbars Control-Up and Control-Down have
          the  same  behavior  as  mouse  clicks over trough1 and
          trough2, respectively.  In horizontal scrollbars  these
          keys have no effect.

     [10] In horizontal scrollbars the Up and Down keys have  the
          same  behavior  as mouse clicks over arrow1 and arrow2,
          respectively.  In vertical scrollbars these  keys  have
          no effect.

     [11] In horizontal scrollbars  Control-Up  and  Control-Down
          have the same behavior as mouse clicks over trough1 and
          trough2, respectively.  In  vertical  scrollbars  these
          keys have no effect.

     [12] The Prior and Next keys have the same behavior as mouse
          clicks over trough1 and trough2, respectively.

     [13] The Home key adjusts the view to the top (left edge) of
          the document.

     [14] The End key adjusts the view to the bottom (right edge)
          of the document.

KEYWORDS

     scrollbar, widget
itcl2.2/html/tk4.2/selection.n.html100666 1751 0 20201 6423554672 16001 0ustar kunkeewheel tk4.2 User Commands - selection

tk4.2 User Commands - selection

NAME

     selection - Manipulate the X selection

SYNOPSIS

     selection option ?arg arg ...?

DESCRIPTION

     This command provides a Tcl interface  to  the  X  selection
     mechanism  and  implements  the full selection functionality
     described in the X  Inter-Client  Communication  Conventions
     Manual (ICCCM).

     The first argument to selection determines the format of the
     rest  of the arguments and the behavior of the command.  The
     following forms are currently supported:

     selection clear ?-displayof window? ?-selection selection?
          If selection exists anywhere on window's display, clear
          it  so  that  no  window  owns  the  selection anymore.
          Selection specifies the  X  selection  that  should  be
          cleared,  and should be an atom name such as PRIMARY or
          CLIPBOARD; see the Inter-Client  Communication  Conven-
          tions  Manual for complete details.  Selection defaults
          to PRIMARY and window defaults to  ``.''.   Returns  an
          empty string.

type?

     selection get ?-displayof window? ?-selection selection? ? -
           type
          Retrieves the value of selection from window's  display
          and returns it as a result.  Selection defaults to PRI-
          MARY and window defaults to ``.''. Type  specifies  the
          form  in  which  the  selection  is to be returned (the
          desired ``target'' for conversion, in  ICCCM  terminol-
          ogy),  and  should  be  an  atom name such as STRING or
          FILE_NAME; see the Inter-Client  Communication  Conven-
          tions  Manual  for  complete details.  Type defaults to
          STRING.  The selection owner may choose to  return  the
          selection  in  any  of several different representation
          formats, such as STRING, ATOM, INTEGER, etc. (this for-
          mat is different than the selection type; see the ICCCM
          for all the confusing details).  If  the  selection  is
          returned  in  a  non-string  format, such as INTEGER or
          ATOM, the selection command converts it to string  for-
          mat  as  a  collection  of  fields separated by spaces:
          atoms are converted to their textual  names,  and  any-
          thing else is converted to hexadecimal integers.

format? window command

     selection handle ?-selection selection? ?- type  type?  ?  -
           format
          Creates a handler for  selection  requests,  such  that
          command will be executed whenever selection is owned by
          window and someone attempts to retrieve it in the  form
          given  by type (e.g. type is specified in the selection
          get command).   Selection  defaults  to  PRIMARY,  type
          defaults  to STRING, and format defaults to STRING.  If
          command is an empty string then  any  existing  handler
          for window, type, and selection is removed.

          When selection is requested, window  is  the  selection
          owner,  and type is the requested type, command will be
          executed as a Tcl command with two  additional  numbers
          appended  to  it (with space separators). The two addi-
          tional numbers are offset and maxBytes:  offset  speci-
          fies a starting character position in the selection and
          maxBytes gives the maximum number of bytes to retrieve.
          The command should return a value consisting of at most
          maxBytes of the selection, starting at position offset.
          For  very  large  selections (larger than maxBytes) the
          selection will be retrieved using  several  invocations
          of  command  with increasing offset values.  If command
          returns a string whose length is  less  than  maxBytes,
          the  return  value  is  assumed  to  include all of the
          remainder of the selection;  if the length of command's
          result  is  equal  to  maxBytes  then  command  will be
          invoked again, until it  eventually  returns  a  result
          shorter  than  maxBytes.   The  value  of maxBytes will
          always be relatively large (thousands of bytes).

          If  command  returns  an  error  then   the   selection
          retrieval  is  rejected just as if the selection didn't
          exist at all.

          The format argument specifies the  representation  that
          should be used to transmit the selection to the reques-
          ter (the second column of Table 2 of  the  ICCCM),  and
          defaults to STRING.  If format is STRING, the selection
          is transmitted as 8-bit ASCII characters (i.e.  just in
          the form returned by command).  If format is ATOM, then
          the return value from command is  divided  into  fields
          separated  by  white space;  each field is converted to
          its atom value, and the 32-bit atom value is  transmit-
          ted  instead  of  the atom name.  For any other format,
          the return value from command is  divided  into  fields
          separated by white space and each field is converted to
          a 32-bit integer;  an array of integers is  transmitted
          to the selection requester.


          The format argument is needed  only  for  compatibility
          with  selection requesters that don't use Tk.  If Tk is
          being used to retrieve the selection then the value  is
          converted  back  to  a string at the requesting end, so
          format is irrelevant.

     selection own ?-displayof window? ?-selection selection?

     selection own ?        -        command command? ?         -
          selection selection? window
          The first form of selection own returns the  path  name
          of  the  window in this application that owns selection
          on the display containing window, or an empty string if
          no  window  in  this  application  owns  the selection.
          Selection defaults to PRIMARY and  window  defaults  to
          ``.''.

     The second form of selection own causes window to become the
     new  owner  of  selection  on window's display, returning an
     empty string as result. The existing owner, if any, is noti-
     fied  that  it has lost the selection.  If command is speci-
     fied, it is a Tcl script to execute when some  other  window
     claims  ownership of the selection away from window.  Selec-
     tion defaults to PRIMARY.

KEYWORDS

     clear, format, handler, ICCCM, own, selection, target, type
itcl2.2/html/tk4.2/send.n.html100666 1751 0 10417 6423554672 14755 0ustar kunkeewheel tk4.2 User Commands - send

tk4.2 User Commands - send

NAME

     send - Execute a command in a different application

SYNOPSIS

     send ?options? app cmd ?arg arg ...?

DESCRIPTION

     This command arranges for cmd (and args) to be  executed  in
     the  application  named  by  app.   It returns the result or
     error from that command execution.  App may be the  name  of
     any application whose main window is on the display contain-
     ing the sender's main window;  it need  not  be  within  the
     same  process.   If  no  arg arguments are present, then the
     command to be executed is contained entirely within the  cmd
     argument.   If  one  or more args are present, they are con-
     catenated to form the command to be executed,  just  as  for
     the eval command.

     If the initial arguments of the command begin  with  `` - ''
     they  are  treated  as  options.   The following options are
     currently defined:

     -async
          Requests asynchronous invocation.   In  this  case  the
          send  command will complete immediately without waiting
          for cmd to complete  in  the  target  application;   no
          result will be available and errors in the sent command
          will be ignored.  If the target application is  in  the
          same process as the sending application then the -async
          option is ignored.

     -displayof pathName
          Specifies that the target application's main window  is
          on the display of the window given by pathName, instead
          of the display containing the application's  main  win-
          dow.

     --     Serves no purpose except to  terminate  the  list  of
          options.   This option is needed only if app could con-
          tain a leading ``-'' character.

APPLICATION NAMES

     The name of an application is set initially from the name of
     the program or script that created the application.  You can
     query and change the name of  an  application  with  the  tk
     appname command.

DISABLING SENDS

     If the send command is removed  from  an  application  (e.g.
     with  the  command rename send {}) then the application will
     not respond to incoming send requests anymore,  nor will  it
     be  able  to  issue outgoing requests.  Communication can be
     reenabled by invoking the tk appname command.

SECURITY

     The send command is potentially a serious security loophole,
     since  any application that can connect to your X server can
     send scripts to your applications.  These  incoming  scripts
     can  use  Tcl  to  read and write your files and invoke sub-
     processes under your name.  Host-based access  control  such
     as that provided by xhost is particularly insecure, since it
     allows anyone with an account on particular hosts to connect
     to your server, and if disabled it allows anyone anywhere to
     connect to your server.  In order  to  provide  at  least  a
     small amount of security, Tk checks the access control being
     used by the server and rejects  incoming  sends  unless  (a)
     xhost-style  access  control  is  enabled (i.e. only certain
     hosts can establish connections) and (b) the list of enabled
     hosts is empty.  This means that applications cannot connect
     to your server unless they use some other form of authoriza-
     tion such as that provide by xauth.

KEYWORDS

     application, name, remote execution, security, send
itcl2.2/html/tk4.2/text.n.html100666 1751 0 260137 6423554673 15037 0ustar kunkeewheel tk4.2 User Commands - text

tk4.2 User Commands - text

NAME

     text - Create and manipulate text widgets

SYNOPSIS

     text pathName ?options?

STANDARD OPTIONS

     -background     -highlightbackground           -insertontime-selectborderwidth
     -borderwidth    -highlightcolor                -insertwidth-selectforeground
     -cursor         -highlightthickness            -padx-setgrid
     -exportselection               -insertbackground-pady-takefocus
     -font           -insertborderwidth             -relief-xscrollcommand
     -foreground     -insertofftime -selectbackground-yscrollcommand

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

WIDGET-SPECIFIC OPTIONS

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

          Specifies the desired height for the window,  in  units
          of  characters  in  the font given by the -font option.
          Must be at least one.

     Command-Line Name:-spacing1
     Database Name:  spacing1
     Database Class: Spacing1

          Requests additional space above each text line  in  the
          widget, using any of the standard forms for screen dis-
          tances.  If a line wraps, this option only  applies  to
          the  first  line  on  the  display.  This option may be
          overriden with -spacing1 options in tags.

     Command-Line Name:-spacing2
     Database Name:  spacing2
     Database Class: Spacing2

          For lines that wrap (so that they cover more  than  one
          line  on  the display) this option specifies additional
          space  to  provide  between  the  display  lines   that
          represent  a  single  line of text.  The value may have
          any of the standard forms for screen  distances.   This
          option may be overriden with -spacing2 options in tags.

     Command-Line Name:-spacing3
     Database Name:  spacing3
     Database Class: Spacing3
          Requests additional space below each text line  in  the
          widget, using any of the standard forms for screen dis-
          tances.  If a line wraps, this option only  applies  to
          the last line on the display.  This option may be over-
          riden with -spacing3 options in tags.

     Command-Line Name:-state
     Database Name:  state
     Database Class: State

          Specifies one of two states for the  text:   normal  or
          disabled.   If the text is disabled then characters may
          not be inserted or deleted and no insertion cursor will
          be displayed, even if the input focus is in the widget.

     Command-Line Name:-tabs
     Database Name:  tabs
     Database Class: Tabs

          Specifies a set of  tab  stops  for  the  window.   The
          option's  value  consists of a list of screen distances
          giving the positions of the tab stops.   Each  position
          may  optionally be followed in the next list element by
          one of the keywords left, right,  center,  or  numeric,
          which specifies how to justify text relative to the tab
          stop.  Left is the default; it causes the text  follow-
          ing  the  tab  character to be positioned with its left
          edge at the tab position.  Right means that  the  right
          edge  of  the text following the tab character is posi-
          tioned at the tab position, and center means  that  the
          text  is  centered  at the tab position.  Numeric means
          that the decimal point in the text is positioned at the
          tab  position;   if  there is no decimal point then the
          least significant digit of  the  number  is  positioned
          just  to  the left of the tab position;  if there is no
          number in the text then the text is right-justified  at
          the  tab  position.   For example, -tabs {2c left 4c 6c
          center}  creates  three  tab  stops  at  two-centimeter
          intervals;   the  first  two use left justification and
          the third uses center justification.  If  the  list  of
          tab stops does not have enough elements to cover all of
          the tabs in a text line, then Tk extrapolates  new  tab
          stops using the spacing and alignment from the last tab
          stop in the list.  The value of the tabs option may  be
          overridden  by  - tabs  options  in  tags.  If no -tabs
          option is specified, or if it is specified as an  empty
          list,  then  Tk  uses  default  tabs spaced every eight
          (average size) characters.

     Command-Line Name:-width
     Database Name:  width
     Database Class: Width
          Specifies the desired width for the window in units  of
          characters  in  the font given by the -font option.  If
          the font doesn't have a uniform width then the width of
          the character ``0'' is used in translating from charac-
          ter units to screen units.

     Command-Line Name:-wrap
     Database Name:  wrap
     Database Class: Wrap

          Specifies how to handle lines in the text that are  too
          long  to  be  displayed  in a single line of the text's
          window.  The value must be none or  char  or  word.   A
          wrap  mode of none means that each line of text appears
          as exactly one line on the  screen;   extra  characters
          that don't fit on the screen are not displayed.  In the
          other modes each line of text will be  broken  up  into
          several screen lines if necessary to keep all the char-
          acters visible.  In char mode a screen line  break  may
          occur  after  any  character; in word mode a line break
          will only be made at word boundaries.

DESCRIPTION

     The text command creates a new window (given by the pathName
     argument)  and  makes  it  into  a  text widget.  Additional
     options, described above, may be specified  on  the  command
     line  or  in the option database to configure aspects of the
     text such as its default background color and  relief.   The
     text command returns the path name of the new window.

     A text widget displays one or more lines of text and  allows
     that  text  to  be  edited.  Text widgets support three dif-
     ferent kinds of annotations on the text, called tags, marks,
     and  embedded windows.  Tags allow different portions of the
     text to be displayed with different fonts  and  colors.   In
     addition,  Tcl  commands can be associated with tags so that
     scripts are invoked when particular actions  such  as  keys-
     trokes  and  mouse button presses occur in particular ranges
     of the text.  See TAGS below for more details.

     The second form of annotation consists of marks,  which  are
     floating  markers in the text.  Marks are used to keep track
     of various interesting  positions  in  the  text  as  it  is
     edited.  See MARKS below for more details.

     The third form of annotation allows arbitrary windows to  be
     embedded  in  a text widget.  See EMBEDDED WINDOWS below for
     more details.

INDICES

     Many of the widget commands  for  texts  take  one  or  more
     indices as arguments.  An index is a string used to indicate
     a particular place within a text, such as a place to  insert
     characters  or  one  endpoint  of  a  range of characters to
     delete.  Indices have the syntax
          base modifier modifier modifier ...
     Where base gives a starting point and the  modifiers  adjust
     the  index  from  the  starting  point (e.g. move forward or
     backward one character).  Every index must contain  a  base,
     but the modifiers are optional.

     The base for an index must have one of the following forms:

     line.char   Indicates char'th character on line line.  Lines
                 are  numbered  from 1 for consistency with other
                 UNIX programs that use  this  numbering  scheme.
                 Within  a  line, characters are numbered from 0.
                 If char is end then it  refers  to  the  newline
                 character that ends the line.

     @x,y        Indicates the character that  covers  the  pixel
                 whose x and y coordinates within the text's win-
                 dow are x and y.

     end         Indicates the end of  the  text  (the  character
                 just after the last newline).

     mark        Indicates the  character  just  after  the  mark
                 whose name is mark.

     tag.first   Indicates the first character in the  text  that
                 has  been  tagged with tag.  This form generates
                 an error if no characters are  currently  tagged
                 with tag.

     tag.last    Indicates the character just after the last  one
                 in the text that has been tagged with tag.  This
                 form generates an error  if  no  characters  are
                 currently tagged with tag.

     pathName    Indicates the position of  the  embedded  window
                 whose  name is pathName.  This form generates an
                 error if there is  no  embedded  window  by  the
                 given name.

     If modifiers follow the base index, each one  of  them  must
     have  one of the forms listed below.  Keywords such as chars
     and wordend may be abbreviated as long as  the  abbreviation
     is unambiguous.

     + count chars
          Adjust the index forward by count characters, moving to
          later  lines  in  the  text if necessary.  If there are
          fewer than count  characters  in  the  text  after  the
          current index, then set the index to the last character
          in the text.   Spaces  on  either  side  of  count  are
          optional.

     - count chars
          Adjust the index backward by count  characters,  moving
          to  earlier  lines  in the text if necessary.  If there
          are fewer than count characters in the text before  the
          current  index, then set the index to the first charac-
          ter in the text.  Spaces on either side  of  count  are
          optional.

     + count lines
          Adjust the index forward by count lines, retaining  the
          same  character position within the line.  If there are
          fewer than count lines after the  line  containing  the
          current  index, then set the index to refer to the same
          character position on the last line of the text.  Then,
          if  the  line is not long enough to contain a character
          at the indicated character position, adjust the charac-
          ter position to refer to the last character of the line
          (the newline).  Spaces on  either  side  of  count  are
          optional.

     - count lines
          Adjust the index backward by count lines, retaining the
          same  character position within the line.  If there are
          fewer than count lines before the line  containing  the
          current  index, then set the index to refer to the same
          character position on  the  first  line  of  the  text.
          Then, if the line is not long enough to contain a char-
          acter at the indicated character position,  adjust  the
          character  position  to  refer to the last character of
          the line (the newline).  Spaces on either side of count
          are optional.

     linestart
          Adjust the index to refer to the first character on the
          line.

     lineend
          Adjust the index to refer to the last character on  the
          line (the newline).

     wordstart
          Adjust the index to refer to the first character of the
          word  containing the current index.  A word consists of
          any number of adjacent  characters  that  are  letters,
          digits,  or  underscores, or a single character that is
          not one of these.

     wordend
          Adjust the index to refer to the character  just  after
          the  last one of the word containing the current index.
          If the current index refers to the  last  character  of
          the text then it is not modified.

     If more than one modifier is present then they  are  applied
     in  left-to-right  order.   For example, the index ``end - 1
     chars'' refers to the next-to-last character in the text and
     ``insert  wordstart  -  1  c''  refers to the character just
     before the first one in the word  containing  the  insertion
     cursor.

TAGS

     The first form of annotation in text widgets is  a  tag.   A
     tag  is a textual string that is associated with some of the
     characters in a text.  Tags may  contain  arbitrary  charac-
     ters, but it is probably best to avoid using the the charac-
     ters `` '' (space), +, or -:  these characters have  special
     meaning in indices, so tags containing them can't be used as
     indices.  There may be any number of  tags  associated  with
     characters  in a text.  Each tag may refer to a single char-
     acter, a range of characters, or several ranges  of  charac-
     ters.   An  individual character may have any number of tags
     associated with it.

     A priority order is defined among tags, and  this  order  is
     used  in  implementing  some  of  the  tag-related functions
     described below.  When a tag is defined (by  associating  it
     with  characters  or  setting its display options or binding
     commands to it), it is given  a  priority  higher  than  any
     existing  tag.   The priority order of tags may be redefined
     using the ``pathName tag raise'' and ``pathName tag  lower''
     widget commands.

     Tags serve three purposes in text widgets.  First, they con-
     trol  the  way  information  is displayed on the screen.  By
     default, characters are displayed as determined by the back-
     ground,  font,  and  foreground options for the text widget.
     However, display options may be associated  with  individual
     tags  using  the  ``pathName tag configure'' widget command.
     If a character has been tagged,  then  the  display  options
     associated  with the tag override the default display style.
     The following options are currently supported for tags:

     -background color
          Color specifies the background color to use for charac-
          ters  associated  with the tag.  It may have any of the
          forms accepted by Tk_GetColor.

     -bgstipple bitmap
          Bitmap specifies a bitmap that is  used  as  a  stipple
          pattern  for  the  background.   It may have any of the
          forms accepted by Tk_GetBitmap.  If bitmap hasn't  been
          specified,  or  if  it is specified as an empty string,
          then a solid fill will be used for the background.

     -borderwidth pixels
          Pixels specifies the width of  a  3-D  border  to  draw
          around  the  background.   It may have any of the forms
          accepted by Tk_GetPixels.  This option is used in  con-
          junction  with the -relief option to give a 3-D appear-
          ance to the background for characters;  it  is  ignored
          unless the -background option has been set for the tag.

     -fgstipple bitmap
          Bitmap specifies a bitmap that is  used  as  a  stipple
          pattern when drawing text and other foreground informa-
          tion such as underlines.  It may have any of the  forms
          accepted by Tk_GetBitmap.  If bitmap hasn't been speci-
          fied, or if it is specified as an empty string, then  a
          solid fill will be used.

     -font fontName
          FontName is the name of a font to use for drawing char-
          acters.   It  may  have  any  of  the forms accepted by
          Tk_GetFontStruct.

     -foreground color
          Color specifies the color to use when drawing text  and
          other  foreground  information  such as underlines.  It
          may have any of the forms accepted by Tk_GetColor.

     -justify justify
          If the first character of a display line has a tag  for
          which  this  option  has  been  specified, then justify
          determines how to justify the line.  It must be one  of
          left, right, or center.  If a line wraps, then the jus-
          tification for each line on the display  is  determined
          by the first character of that display line.

     -lmargin1 pixels
          If the first character of a text line  has  a  tag  for
          which  this  option  has  been  specified,  then pixels
          specifies how much the line should be indented from the
          left  edge  of  the window.  Pixels may have any of the
          standard forms for screen distances.  If a line of text
          wraps,  this  option  only applies to the first line on
          the display;  the -lmargin2 option controls the  inden-
          tation for subsequent lines.

     -lmargin2 pixels
          If the first character of a display line has a tag  for
          which  this  option  has  been  specified,  and  if the
          display line is not the first for its text line  (i.e.,
          the  text  line has wrapped), then pixels specifies how
          much the line should be indented from the left edge  of
          the  window.  Pixels may have any of the standard forms
          for screen distances.  This option is  only  used  when
          wrapping  is enabled, and it only applies to the second
          and later display lines for a text line.

     -offset pixels
          Pixels specifies an amount by which the text's baseline
          should  be  offset  vertically from the baseline of the
          overall line,  in  pixels.   For  example,  a  positive
          offset  can  be  used  for  superscripts and a negative
          offset can be used for subscripts.  Pixels may have any
          of the standard forms for screen distances.

     -overstrike boolean
          Specifies whether or not  to  draw  a  horizontal  rule
          through the middle of characters.  Boolean may have any
          of the forms accepted by Tk_GetBoolean.

     -relief relief
          Relief specifies the 3-D  relief  to  use  for  drawing
          backgrounds,   in   any   of   the  forms  accepted  by
          Tk_GetRelief.  This option is used in conjunction  with
          the -borderwidth option to give a 3-D appearance to the
          background for characters; it is ignored unless  the  -
          background option has been set for the tag.

     -rmargin pixels
          If the first character of a display line has a tag  for
          which  this  option  has  been  specified,  then pixels
          specifies how wide a margin to leave between the end of
          the  line and the right edge of the window.  Pixels may
          have any of the standard forms  for  screen  distances.
          This  option is only used when wrapping is enabled.  If
          a text line wraps, the right margin for  each  line  on
          the  display  is  determined  by the first character of
          that display line.

     -spacing1 pixels
          Pixels specifies how much additional  space  should  be
          left  above  each  text line, using any of the standard
          forms for screen distances.   If  a  line  wraps,  this
          option only applies to the first line on the display.

     -spacing2 pixels
          For lines that wrap, this  option  specifies  how  much
          additional space to leave between the display lines for
          a single  text  line.   Pixels  may  have  any  of  the
          standard forms for screen distances.

     -spacing3 pixels
          Pixels specifies how much additional  space  should  be
          left  below  each  text line, using any of the standard
          forms for screen distances.   If  a  line  wraps,  this
          option only applies to the last line on the display.

     -tabs tabList
          TabList specifies a set of tab stops in the  same  form
          as  for  the  - tabs  option for the text widget.  This
          option only applies to a display line if it applies  to
          the  first  character  on  that  display line.  If this
          option is specified as an empty string, it cancels  the
          option,   leaving  it  unspecified  for  the  tag  (the
          default).  If the option is specified  as  a  non-empty
          string  that  is an empty list, such as -tags { }, then
          it requests default 8-character tabs as  described  for
          the tags widget option.

     -underline boolean
          Boolean specifies whether or not to draw  an  underline
          underneath  characters.   It  may have any of the forms
          accepted by Tk_GetBoolean.

     -wrap mode
          Mode specifies how to handle lines that are wider  than
          the text's window.  It has the same legal values as the
          -wrap option for the text widget:  none, char, or word.
          If this tag option is specified, it overrides the -wrap
          option for the text widget.

     If a character has several tags associated with it,  and  if
     their  display  options  conflict,  then  the options of the
     highest priority tag are  used.   If  a  particular  display
     option  hasn't been specified for a particular tag, or if it
     is specified as an empty string, then that option will never
     be  used;   the next-highest-priority tag's option will used
     instead.  If no tag specifies a particular  display  option,
     then the default style for the widget will be used.

     The second purpose for tags  is  event  bindings.   You  can
     associate  bindings  with a tag in much the same way you can
     associate bindings with a widget class:  whenever particular
     X events occur on characters with the given tag, a given Tcl
     command will be executed.  Tag bindings can be used to  give
     behaviors  to ranges of characters; among other things, this
     allows  hypertext-like  features  to  be  implemented.   For
     details,  see the description of the tag bind widget command
     below.


     The third use for tags is in managing  the  selection.   See
     THE SELECTION below.

MARKS

     The second form of annotation in text  widgets  is  a  mark.
     Marks  are used for remembering particular places in a text.
     They are something like tags, in that they  have  names  and
     they  refer  to places in the file, but a mark isn't associ-
     ated with particular characters.  Instead, a mark is associ-
     ated  with  the  gap  between two characters.  Only a single
     position may be associated with a mark at  any  given  time.
     If  the  characters  around a mark are deleted the mark will
     still remain;  it will just have  new  neighbor  characters.
     In  contrast, if the characters containing a tag are deleted
     then the tag will no longer have an association with charac-
     ters in the file.  Marks may be manipulated with the ``path-
     Name mark'' widget command, and their current locations  may
     be  determined  by using the mark name as an index in widget
     commands.

     Each mark also has a gravity, which is either left or right.
     The  gravity  for  a mark specifies what happens to the mark
     when text is inserted at the point of the mark.  If  a  mark
     has  left  gravity,  then  the mark is treated as if it were
     attached to the character on its  left,  so  the  mark  will
     remain  to  the  left of any text inserted at the mark posi-
     tion.  If the mark has right gravity, new text  inserted  at
     the mark position will appear to the right of the mark.  The
     gravity for a mark defaults to right.

     The name space for marks is different from  that  for  tags:
     the  same  name  may  be used for both a mark and a tag, but
     they will refer to different things.

     Two marks have special significance.  First, the mark insert
     is  associated with the insertion cursor, as described under
     THE INSERTION CURSOR below.  Second,  the  mark  current  is
     associated  with  the  character closest to the mouse and is
     adjusted automatically to track the mouse position  and  any
     changes  to  the text in the widget (one exception:  current
     is not updated in response to mouse motions if a mouse  but-
     ton  is  down;   the update will be deferred until all mouse
     buttons have been released).  Neither of these special marks
     may be deleted.

EMBEDDED WINDOWS

     The third form of annotation in text widgets is an  embedded
     window.   Each embedded window annotation causes a window to
     be displayed at a particular point in  the text.  There  may
     be  any number of embedded windows in a text widget, and any
     widget may be used as an embedded  window  (subject  to  the
     usual  rules for geometry management, which require the text
     window to be the parent of the embedded window or a  descen-
     dant  of its parent).  The embedded window's position on the
     screen will be updated as the text is modified or  scrolled,
     and  it will be mapped and unmapped as it moves into and out
     of the visible area of the text widget.  Each embedded  win-
     dow  occupies  one  character's  worth of index space in the
     text widget, and it may be referred to either by the name of
     its embedded window or by its position in the widget's index
     space.  If the range of text containing the embedded  window
     is deleted then the window is destroyed.

     When an embedded window is added to a text widget  with  the
     window  create widget command, several configuration options
     may be associated with it.  These options may  be   modified
     later with the window configure widget command.  The follow-
     ing options are currently supported:

     -align where
          If the window is not as tall as the line in which it is
          displayed,  this  option determines where the window is
          displayed in the line.  Where  must  have  one  of  the
          values top (align the top of the window with the top of
          the line), center (center the window within  the  range
          of  the  line),  bottom (align the bottom of the window
          with the bottom of the line's area), or baseline (align
          the  bottom  of  the  window  with  the baseline of the
          line).

     -create script
          Specifies a Tcl script that may be evaluated to  create
          the  window  for  the annotation.  If no -window option
          has been specified for the annotation this script  will
          be  evaluated  when  the  annotation  is  about  to  be
          displayed on the screen.  Script must create  a  window
          for  the  annotation and return the name of that window
          as its result.  If the annotation's window should  ever
          be  deleted,  script  will  be evaluated again the next
          time the annotation is displayed.

     -padx pixels
          Pixels specifies the amount of extra space to leave  on
          each  side  of the embedded window.  It may have any of
          the usual forms defined for a screen distance.

     -pady pixels
          Pixels specifies the amount of extra space to leave  on
          the  top  and on the bottom of the embedded window.  It
          may have any of the usual forms defined  for  a  screen
          distance.

     -stretch boolean
          If the requested height of the embedded window is  less
          than  the  height of the line in which it is displayed,
          this option can be used to specify whether  the  window
          should  be  stretched  vertically to fill its line.  If
          the -pady option has been specified as well,  then  the
          requested  padding  will be retained even if the window
          is stretched.

     -window pathName
          Specifies the name of a window to display in the  anno-
          tation.

THE SELECTION

     Text widgets support the standard  X  selection.   Selection
     support  is  implemented  via  tags.  If the exportSelection
     option for the text widget is true then the sel tag will  be
     associated with the selection:

     [1]  Whenever characters are tagged with sel the text widget
          will claim ownership of the selection.

     [2]  Attempts to retrieve the selection will be serviced  by
          the  text widget, returning all the characters with the
          sel tag.

     [3]  If the selection is claimed away by another application
          or  by another window within this application, then the
          sel tag will be removed  from  all  characters  in  the
          text.

     The sel tag is automatically defined when a text  widget  is
     created,  and  it may not be deleted with the ``pathName tag
     delete'' widget command.  Furthermore, the selectBackground,
     selectBorderWidth, and selectForeground options for the text
     widget are tied to the -background, -borderwidth, and -fore-
     ground  options  for  the  sel  tag:  changes in either will
     automatically be reflected in the other.

THE INSERTION CURSOR

     The mark named insert has special significance in text widg-
     ets.   It  is  defined  automatically  when a text widget is
     created and it may not be unset  with  the  ``pathName  mark
     unset''  widget  command.   The  insert  mark represents the
     position of the insertion cursor, and the  insertion  cursor
     will  automatically be drawn at this point whenever the text
     widget has the input focus.

WIDGET COMMAND

     The text command creates a new Tcl command whose name is the
     same  as  the  path name of the text's window.  This command
     may be used to invoke various operations on the widget.   It
     has the following general form:
          pathName option ?arg arg ...?
     PathName is the name of the command, which is  the  same  as
     the  text widget's path name.  Option and the args determine
     the exact behavior of the command.  The  following  commands
     are possible for text widgets:

     pathName bbox index
          Returns a list of four elements describing  the  screen
          area  of  the  character given by index.  The first two
          elements of the list give the x and  y  coordinates  of
          the upper-left corner of the area occupied by the char-
          acter, and the last two elements  give  the  width  and
          height of the area.  If the character is only partially
          visible on the screen, then the return  value  reflects
          just the visible part.  If the character is not visible
          on the screen then the return value is an empty 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 text command.

     pathName compare index1 op index2
          Compares the indices given by index1 and index2 accord-
          ing to the relational operator given by op, and returns
          1 if the relationship is satisfied and 0 if  it  isn't.
          Op  must  be  one of the operators <, <=, ==, >=, >, or
          !=.  If op is == then 1 is returned if the two  indices
          refer  to  the  same  character,  if  op is < then 1 is
          returned if index1 refers to an  earlier  character  in
          the text than index2, and so on.

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

     pathName debug ?boolean?
          If boolean is specified, then it must have one  of  the
          true  or  false  values accepted by Tcl_GetBoolean.  If
          the value is  a  true  one  then  internal  consistency
          checks  will be turned on in the B-tree code associated
          with text widgets.  If boolean has a false  value  then
          the  debugging  checks  will  be turned off.  In either
          case the command returns an empty string.   If  boolean
          is  not specified then the command returns on or off to
          indicate whether or not debugging is turned on.   There
          is  a  single debugging switch shared by all text widg-
          ets:  turning debugging on or off in any  widget  turns
          it  on  or off for all widgets.  For widgets with large
          amounts of text, the consistency  checks  may  cause  a
          noticeable slow-down.

     pathName delete index1 ?index2?
          Delete a range of characters from the  text.   If  both
          index1  and  index2  are specified, then delete all the
          characters starting with the one given  by  index1  and
          stopping  just  before  index2  (i.e.  the character at
          index2 is not deleted).  If index2  doesn't  specify  a
          position  later in the text than index1 then no charac-
          ters are deleted.  If index2 isn't specified  then  the
          single  character  at  index1  is  deleted.   It is not
          allowable to delete characters  in  a  way  that  would
          leave the text without a newline as the last character.
          The command returns an empty string.

     pathName dlineinfo index
          Returns a list with five elements describing  the  area
          occupied  by  the  display  line containing index.  The
          first two elements of the list give the x and y coordi-
          nates  of the upper-left corner of the area occupied by
          the line, the third and fourth elements give the  width
          and height of the area, and the fifth element gives the
          position of the baseline for the  line,  measured  down
          from  the  top of the area.  All of this information is
          measured in pixels.  If the current wrap mode  is  none
          and  the line extends beyond the boundaries of the win-
          dow, the area returned reflects the entire area of  the
          line,  including  the portions that are out of the win-
          dow.  If the line is shorter than the full width of the
          window then the area returned reflects just the portion
          of the line that is occupied by characters and embedded
          windows.   If  the display line containing index is not
          visible on the screen then the return value is an empty
          list.

     pathName dump ?switches? index1 ?index2?
          Return the contents of the text widget from  index1  up
          to,  but  not  including index2, including the text and
          information about marks, tags,  and  embedded  windows.
          If  index2  is  not  specified, then it defaults to one
          character past index1.  The information is returned  in
          the following format:

          key1 value1 index1 key2 value2 index2 ...

          The possible key values are text, mark, tagon,  tagoff,
          and  window.  The corresponding value is the text, mark
          name, tag name, or window name.  The index  information
          is  the  index  of the start of the text, the mark, the
          tag transition, or the window.  One or more of the fol-
          lowing  switches  (or  abbreviations  thereof)  may  be
          specified to control the dump:

          -all  Return  information  about  all  elements:  text,
               marks, tags, and windows.  This is the default.

          -command command
               Instead of returning the information as the result
               of  the dump operation, invoke the command on each
               element of the text widget within the range.   The
               command  has three arguments appended to it before
               it is evaluated:  the key, value, and index.

          -mark
               Include  information  about  marks  in  the   dump
               results.

          -tag  Include information about tag transitions in  the
               dump results. Tag information is returned as tagon
               and tagoff elements that indicate  the  begin  and
               end of each range of each tag, respectively.

          -text
               Include  information  about  text  in   the   dump
               results.   The  value  is  the text up to the next
               element or the end of range indicated  by  index2.
               A  text  element does not span newlines.  A multi-
               line block of text that contains no marks  or  tag
               transitions  will still be dumped as a set of text
               seqments that each end with a newline.   The  new-
               line is part of the value.

          -window
               Include information about embedded windows in  the
               dump  results.   The  value  of a window is its Tk
               pathname, unless the window has not  been  created
               yet.   (It  must  have  a create script.)  In this
               case an empty string is  returned,  and  you  must
               query the window by its index position to get more
               information.

     pathName get index1 ?index2?
          Return a range of characters from the text.  The return
          value  will  be all the characters in the text starting
          with the one whose index  is  index1  and  ending  just
          before  the one whose index is index2 (the character at
          index2 will not be returned).   If  index2  is  omitted
          then  the  single  character at index1 is returned.  If
          there are no characters in the  specified  range  (e.g.
          index1  is  past  the end of the file or index2 is less
          than or equal  to  index1)  then  an  empty  string  is
          returned.   If  the  specified  range contains embedded
          windows, no information about them is included  in  the
          returned string.

     pathName index index
          Returns the position corresponding to index in the form
          line.char where line is the line number and char is the
          character number.  Index may  have  any  of  the  forms
          described under INDICES above.

     pathName insert index chars ?tagList chars tagList ...?
          Inserts all of the  chars  arguments  just  before  the
          character  at index.  If index refers to the end of the
          text (the character after the last  newline)  then  the
          new  text  is  inserted  just  before  the last newline
          instead.  If there is a single chars  argument  and  no
          tagList,  then  the new text will receive any tags that
          are present on both the character before and the  char-
          acter after the insertion point; if a tag is present on
          only one of  these  characters  then  it  will  not  be
          applied  to the new text.  If tagList is specified then
          it consists of a list of tag names;  the new characters
          will  receive  all of the tags in this list and no oth-
          ers, regardless of the tags present around  the  inser-
          tion  point.   If multiple chars-tagList argument pairs
          are present, they produce  the  same  effect  as  if  a
          separate insert widget command had been issued for each
          pair, in order.  The last tagList argument may be omit-
          ted.

     pathName mark option ?arg arg ...?
          This command is used to manipulate  marks.   The  exact
          behavior  of the command depends on the option argument
          that follows the mark argument.  The following forms of
          the command are currently supported:

          pathName mark gravity markName ?direction?
               If direction is not  specified,  returns  left  or
               right to indicate which of its adjacent characters
               markName is attached to.  If direction  is  speci-
               fied,  it  must  be  left or right; the gravity of
               markName is set to the given value.

          pathName mark names
               Returns a list whose elements are the names of all
               the marks that are currently set.

          pathName mark next index
               Returns the name of the  next  mark  at  or  after
               index.   If  index is specified in numerical form,
               then the search for the next mark begins  at  that
               index.   If  index is the name of a mark, then the
               search for the next mark begins immediately  after
               that  mark.   This  can still return a mark at the
               same position if there are multiple marks  at  the
               same  index.   These  semantics mean that the mark
               next operation can be used to step through all the
               marks  in  a  text widget in the same order as the
               mark information returned by the  dump  operation.
               If  a  mark has been set to the special end index,
               then it appears to be after end  with  respect  to
               the  mark  next  operation.   An  empty  string is
               returned if there are no marks after index.

          pathName mark previous index
               Returns the name of the mark at or  before  index.
               If  index is specified in numerical form, then the
               search for the previous mark begins with the char-
               acter  just  before  that  index.  If index is the
               name of a mark, then the search for the next  mark
               begins  immediately  before  that  mark.  This can
               still return a mark at the same position if  there
               are  multiple  marks  at  the  same  index.  These
               semantics mean that the  mark  previous  operation
               can  be  used  to  step through all the marks in a
               text widget in  the  reverse  order  as  the  mark
               information  returned  by  the dump operation.  An
               empty string is returned if  there  are  no  marks
               before index.

          pathName mark set markName index
               Sets the mark named markName to  a  position  just
               before   the  character  at  index.   If  markName
               already exists, it is moved from its old position;
               if  it doesn't exist, a new mark is created.  This
               command returns an empty string.

          pathName mark unset markName ?markName markName ...?
               Remove the mark corresponding to each of the mark-
               Name  arguments.   The  removed  marks will not be
               usable in indices and  will  not  be  returned  by
               future  calls  to  ``pathName  mark names''.  This
               command returns an empty string.

     pathName scan option args
          This command is used to implement  scanning  on  texts.
          It has two forms, depending on option:

          pathName scan mark x y
               Records x and y and the current view in  the  text
               window,  for  use  in  conjunction with later scan
               dragto commands.  Typically this command is  asso-
               ciated  with  a  mouse button press in the widget.
               It returns an empty string.

          pathName scan dragto x y
               This command computes the difference between its x
               and  y  arguments and the x and y arguments to the
               last scan mark command for the  widget.   It  then
               adjusts  the  view  by  10 times the difference in
               coordinates.  This command is typically associated
               with mouse motion events in the widget, to produce
               the effect of dragging  the  text  at  high  speed
               through  the window.  The return value is an empty
               string.

     pathName search ?switches? pattern index ?stopIndex?
          Searches the text in pathName starting at index  for  a
          range  of  characters that matches pattern.  If a match
          is found, the index of the first character in the match
          is  returned  as  result;  otherwise an empty string is
          returned.  One or more of the  following  switches  (or
          abbreviations  thereof) may be specified to control the
          search:

          -forwards
               The search will proceed forward through the  text,
               finding  the  first  matching range starting at or
               after the position given by index.   This  is  the
               default.

          -backwards
               The search will proceed backward through the text,
               finding  the matching range closest to index whose
               first character is before index.

          -exact
               Use exact matching:  the characters in the  match-
               ing  range  must be identical to those in pattern.
               This is the default.

          -regexp
               Treat pattern as a regular expression and match it
               against  the  text  using  the  rules  for regular
               expressions (see the regexp command for details).

          -nocase
               Ignore case differences between  the  pattern  and
               the text.

          -count varName
               The argument following -count gives the name of  a
               variable; if a match is found, the number of char-
               acters in the matching range will be stored in the
               variable.

          --     This switch has no effect  except  to  terminate
               the  list  of switches:  the next argument will be
               treated as pattern even if it starts with -.

          The matching range must be  entirely  within  a  single
          line of text.  For regular expression matching the new-
          lines are removed from the ends  of  the  lines  before
          matching:   use the $ feature in regular expressions to
          match the end of a line.  For exact matching  the  new-
          lines  are  retained.   If  stopIndex is specified, the
          search stops at that index:  for forward  searches,  no
          match  at  or  after stopIndex will be considered;  for
          backward searches, no match earlier in  the  text  than
          stopIndex will be considered.  If stopIndex is omitted,
          the entire text will be searched:  when  the  beginning
          or  end of the text is reached, the search continues at
          the other end until the starting  location  is  reached
          again;   if stopIndex is specified, no wrap-around will
          occur.

     pathName see index
          Adjusts the view in the window so  that  the  character
          given  by  index  is  completely  visible.  If index is
          already visible then  the  command  does  nothing.   If
          index  is  a  short  distance  out of view, the command
          adjusts the view just enough to make index  visible  at
          the  edge  of the window.  If index is far out of view,
          then the command centers index in the window.

     pathName tag option ?arg arg ...?
          This command is used to  manipulate  tags.   The  exact
          behavior  of the command depends on the option argument
          that follows the tag argument.  The following forms  of
          the command are currently supported:

          pathName tag add tagName index1 ?index2 index1 index2 ...?
               Associate  the tag tagName with all of the charac-
               ters starting with index1 and ending  just  before
               index2  (the character at index2 isn't tagged).  A
               single command may contain any number of  index1 -
               index2  pairs.  If the last index2 is omitted then
               the single character  at  index1  is  tagged.   If
               there  are  no  characters  in the specified range
               (e.g. index1 is past the end of the file or index2
               is  less than or equal to index1) then the command
               has no effect.

          pathName tag bind tagName ?sequence? ?script?
               This command associates script with the tag  given
               by  tagName.  Whenever the event sequence given by
               sequence occurs for  a  character  that  has  been
               tagged  with  tagName, the script will be invoked.
               This widget command is similar to the bind command
               except  that  it  operates on characters in a text
               rather than entire widgets.  See the  bind  manual
               entry  for  complete  details  on  the  syntax  of
               sequence and the substitutions performed on script
               before  invoking  it.  If all arguments are speci-
               fied then a new binding is created, replacing  any
               existing binding for the same sequence and tagName
               (if the first character of script  is  ``+''  then
               script  augments  an  existing binding rather than
               replacing it).  In this case the return  value  is
               an  empty  string.   If script is omitted then the
               command returns the script associated with tagName
               and  sequence (an error occurs if there is no such
               binding).  If both script and sequence are omitted
               then  the  command  returns  a  list  of  all  the
               sequences for which bindings have been defined for
               tagName.

               The only events for which bindings may  be  speci-
               fied  are those related to the mouse and keyboard,
               such as Enter,  Leave,  ButtonPress,  Motion,  and
               KeyPress.   Event  bindings  for a text widget use
               the current mark described under MARKS above.   An
               Enter  event triggers for a tag when the tag first
               becomes present on the current  character,  and  a
               Leave  event  triggers for a tag when it ceases to
               be present on the current  character.   Enter  and
               Leave events can happen either because the current
               mark moved or because the character at that  posi-
               tion  changed.   Note  that  these events are dif-
               ferent than Enter and Leave  events  for  windows.
               Mouse  and  keyboard  events  are  directed to the
               current character.

               It is possible for the current character  to  have
               multiple  tags,  and  for  each  of them to have a
               binding for a  particular  event  sequence.   When
               this  occurs, one binding is invoked for each tag,
               in order from lowest-priority to highest priority.
               If there are multiple matching bindings for a sin-
               gle tag, then the most specific binding is  chosen
               (see  the  manual  entry  for the bind command for
               details).   continue  and  break  commands  within
               binding  scripts  are processed in the same way as
               for bindings created with the bind command.

               If bindings are created for the widget as a  whole
               using  the  bind command, then those bindings will
               supplement the tag  bindings.   The  tag  bindings
               will  be  invoked  first, followed by bindings for
               the window as a whole.

          pathName tag cget tagName option
               This command returns  the  current  value  of  the
               option  named option associated with the tag given
               by tagName.  Option may have  any  of  the  values
               accepted by the tag configure widget command.

          value ...?
          pathName tag  configure  tagName  ?option?  ?value?  ?option
               This  command  is  similar to the configure widget
               command except that it modifies options associated
               with the tag given by tagName instead of modifying
               options for the overall text widget.  If no option
               is  specified, the command returns a list describ-
               ing all of the available options for tagName  (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 option(s) to have the given value(s) in tag-
               Name;  in  this  case the command returns an empty
               string.  See TAGS above for details on the options
               available for tags.

          pathName tag delete tagName ?tagName ...?
               Deletes all tag information for each of  the  tag-
               Name arguments.  The command removes the tags from
               all characters in the file and  also  deletes  any
               other  information  associated with the tags, such
               as bindings and display information.  The  command
               returns an empty string.

          pathName tag lower tagName ?belowThis?
               Changes the priority of tag tagName so that it  is
               just  lower in priority than the tag whose name is
               belowThis.   If   belowThis   is   omitted,   then
               tagName's  priority  is  changed to make it lowest
               priority of all tags.

          pathName tag names ?index?
               Returns a list whose elements are the names of all
               the tags that are active at the character position
               given by index.  If index  is  omitted,  then  the
               return  value  will  describe all of the tags that
               exist for the text (this includes  all  tags  that
               have  been named in a ``pathName tag'' widget com-
               mand but haven't been deleted by a ``pathName  tag
               delete'' widget command, even if no characters are
               currently marked with the tag).  The list will  be
               sorted  in  order  from lowest priority to highest
               priority.

          pathName tag nextrange tagName index1 ?index2?
               This command searches the  text  for  a  range  of
               characters  tagged  with  tagName  where the first
               character of the range  is  no  earlier  than  the
               character  at index1 and no later than the charac-
               ter just before index2 (a range starting at index2
               will  not  be  considered).   If  several matching
               ranges  exist,  the  first  one  is  chosen.   The
               command's  return  value  is a list containing two
               elements, which are the index of the first charac-
               ter  of  the  range and the index of the character
               just after the last  one  in  the  range.   If  no
               matching  range  is found then the return value is
               an empty string.  If index2 is not given  then  it
               defaults to the end of the text.

          pathName tag prevrange tagName index1 ?index2?
               This command searches the  text  for  a  range  of
               characters  tagged  with  tagName  where the first
               character of the range is before the character  at
               index1 and no earlier than the character at index2
               (a range starting at index2 will  be  considered).
               If  several matching ranges exist, the one closest
               to index1 is chosen.  The command's  return  value
               is  a  list containing two elements, which are the
               index of the first character of the range and  the
               index  of the character just after the last one in
               the range.  If no matching range is found then the
               return value is an empty string.  If index2 is not
               given then it defaults to  the  beginning  of  the
               text.

          pathName tag raise tagName ?aboveThis?
               Changes the priority of tag tagName so that it  is
               just higher in priority than the tag whose name is
               aboveThis.   If   aboveThis   is   omitted,   then
               tagName's  priority  is changed to make it highest
               priority of all tags.

          pathName tag ranges tagName
               Returns a list describing all  of  the  ranges  of
               text  that  have  been  tagged  with tagName.  The
               first two elements of the list describe the  first
               tagged  range  in  the text, the next two elements
               describe the second range, and so on.   The  first
               element  of  each  pair  contains the index of the
               first character of the range, and the second  ele-
               ment of the pair contains the index of the charac-
               ter just after the last  one  in  the  range.   If
               there  are  no  characters tagged with tag then an
               empty string is returned.

          ...?
          pathName tag remove tagName  index1  ?index2  index1  index2
               Remove  the tag tagName from all of the characters
               starting at index1 and ending just  before  index2
               (the  character at index2 isn't affected).  A sin-
               gle command may contain  any  number  of  index1 -
               index2  pairs.  If the last index2 is omitted then
               the single character  at  index1  is  tagged.   If
               there  are  no  characters  in the specified range
               (e.g. index1 is past the end of the file or index2
               is  less than or equal to index1) then the command
               has no effect.   This  command  returns  an  empty
               string.

     pathName window option ?arg arg ...?
          This command is used to  manipulate  embedded  windows.
          The behavior of the command depends on the option argu-
          ment that follows  the  tag  argument.   The  following
          forms of the command are currently supported:

          pathName window cget index option
               Returns the value of a configuration option for an
               embedded  window.   Index  identifies the embedded
               window, and option specifies a  particular  confi-
               guration  option,  which  must  be one of the ones
               listed in the section EMBEDDED WINDOWS.

          pathName window configure index ?option value ...?
               Query or modify the configuration options  for  an
               embedded  window.   If  no  option  is  specified,
               returns a list describing  all  of  the  available
               options  for  the  embedded  window  at index (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  option(s)  to  have the given value(s);  in
               this case the command  returns  an  empty  string.
               See   EMBEDDED  WINDOWS  for  information  on  the
               options that are supported.

          pathName window create index ?option value ...?
               This command  creates  a  new  window  annotation,
               which  will  appear  in  the  text at the position
               given by index.  Any number of option-value  pairs
               may be specified to configure the annotation.  See
               EMBEDDED WINDOWS for information  on  the  options
               that are supported.  Returns an empty string.

          pathName window names
               Returns a list whose elements are the names of all
               windows currently embedded in window.

     pathName xview option args
          This command is used to query and change the horizontal
          position  of  the  text in the widget's window.  It can
          take any of the following forms:

          pathName xview
               Returns a list containing two elements.  Each ele-
               ment is a real fraction between 0 and 1;  together
               they describe the portion of the  document's  hor-
               izontal  span  that is visible in the window.  For
               example, if the first element is .2 and the second
               element  is  .6,  20% of the text is off-screen to
               the left, the middle 40% is visible in the window,
               and  40%  of  the text is off-screen to the right.
               The fractions refer only to  the  lines  that  are
               actually  visible  in the window:  if the lines in
               the window are all very short, so  that  they  are
               entirely visible, the returned fractions will be 0
               and 1, even if there are other lines in  the  text
               that  are  much  wider than the window.  These are
               the same values passed to  scrollbars  via  the  -
               xscrollcommand option.

          pathName xview moveto fraction
               Adjusts the view in the window so that fraction of
               the  horizontal  span of the text is off-screen to
               the left.  Fraction is a fraction between 0 and 1.

          pathName xview scroll number what
               This command shifts the view in the window left or
               right  according  to number and what.  Number must
               be an integer.  What must be either units or pages
               or  an  abbreviation  of one of these.  If what is
               units, the view adjusts left or  right  by  number
               average-width characters on the display;  if it is
               pages then the view adjusts by number  screenfuls.
               If  number  is negative then characters farther to
               the left become visible;  if it is  positive  then
               characters farther to the right become visible.

     pathName yview ?args?
          This command is used to query and change  the  vertical
          position  of  the  text in the widget's window.  It can
          take any of the following forms:

          pathName yview
               Returns a list containing two  elements,  both  of
               which  are  real  fractions  between 0 and 1.  The
               first element gives  the  position  of  the  first
               character  in the top line in the window, relative
               to the text as a whole (0.5 means  it  is  halfway
               through  the  text, for example).  The second ele-
               ment gives the  position  of  the  character  just
               after  the last one in the bottom line of the win-
               dow, relative to the text as a whole.   These  are
               the  same  values  passed  to scrollbars via the -
               yscrollcommand option.

          pathName yview moveto fraction
               Adjusts the view in the window so that the charac-
               ter  given  by fraction appears on the top line of
               the window.  Fraction is a fraction between 0  and
               1;   0  indicates the first character in the text,
               0.33 indicates the  character  one-third  the  way
               through the text, and so on.

          pathName yview scroll number what
               This command adjust the view in the window  up  or
               down according to number and what.  Number must be
               an integer.  What must be either units  or  pages.
               If  what  is units, the view adjusts up or down by
               number lines on the display;  if it is pages  then
               the  view adjusts by number screenfuls.  If number
               is negative then earlier  positions  in  the  text
               become  visible;   if  it  is  positive then later
               positions in the text become visible.

          pathName yview ?-pickplace? index
               Changes the view in the widget's  window  to  make
               index  visible.   If  the  -pickplace option isn't
               specified then index will appear at the top of the
               window.   If  - pickplace  is  specified  then the
               widget chooses where index appears in the window:

               [1]  If index is already visible somewhere in  the
                    window then the command does nothing.

               [2]  If index is only a few lines off-screen above
                    the  window then it will be positioned at the
                    top of the window.

               [3]  If index is only a few lines off-screen below
                    the  window then it will be positioned at the
                    bottom of the window.

               [4]  Otherwise, index will be centered in the win-
                    dow.

               The -pickplace option has been  obsoleted  by  the
               see  widget  command  (see  handles both x- and y-
               motion to make a location visible, whereas - pick-
               place only handles motion in y).

          pathName yview number
               This command makes the first character on the line
               after  the  one given by number visible at the top
               of the window.  Number must be an  integer.   This
               command  used to be used for scrolling, but now it
               is obsolete.

BINDINGS

     Tk automatically creates class bindings for texts that  give
     them  the  following  default behavior.  In the descriptions
     below, ``word'' refers to a  contiguous  group  of  letters,
     digits,  or  ``_'' characters, or any single character other
     than these.

     [1]  Clicking mouse button 1 positions the insertion  cursor
          just  before the character underneath the mouse cursor,
          sets the input focus to this  widget,  and  clears  any
          selection  in the widget.  Dragging with mouse button 1
          strokes out a selection between  the  insertion  cursor
          and the character under the mouse.

     [2]  Double-clicking with mouse button 1  selects  the  word
          under  the  mouse and positions the insertion cursor at
          the beginning of the word.   Dragging  after  a  double
          click  will  stroke out a selection consisting of whole
          words.

     [3]  Triple-clicking with mouse button 1  selects  the  line
          under  the  mouse and positions the insertion cursor at
          the beginning of the line.   Dragging  after  a  triple
          click  will  stroke out a selection consisting of whole
          lines.

     [4]  The ends of the selection can be adjusted  by  dragging
          with  mouse button 1 while the Shift key is down;  this
          will adjust the end of the selection that  was  nearest
          to  the mouse cursor when button 1 was pressed.  If the
          button  is  double-clicked  before  dragging  then  the
          selection will be adjusted in units of whole words;  if
          it  is  triple-clicked  then  the  selection  will   be
          adjusted in units of whole lines.

     [5]  Clicking mouse button 1 with the Control key down  will
          reposition  the  insertion cursor without affecting the
          selection.

     [6]  If any normal printing characters are typed,  they  are
          inserted at the point of the insertion cursor.

     [7]  The view in the widget can be adjusted by dragging with
          mouse  button  2.  If mouse button 2 is clicked without
          moving the mouse, the selection is copied into the text
          at  the  position  of the mouse cursor.  The Insert key
          also inserts the selection, but at the position of  the
          insertion cursor.

     [8]  If the mouse is dragged out of the widget while  button
          1  is  pressed,  the entry will automatically scroll to
          make more text visible (if  there  is  more  text  off-
          screen on the side where the mouse left the window).

     [9]  The Left and Right keys move the insertion  cursor  one
          character  to  the  left or right;  they also clear any
          selection in the text.  If Left or Right is typed  with
          the Shift key down, then the insertion cursor moves and
          the selection is extended to include the new character.
          Control-Left  and Control-Right move the insertion cur-
          sor  by  words,  and  Control-Shift-Left  and  Control-
          Shift-Right move the insertion cursor by words and also
          extend the selection.  Control-b and  Control-f  behave
          the  same  as Left and Right, respectively.  Meta-b and
          Meta-f behave the same  as  Control-Left  and  Control-
          Right, respectively.

     [10] The Up and Down keys move the insertion cursor one line
          up  or down and clear any selection in the text.  If Up
          or Right is typed with the Shift  key  down,  then  the
          insertion cursor moves and the selection is extended to
          include the new character.  Control-Up and Control-Down
          move  the  insertion  cursor  by  paragraphs (groups of
          lines separated by blank lines),  and  Control-Shift-Up
          and  Control-Shift-Down  move  the  insertion cursor by
          paragraphs and also extend  the  selection.   Control-p
          and  Control-n  behave the same as Up and Down, respec-
          tively.

     [11] The Next and Prior keys move the insertion cursor  for-
          ward  or  backwards  by  one  screenful  and  clear any
          selection in the text.  If the Shift key is  held  down
          while  Next  or  Prior  is typed, then the selection is
          extended to include the new character.  Control-v moves
          the  view  down one screenful without moving the inser-
          tion cursor or adjusting the selection.

     [12] Control-Next and Control-Prior scroll the view right or
          left by one page without moving the insertion cursor or
          affecting the selection.

     [13] Home and Control-a move the  insertion  cursor  to  the
          beginning  of  its  line and clear any selection in the
          widget.  Shift-Home moves the insertion cursor  to  the
          beginning of the line and also extends the selection to
          that point.

     [14] End and Control-e move the insertion cursor to the  end
          of  the  line  and  clear  any selection in the widget.
          Shift-End moves the cursor to the end of the  line  and
          extends the selection to that point.

     [15] Control-Home and Meta-< move the  insertion  cursor  to
          the  beginning  of  the text and clear any selection in
          the widget.   Control-Shift-Home  moves  the  insertion
          cursor  to  the  beginning of the text and also extends
          the selection to that point.

     [16] Control-End and Meta-> move the insertion cursor to the
          end  of the text and clear any selection in the widget.
          Control-Shift-End moves the cursor to the  end  of  the
          text and extends the selection to that point.

     [17] The Select key  and  Control-Space  set  the  selection
          anchor  to  the position of the insertion cursor.  They
          don't affect the current selection.   Shift-Select  and
          Control-Shift-Space adjust the selection to the current
          position of the insertion cursor,  selecting  from  the
          anchor  to  the  insertion  cursor if there was not any
          selection previously.

     [18] Control-/ selects the entire contents of the widget.

     [19] Control-\ clears any selection in the widget.

     [20] The F16 key (labelled Copy on many Sun workstations) or
          Meta-w  copies the selection in the widget to the clip-
          board, if there is a selection.

     [21] The F20 key (labelled Cut on many Sun workstations)  or
          Control-w  copies  the  selection  in the widget to the
          clipboard and deletes the selection.  If  there  is  no
          selection in the widget then these keys have no effect.

     [22] The F18 key (labelled Paste on many  Sun  workstations)
          or  Control-y  inserts the contents of the clipboard at
          the position of the insertion cursor.

     [23] The Delete key deletes the selection, if there  is  one
          in  the  widget.   If there is no selection, it deletes
          the character to the right of the insertion cursor.

     [24] Backspace and Control-h delete the selection, if  there
          is  one  in the widget.  If there is no selection, they
          delete the character to the left of the insertion  cur-
          sor.

     [25] Control-d deletes the character to  the  right  of  the
          insertion cursor.

     [26] Meta-d deletes the word to the right of  the  insertion
          cursor.

     [27] Control-k deletes from the insertion cursor to the  end
          of  its line; if the insertion cursor is already at the
          end of a line, then Control-k deletes the newline char-
          acter.

     [28] Control-o opens a new line by inserting a newline char-
          acter  in  front of the insertion cursor without moving
          the insertion cursor.

     [29] Meta-backspace and Meta-Delete delete the word  to  the
          left of the insertion cursor.

     [30] Control-x deletes whatever  is  selected  in  the  text
          widget.

     [31] Control-t reverses the order of the two  characters  to
          the right of the insertion cursor.

     If the widget is disabled using the -state option, then  its
     view  can  still be adjusted and text can still be selected,
     but no insertion cursor will be displayed and no text modif-
     ications will take place.

     The behavior of texts can be changed by defining  new  bind-
     ings for individual widgets or by redefining the class bind-
     ings.

PERFORMANCE ISSUES

     Text widgets should run efficiently under a variety of  con-
     ditions.   The  text  widget  uses  about  2-3 bytes of main
     memory for each byte of text, so texts containing a megabyte
     or  more  should be practical on most workstations.  Text is
     represented internally with a modified B-tree structure that
     makes operations relatively efficient even with large texts.
     Tags are included in the B-tree  structure  in  a  way  that
     allows  tags  to  span  large  ranges  or have many disjoint
     smaller ranges without loss of efficiency.  Marks  are  also
     implemented in a way that allows large numbers of marks.  In
     most cases it is fine to have large numbers of unique  tags,
     or a tag that has many distinct ranges.

     One performance problem can arise if you  have  hundreds  or
     thousands  of  different  tags  that  all have the following
     characteristics:  the first and last ranges of each tag  are
     near  the  beginning and end of the text, respectively, or a
     single tag range covers most of the text widget.   The  cost
     of adding and deleting tags like this is proportional to the
     number of other tags with the same properties.  In contrast,
     there  is  no problem with having thousands of distinct tags
     if their overall ranges are localized and  spread  uniformly
     throughout the text.

     Very long text lines can be expensive,  especially  if  they
     have many marks and tags within them.

     The display line with the insert cursor is redrawn each time
     the  cursor blinks, which causes a steady stream of graphics
     traffic.  Set the insertOffTime attribute to 0 avoid this.

KEYWORDS

     text, widget
itcl2.2/html/tk4.2/tk.n.html100666 1751 0 4120 6423554673 14415 0ustar kunkeewheel tk4.2 User Commands - tk

tk4.2 User Commands - tk

NAME

     tk - Manipulate Tk internal state

SYNOPSIS

     tk option ?arg arg ...?

DESCRIPTION

     The tk command provides access to miscellaneous elements  of
     Tk's internal state.  Most of the information manipulated by
     this command pertains to the application as a whole, or to a
     screen  or display, rather than to a particular window.  The
     command can take any of a number of different forms  depend-
     ing on the option argument.  The legal forms are:

     tk appname ?newName?
          If newName isn't specified, this  command  returns  the
          name  of  the application (the name that may be used in
          send commands to communicate with the application).  If
          newName  is specified, then the name of the application
          is changed to newName.  If the given name is already in
          use,  then  a  suffix of the form `` #2'' or `` #3'' is
          appended  in  order  to  make  the  name  unique.   The
          command's  result is the name actually chosen.  newName
          should not start with  a  capital  letter.   This  will
          interfere  with option processing, since names starting
          with capitals are assumed to be classes;  as a  result,
          Tk  may not be able to find some options for the appli-
          cation.  If sends have been disabled  by  deleting  the
          send  command,  this  command  will  reenable  them and
          recreate the send command.

KEYWORDS

     application name, send
itcl2.2/html/tk4.2/tk4.2API.html100666 1751 0 11062 6423554673 14762 0ustar kunkeewheel
tk4.2 C API
tk4.2 C API
itcl2.2/html/tk4.2/tkerror.n.html100666 1751 0 2112 6423554673 15466 0ustar kunkeewheel tk4.2 User Commands - tkerror

tk4.2 User Commands - tkerror

NAME

     tkerror - Command invoked to process background errors

SYNOPSIS

     tkerror message

DESCRIPTION

     Note: as of Tk 4.1 the tkerror command has been  renamed  to
     bgerror  because  the  event  loop  (which  is  what usually
     invokes it) is now part of Tcl.  The  changes  are  backward
     compatible,  so  that old uses of tkerror should still work,
     but you should modify your scripts to use bgerror instead of
     tkerror.   Documentation for bgerror is available as part of
     Tcl's documentation.

KEYWORDS

     background error, reporting
itcl2.2/html/tk4.2/tk4.2UserCmds.html100666 1751 0 6256 6423554673 16067 0ustar kunkeewheel
tk4.2 User Commands
tk4.2 User Commands
itcl2.2/html/tk4.2/tkvars.n.html100666 1751 0 10002 6423554673 15325 0ustar kunkeewheel tk4.2 User Commands - tkvars

tk4.2 User Commands - tkvars

NAME

     tkvars - Variables used or set by Tk

DESCRIPTION

     The following Tcl variables are either set or used by Tk  at
     various times in its execution:

     tk_library     This variable  holds  the  file  name  for  a
                    directory containing a library of Tcl scripts
                    related to Tk.  These scripts include an ini-
                    tialization  file  that is normally processed
                    whenever a Tk  application  starts  up,  plus
                    other files containing procedures that imple-
                    ment default behaviors for widgets.  The ini-
                    tial  value  of tcl_library is set when Tk is
                    added to an interpreter;   this  is  done  by
                    searching several different directories until
                    one is found that contains an appropriate  Tk
                    startup  script.   If the TK_LIBRARY environ-
                    ment variable exists, then the  directory  it
                    names  is checked first.  If TK_LIBRARY isn't
                    set or doesn't refer to an appropriate direc-
                    tory,  then  Tk  checks  several other direc-
                    tories based on a compiled-in  default  loca-
                    tion,  the location of the Tcl library direc-
                    tory, the location of the  binary  containing
                    the  application,  and  the  current  working
                    directory.  The variable can be  modified  by
                    an  application  to  switch  to  a  different
                    library.

     tk_patchLevel  Contains a decimal integer giving the current
                    patch  level  for  Tk.   The  patch  level is
                    incremented for each new  release  or  patch,
                    and  it  uniquely identifies an official ver-
                    sion of Tk.

     tkPriv         This variable is an array containing  several
                    pieces of information that are private to Tk.
                    The elements of tkPriv are used by Tk library
                    procedures and default bindings.  They should
                    not be accessed by any code outside Tk.

     tk_strictMotif This variable is set to zero by default.   If
                    an  application  sets  it  to  one,  then  Tk
                    attempts to adhere as closely as possible  to
                    Motif  look-and-feel standards.  For example,
                    active elements such as buttons and scrollbar
                    sliders   will  not  change  color  when  the
                    pointer passes over them.

     tk_version     Tk sets this variable in the interpreter  for
                    each  application.   The  variable  holds the
                    current version number of the Tk  library  in
                    the  form  major.minor.   Major and minor are
                    integers.  The major version number increases
                    in  any Tk release that includes changes that
                    are not backward  compatible  (i.e.  whenever
                    existing Tk applications and scripts may have
                    to change to work with the new release).  The
                    minor  version number increases with each new
                    release of Tk, except that it resets to  zero
                    whenever the major version number changes.

KEYWORDS

     variables, version
itcl2.2/html/tk4.2/tkwait.n.html100666 1751 0 4405 6423554673 15310 0ustar kunkeewheel tk4.2 User Commands - tkwait

tk4.2 User Commands - tkwait

NAME

     tkwait - Wait for variable to change or window  to  be  des-
     troyed

SYNOPSIS

     tkwait variable name

     tkwait visibility name

     tkwait window name

DESCRIPTION

     The tkwait command waits for one of several things  to  hap-
     pen,  then it returns without taking any other actions.  The
     return value is always an empty string.  If the first  argu-
     ment is variable (or any abbreviation of it) then the second
     argument is the name of a global variable  and  the  command
     waits  for that variable to be modified.  If the first argu-
     ment is visibility (or any  abbreviation  of  it)  then  the
     second  argument is the name of a window and the tkwait com-
     mand waits for a change in its visibility  state  (as  indi-
     cated  by  the  arrival  of a VisibilityNotify event).  This
     form is typically used to wait for a newly-created window to
     appear  on  the  screen  before  taking some action.  If the
     first argument is window (or any abbreviation  of  it)  then
     the  second  argument is the name of a window and the tkwait
     command waits for that window to be destroyed.  This form is
     typically used to wait for a user to finish interacting with
     a dialog box before using the result of that interaction.

     While the tkwait command is waiting it processes  events  in
     the  normal  fashion,  so  the  application will continue to
     respond to user interactions.  If an event  handler  invokes
     tkwait again, the nested call to tkwait must complete before
     the outer call can complete.

KEYWORDS

     variable, visibility, wait, window
itcl2.2/html/tk4.2/toplevel.n.html100666 1751 0 16711 6423554674 15663 0ustar kunkeewheel tk4.2 User Commands - toplevel

tk4.2 User Commands - toplevel

NAME

     toplevel - Create and manipulate toplevel widgets

SYNOPSIS

     toplevel pathName ?options?

STANDARD OPTIONS

     -borderwidth    -highlightbackground           -highlightthickness-takefocus
     -cursor         -highlightcolor                -relief

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

WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-background
     Database Name:  background
     Database Class: Background

          This option is the  same  as  the  standard  background
          option  except  that its value may also be specified as
          an empty string.  In this case, the widget will display
          no background or border, and no colors will be consumed
          from its colormap for its background and border.

     Command-Line Name:-class
     Database Name:  class
     Database Class: Class

          Specifies a class for the window.  This class  will  be
          used when querying the option database for the window's
          other options, and it will also be used later for other
          purposes such as bindings.  The class option may not be
          changed with the configure widget command.

     Command-Line Name:-colormap
     Database Name:  colormap
     Database Class: Colormap

          Specifies a colormap to use for the window.  The  value
          may  be  either  new,  in  which case a new colormap is
          created for the window and its children, or the name of
          another  window  (which  must be on the same screen and
          have the same visual as pathName), in  which  case  the
          new  window  will  use  the colormap from the specified
          window.  If the colormap option is not  specified,  the
          new  window  uses  the  default colormap of its screen.
          This option may  not  be  changed  with  the  configure
          widget command.


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

          Specifies the desired height for the window in  any  of
          the  forms  acceptable to Tk_GetPixels.  If this option
          is less than or equal to zero then the window will  not
          request any size at all.

     Command-Line Name:-screen
     Database Name:
     Database Class:

          Specifies the screen on which to place the new  window.
          Any  valid screen name may be used, even one associated
          with a different display.  Defaults to the same  screen
          as  its  parent.  This option is special in that it may
          not be specified via the option database,  and  it  may
          not be modified with the configure widget command.

     Command-Line Name:-visual
     Database Name:  visual
     Database Class: Visual

          Specifies visual information for the new window in  any
          of  the forms accepted by Tk_GetVisual.  If this option
          is not specified, the new window will use  the  default
          visual  for  its  screen.  The visual option may not be
          modified with the configure widget command.

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

          Specifies the desired width for the window  in  any  of
          the  forms  acceptable to Tk_GetPixels.  If this option
          is less than or equal to zero then the window will  not
          request any size at all.

DESCRIPTION

     The toplevel command creates a new toplevel widget (given by
     the   pathName  argument).   Additional  options,  described
     above, may be specified on the command line or in the option
     database  to  configure  aspects of the toplevel such as its
     background color and relief.  The toplevel  command  returns
     the path name of the new window.

     A toplevel is similar to a frame except that it  is  created
     as a top-level window:  its X parent is the root window of a
     screen rather than the logical parent from  its  path  name.
     The primary purpose of a toplevel is to serve as a container
     for dialog boxes and other collections of widgets.  The only
     visible  features of a toplevel are its background color and
     an optional 3-D border to make the toplevel appear raised or
     sunken.

WIDGET COMMAND

     The toplevel command creates a new Tcl command whose name is
     the  same  as  the path name of the toplevel's window.  This
     command may be used to  invoke  various  operations  on  the
     widget.  It has the following general form:
          pathName option ?arg arg ...?
     PathName is the name of the command, which is  the  same  as
     the toplevel widget's path name.  Option and the args deter-
     mine the exact behavior of the command.  The following  com-
     mands are possible for toplevel widgets:

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

BINDINGS

     When a new toplevel is created,  it  has  no  default  event
     bindings:  toplevels are not intended to be interactive.

KEYWORDS

     toplevel, widget
itcl2.2/html/tk4.2/winfo.n.html100666 1751 0 46403 6423554674 15154 0ustar kunkeewheel tk4.2 User Commands - winfo

tk4.2 User Commands - winfo

NAME

     winfo - Return window-related information

SYNOPSIS

     winfo option ?arg arg ...?

DESCRIPTION

     The winfo command is used to retrieve information about win-
     dows  managed  by  Tk.   It can take any of a number of dif-
     ferent forms, depending on the option argument.   The  legal
     forms are:

     winfo atom ?-displayof window? name
          Returns a decimal string giving the integer  identifier
          for  the  atom  whose  name is name.  If no atom exists
          with the name name then a new one is created.  If the -
          displayof option is given then the atom is looked up on
          the display of window;  otherwise it is  looked  up  on
          the display of the application's main window.

     winfo atomname ?-displayof window? id
          Returns the textual name for  the  atom  whose  integer
          identifier  is  id.   If the -displayof option is given
          then the identifier is looked up on the display of win-
          dow;   otherwise  it is looked up on the display of the
          application's main window.  This command is the inverse
          of the winfo atom command.  It generates an error if no
          such atom exists.

     winfo cells window
          Returns a decimal string giving the number of cells  in
          the color map for window.

     winfo children window
          Returns a list containing the path  names  of  all  the
          children  of window.  Top-level windows are returned as
          children of their logical parents.

     winfo class window
          Returns the class name for window.

     winfo colormapfull window
          Returns 1 if the colormap for window  is  known  to  be
          full,  0  otherwise.   The  colormap  for  a  window is
          ``known'' to be full if the last attempt to allocate  a
          new  color  on  that window failed and this application
          hasn't freed any  colors  in  the  colormap  since  the
          failed allocation.

     winfo command window
          Returns the  fully-qualified  access  command  for  the  |
          widget  window.   Unless  the command has been renamed,  |
          this is the same as the window name, but  with  leading  |
          namespace  qualifiers.  The fully-qualified access com-  |
          mand should be used instead of  the  window  name  when  |
          accessing widgets.

     winfo containing ?-displayof window? rootX rootY
          Returns the path name for  the  window  containing  the
          point  given  by  rootX and rootY.  RootX and rootY are
          specified in screen units (i.e.  any form acceptable to
          Tk_GetPixels) in the coordinate system of the root win-
          dow (if a virtual-root window manager is  in  use  then
          the  coordinate  system  of  the virtual root window is
          used).  If the -displayof  option  is  given  then  the
          coordinates  refer  to  the  screen  containing window;
          otherwise they refer to the screen of the application's
          main window.  If no window in this application contains
          the point then an empty string is returned.  In select-
          ing  the  containing  window, children are given higher
          priority than parents and among  siblings  the  highest
          one in the stacking order is chosen.

     winfo depth window
          Returns a decimal string giving  the  depth  of  window
          (number of bits per pixel).

     winfo exists window
          Returns 1 if there exists a window named window,  0  if
          no such window exists.

     winfo fpixels window number
          Returns a floating-point value  giving  the  number  of
          pixels in window corresponding to the distance given by
          number.  Number may be specified in any  of  the  forms
          acceptable  to  Tk_GetScreenMM,  such  as  ``2.0c''  or
          ``1i''.  The return value may be  fractional;   for  an
          integer value, use winfo pixels.

     winfo geometry window
          Returns  the  geometry  for   window,   in   the   form
          widthxheight+x+y.  All dimensions are in pixels.

     winfo height window
          Returns a decimal string giving window's height in pix-
          els.  When a window is first created its height will be
          1 pixel;  the height will eventually be  changed  by  a
          geometry manager to fulfill the window's needs.  If you
          need the  true  height  immediately  after  creating  a
          widget,  invoke update to force the geometry manager to
          arrange it, or use winfo reqheight to get the  window's
          requested height instead of its actual height.

     winfo id window
          Returns a hexadecimal string indicating the X  identif-
          ier for window.

     winfo interps ?-displayof window?
          Returns a list whose members are the names of  all  Tcl
          interpreters (e.g. all Tk-based applications) currently
          registered for a particular display.  If the -displayof
          option  is  given  then  the return value refers to the
          display of window;  otherwise it refers to the  display
          of the application's main window.

     winfo ismapped window
          Returns 1 if window is currently mapped, 0 otherwise.

     winfo manager window
          Returns the name  of  the  geometry  manager  currently
          responsible  for  window,  or an empty string if window
          isn't managed by any geometry  manager.   The  name  is
          usually  the  name  of the Tcl command for the geometry
          manager, such  as  pack  or  place.   If  the  geometry
          manager is a widget, such as canvases or text, the name
          is the widget's class command, such as canvas.

     winfo megawidget window
          Returns the window path name for the  mega-widget  con-  |
          taining  the  component  window,  or the null string if  |
          window is not a mega-widget component.  For  this  com-  |
          mand to work properly, mega-widget packages must regis-  |
          ter    their    components    via     the     procedure  |
          Itk_SetMegaWidget().

     winfo name window
          Returns window's name (i.e. its name within its parent,
          as  opposed  to its full path name).  The command winfo
          name . will return the name of the application.

     winfo parent window
          Returns the path name of window's parent, or  an  empty
          string if window is the main window of the application.

     winfo pathname ?-displayof window? id
          Returns the path name of the window whose X  identifier
          is  id.   Id  must  be a decimal, hexadecimal, or octal
          integer and must correspond to a window in the invoking
          application.   If  the  -displayof option is given then
          the identifier is looked up on the display  of  window;
          otherwise  it  is  looked  up  on  the  display  of the
          application's main window.

     winfo pixels window number
          Returns the number of pixels in window corresponding to
          the  distance given by number.  Number may be specified
          in any of the forms acceptable to Tk_GetPixels, such as
          ``2.0c''  or  ``1i''.   The  result  is  rounded to the
          nearest integer value;  for a  fractional  result,  use
          winfo fpixels.

     winfo pointerx window
          If the mouse pointer is on the same screen  as  window,
          returns  the pointer's x coordinate, measured in pixels
          in the screen's root window.  If a virtual root  window
          is  in  use  on the screen, the position is measured in
          the virtual root.  If the mouse pointer  isn't  on  the
          same screen as window then -1 is returned.

     winfo pointerxy window
          If the mouse pointer is on the same screen  as  window,
          returns  a  list  with  two  elements,  which  are  the
          pointer's x and y coordinates measured in pixels in the
          screen's  root  window.  If a virtual root window is in
          use on the screen, the position is computed in the vir-
          tual  root.   If  the  mouse  pointer isn't on the same
          screen as window then both of the returned  coordinates
          are -1.

     winfo pointery window
          If the mouse pointer is on the same screen  as  window,
          returns  the pointer's y coordinate, measured in pixels
          in the screen's root window.  If a virtual root  window
          is  in  use  on the screen, the position is computed in
          the virtual root.  If the mouse pointer  isn't  on  the
          same screen as window then -1 is returned.

     winfo reqheight window
          Returns a  decimal  string  giving  window's  requested
          height,  in pixels.  This is the value used by window's
          geometry manager to compute its geometry.

     winfo reqwidth window
          Returns a  decimal  string  giving  window's  requested
          width,  in  pixels.  This is the value used by window's
          geometry manager to compute its geometry.

     winfo rgb window color
          Returns a list containing three decimal  values,  which
          are   the   red,   green,  and  blue  intensities  that
          correspond to color in  the  window  given  by  window.
          Color  may  be specified in any of the forms acceptable
          for a color option.

     winfo rootx window
          Returns a decimal string giving  the  x-coordinate,  in
          the root window of the screen, of the upper-left corner
          of window's border (or window if it has no border).

     winfo rooty window
          Returns a decimal string giving  the  y-coordinate,  in
          the root window of the screen, of the upper-left corner
          of window's border (or window if it has no border).

     winfo screen window
          Returns the name of the screen associated with  window,
          in the form displayName.screenIndex.

     winfo screencells window
          Returns a decimal string giving the number of cells  in
          the default color map for window's screen.

     winfo screendepth window
          Returns a decimal string giving the depth of  the  root
          window of window's screen (number of bits per pixel).

     winfo screenheight window
          Returns a decimal string giving the height of  window's
          screen, in pixels.

     winfo screenmmheight window
          Returns a decimal string giving the height of  window's
          screen, in millimeters.

     winfo screenmmwidth window
          Returns a decimal string giving the width  of  window's
          screen, in millimeters.

     winfo screenvisual window
          Returns one of the following strings  to  indicate  the
          default  visual class for window's screen: directcolor,
          grayscale,  pseudocolor,  staticcolor,  staticgray,  or
          truecolor.

     winfo screenwidth window
          Returns a decimal string giving the width  of  window's
          screen, in pixels.

     winfo server window
          Returns  a  string  containing  information  about  the
          server  for window's display.  The exact format of this
          string may vary  from  platform  to  platform.   For  X
          servers  the  string has the form ``XmajorRminor vendor
          vendorVersion'' where major and minor are  the  version
          and  revision  numbers  provided  by  the server (e.g.,
          X11R5), vendor is  the  name  of  the  vendor  for  the
          server,  and vendorRelease is an integer release number
          provided by the server.

     winfo toplevel window
          Returns the path name of the top-level window  contain-
          ing window.

     winfo viewable window
          Returns 1 if window and all of its ancestors up through
          the  nearest  toplevel window are mapped.  Returns 0 if
          any of these windows are not mapped.

     winfo visual window
          Returns one of the following strings  to  indicate  the
          visual  class for window: directcolor, grayscale, pseu-
          docolor, staticcolor, staticgray, or truecolor.

     winfo visualid window
          Returns the X identifier for the visual for window.

     winfo visualsavailable window ?includeids?
          Returns a list  whose  elements  describe  the  visuals
          available  for  window's screen.  Each element consists
          of a visual class followed by an  integer  depth.   The
          class  has  the  same form as returned by winfo visual.
          The depth gives the number of bits  per  pixel  in  the
          visual.   In  addition,  if  the includeids argument is
          provided, then the depth is followed by the X  identif-
          ier for the visual.

     winfo vrootheight window
          Returns the height of the virtual root  window  associ-
          ated  with  window  if there is one;  otherwise returns
          the height of window's screen.

     winfo vrootwidth window
          Returns the width of the virtual root window associated
          with  window  if  there  is one;  otherwise returns the
          width of window's screen.

     winfo vrootx window
          Returns the x-offset of the virtual root window associ-
          ated  with  window,  relative to the root window of its
          screen.  This is  normally  either  zero  or  negative.
          Returns  0  if there is no virtual root window for win-
          dow.

     winfo vrooty window
          Returns the y-offset of the virtual root window associ-
          ated  with  window,  relative to the root window of its
          screen.  This is  normally  either  zero  or  negative.
          Returns  0  if there is no virtual root window for win-
          dow.

     winfo width window
          Returns a decimal string giving window's width in  pix-
          els.   When a window is first created its width will be
          1 pixel;  the width will eventually  be  changed  by  a
          geometry manager to fulfill the window's needs.  If you
          need  the  true  width  immediately  after  creating  a
          widget,  invoke update to force the geometry manager to
          arrange it, or use winfo reqwidth to get  the  window's
          requested width instead of its actual width.

     winfo x window
          Returns a decimal string giving  the  x-coordinate,  in
          window's  parent,  of the upper-left corner of window's
          border (or window if it has no border).

     winfo y window
          Returns a decimal string giving  the  y-coordinate,  in
          window's  parent,  of the upper-left corner of window's
          border (or window if it has no border).

KEYWORDS

     atom, children, class, geometry, height, identifier,  infor-
     mation,  interpreters,  mapped,  parent,  path name, screen,
     virtual root, width, window
itcl2.2/html/tk4.2/wm.n.html100666 1751 0 103404 6423554674 14470 0ustar kunkeewheel tk4.2 User Commands - wm

tk4.2 User Commands - wm

NAME

     wm - Communicate with window manager

SYNOPSIS

     wm option window ?args?

DESCRIPTION

     The wm command is used to interact with window  managers  in
     order  to control such things as the title for a window, its
     geometry, or the increments in terms  of  which  it  may  be
     resized.   The  wm  command can take any of a number of dif-
     ferent forms, depending on the option argument.  All of  the
     forms expect at least one additional argument, window, which
     must be the path name of a top-level window.

     The legal forms for the wm command are:

     wm aspect window ?minNumer minDenom maxNumer maxDenom?
          If minNumer, minDenom, maxNumer, and maxDenom  are  all
          specified,  then  they  will  be  passed  to the window
          manager and the  window  manager  should  use  them  to
          enforce a range of acceptable aspect ratios for window.
          The aspect ratio of window (width/length) will be  con-
          strained   to   lie   between   minNumer/minDenom   and
          maxNumer/maxDenom.  If minNumer etc. are all  specified
          as  empty  strings, then any existing aspect ratio res-
          trictions are removed.  If minNumer etc. are specified,
          then  the  command returns an empty string.  Otherwise,
          it returns a Tcl list containing four  elements,  which
          are the current values of minNumer, minDenom, maxNumer,
          and maxDenom (if no aspect restrictions are in  effect,
          then an empty string is returned).

     wm client window ?name?
          If name is specified, this command stores  name  (which
          should be the name of the host on which the application
          is executing) in  window's  WM_CLIENT_MACHINE  property
          for  use by the window manager or session manager.  The
          command returns an empty string in this case.  If  name
          isn't  specified, the command returns the last name set
          in a wm client command for window.  If name  is  speci-
          fied  as  an  empty  string,  the  command  deletes the
          WM_CLIENT_MACHINE property from window.

     wm colormapwindows window ?windowList?
          This   command    is    used    to    manipulate    the
          WM_COLORMAP_WINDOWS  property,  which provides informa-
          tion to the window managers  about  windows  that  have
          private  colormaps.  If windowList isn't specified, the
          command returns a list whose elements are the names  of
          the  windows  in  the WM_COLORMAP_WINDOWS property.  If
          windowList is specified, it consists of a list of  win-
          dow   path   names;    the   command   overwrites   the
          WM_COLORMAP_WINDOWS property with the given windows and
          returns  an empty string.  The WM_COLORMAP_WINDOWS pro-
          perty should normally contain a list  of  the  internal
          windows within window whose colormaps differ from their
          parents.  The order of  the  windows  in  the  property
          indicates  a  priority  order:  the window manager will
          attempt to install as many colormaps as  possible  from
          the  head  of  this  list when window gets the colormap
          focus.  If window is not included among the windows  in
          windowList,  Tk  implicitly  adds  it at the end of the
          WM_COLORMAP_WINDOWS property, so that its  colormap  is
          lowest  in  priority.   If  wm  colormapwindows  is not
          invoked, Tk will automatically  set  the  property  for
          each top-level window to all the internal windows whose
          colormaps differ from their parents,  followed  by  the
          top-level itself;  the order of the internal windows is
          undefined.  See the ICCCM documentation for more infor-
          mation on the WM_COLORMAP_WINDOWS property.

     wm command window ?value?
          If value is specified, this  command  stores  value  in
          window's  WM_COMMAND  property  for  use  by the window
          manager or session manager and returns an empty string.
          Value  must  have  proper list structure;  the elements
          should contain the words of the command used to  invoke
          the  application.   If  value  isn't specified then the
          command returns the last value set in a wm command com-
          mand  for  window.   If  value is specified as an empty
          string, the command  deletes  the  WM_COMMAND  property
          from window.

     wm deiconify window
          Arrange for window to  be  displayed  in  normal  (non-
          iconified)  form.   This is done by mapping the window.
          If the window has never been mapped then  this  command
          will  not  map the window, but it will ensure that when
          the window is first mapped it will be displayed in  de-
          iconified form.  Returns an empty string.

     wm focusmodel window ?active|passive?
          If active or passive is supplied as an  optional  argu-
          ment  to the command, then it specifies the focus model
          for window.  In this case the command returns an  empty
          string.   If  no  additional argument is supplied, then
          the command returns the current focus model for window.
          An  active focus model means that window will claim the
          input focus for itself  or  its  descendants,  even  at
          times  when the focus is currently in some other appli-
          cation.  Passive means that window will never claim the
          focus  for  itself:  the window manager should give the
          focus to window at appropriate  times.   However,  once
          the  focus  has been given to window or one of its des-
          cendants, the application may re-assign the focus among
          window's descendants.  The focus model defaults to pas-
          sive, and Tk's focus command assumes a passive model of
          focusing.

     wm frame window
          If window has been reparented  by  the  window  manager
          into a decorative frame, the command returns the X win-
          dow identifier for the outermost  frame  that  contains
          window  (the window whose parent is the root or virtual
          root).  If window hasn't been reparented by the  window
          manager  then the command returns the X window identif-
          ier for window.

     wm geometry window ?newGeometry?
          If newGeometry is specified, then the geometry of  win-
          dow is changed and an empty string is returned.  Other-
          wise the current geometry for window is returned  (this
          is  the most recent geometry specified either by manual
          resizing or in a wm geometry command).  NewGeometry has
          the  form  =widthxheight _ x_y, where any of =, widthx-
          height, or _x_y may be omitted.  Width and  height  are
          positive  integers specifying the desired dimensions of
          window.  If window is  gridded  (see  GRIDDED  GEOMETRY
          MANAGEMENT  below) then the dimensions are specified in
          grid units;  otherwise  they  are  specified  in  pixel
          units.   X and y specify the desired location of window
          on the screen, in pixels.  If x is preceded  by  +,  it
          specifies the number of pixels between the left edge of
          the screen and the left edge of  window's  border;   if
          preceded  by  -  then  x specifies the number of pixels
          between the right edge of the screen and the right edge
          of  window's  border.   If  y  is preceded by + then it
          specifies the number of pixels between the top  of  the
          screen  and  the  top of window's border;  if y is pre-
          ceded by - then  it  specifies  the  number  of  pixels
          between the bottom of window's border and the bottom of
          the screen.  If newGeometry is specified  as  an  empty
          string  then  any  existing user-specified geometry for
          window is cancelled, and the window will revert to  the
          size requested internally by its widgets.

     wm grid window ?baseWidth baseHeight widthInc heightInc?
          This command indicates that window is to be managed  as
          a  gridded  window.  It also specifies the relationship
          between grid units  and  pixel  units.   BaseWidth  and
          baseHeight   specify   the   number   of   grid   units
          corresponding to the pixel dimensions requested  inter-
          nally by window using Tk_GeometryRequest.  WidthInc and
          heightInc specify the number of pixels in each horizon-
          tal  and  vertical grid unit.  These four values deter-
          mine  a  range  of   acceptable   sizes   for   window,
          corresponding to grid-based widths and heights that are
          non-negative integers.  Tk will pass  this  information
          to  the  window  manager;   during manual resizing, the
          window manager will restrict the window's size  to  one
          of  these acceptable sizes.  Furthermore, during manual
          resizing the window manager will display  the  window's
          current size in terms of grid units rather than pixels.
          If baseWidth etc. are all specified as  empty  strings,
          then window will no longer be managed as a gridded win-
          dow.  If baseWidth etc. are specified then  the  return
          value  is  an empty string.  Otherwise the return value
          is a Tcl list containing four elements corresponding to
          the   current   baseWidth,  baseHeight,  widthInc,  and
          heightInc;  if window is not currently gridded, then an
          empty  string  is  returned.  Note: this command should
          not be needed very often, since the Tk_SetGrid  library
          procedure  and the setGrid option provide easier access
          to the same functionality.

     wm group window ?pathName?
          If pathName is specified, it gives the  path  name  for
          the  leader  of a group of related windows.  The window
          manager may use this information, for example, to unmap
          all  of  the windows in a group when the group's leader
          is iconified.  PathName may be specified  as  an  empty
          string to remove window from any group association.  If
          pathName is specified then the command returns an empty
          string;  otherwise it returns the path name of window's
          current group leader, or  an  empty  string  if  window
          isn't part of any group.

     wm iconbitmap window ?bitmap?
          If bitmap is specified, then it names a bitmap  in  the
          standard  forms  accepted  by  Tk (see the Tk_GetBitmap
          manual entry for details).  This bitmap  is  passed  to
          the  window  manager  to be displayed in window's icon,
          and the command returns an empty string.  If  an  empty
          string  is  specified for bitmap, then any current icon
          bitmap is cancelled for window.  If bitmap is specified
          then the command returns an empty string.  Otherwise it
          returns the name of the current icon bitmap  associated
          with  window,  or an empty string if window has no icon
          bitmap.

     wm iconify window
          Arrange for window to be iconified.  It  window  hasn't
          yet  been  mapped for the first time, this command will
          arrange for it to appear in the iconified state when it
          is eventually mapped.

     wm iconmask window ?bitmap?
          If bitmap is specified, then it names a bitmap  in  the
          standard  forms  accepted  by  Tk (see the Tk_GetBitmap
          manual entry for details).  This bitmap  is  passed  to
          the  window manager to be used as a mask in conjunction
          with the iconbitmap option:  where the mask has  zeroes
          no icon will be displayed;  where it has ones, the bits
          from the icon bitmap will be displayed.   If  an  empty
          string  is  specified  for bitmap then any current icon
          mask is cancelled for window  (this  is  equivalent  to
          specifying  a bitmap of all ones).  If bitmap is speci-
          fied then the command returns an empty string.   Other-
          wise it returns the name of the current icon mask asso-
          ciated with window, or an empty string if no mask is in
          effect.

     wm iconname window ?newName?
          If newName is specified, then it is passed to the  win-
          dow manager;  the window manager should display newName
          inside the icon associated with window.  In  this  case
          an  empty  string  is  returned  as result.  If newName
          isn't specified then the command  returns  the  current
          icon  name  for  window,  or an empty string if no icon
          name has  been  specified  (in  this  case  the  window
          manager  will  normally  display the window's title, as
          specified with the wm title command).

     wm iconposition window ?x y?
          If x and y are specified, they are passed to the window
          manager  as a hint about where to position the icon for
          window.  In this case an empty string is returned.   If
          x  and y are specified as empty strings then any exist-
          ing icon position hint is cancelled.  If neither x  nor
          y  is  specified,  then  the command returns a Tcl list
          containing two values, which are the current icon posi-
          tion  hints  (if  no  hints are in effect then an empty
          string is returned).

     wm iconwindow window ?pathName?
          If pathName is specified, it is the  path  name  for  a
          window to use as icon for window: when window is iconi-
          fied then pathName will be mapped to serve as icon, and
          when  window  is  de-iconified  then  pathName  will be
          unmapped again.  If pathName is specified as  an  empty
          string  then  any  existing icon window association for
          window will be cancelled.  If the pathName argument  is
          specified  then an empty string is returned.  Otherwise
          the command returns the path name of the  current  icon
          window  for  window,  or an empty string if there is no
          icon window currently  specified  for  window.   Button
          press  events  are disabled for window as long as it is
          an icon window;  this is needed in order to allow  win-
          dow  managers  to  ``own'' those events.  Note: not all
          window managers support the notion of an icon window.

     wm maxsize window ?width height?
          If width and height are specified, they give  the  max-
          imum  permissible  dimensions  for window.  For gridded
          windows the dimensions are  specified  in  grid  units;
          otherwise  they are specified in pixel units.  The win-
          dow manager will restrict the window's dimensions to be
          less  than  or equal to width and height.  If width and
          height are specified, then the command returns an empty
          string.   Otherwise it returns a Tcl list with two ele-
          ments, which are the maximum width and height currently
          in  effect.   The  maximum size defaults to the size of
          the screen.  If resizing has been disabled with the  wm
          resizable  command,  then  this  command has no effect.
          See the sections on geometry management below for  more
          information.

     wm minsize window ?width height?
          If width  and  height  are  specified,  they  give  the
          minimum permissible dimensions for window.  For gridded
          windows the dimensions are  specified  in  grid  units;
          otherwise  they are specified in pixel units.  The win-
          dow manager will restrict the window's dimensions to be
          greater  than  or  equal to width and height.  If width
          and height are specified, then the command  returns  an
          empty string.  Otherwise it returns a Tcl list with two
          elements,  which  are  the  minimum  width  and  height
          currently  in effect.  The minimum size defaults to one
          pixel in each dimension.  If resizing has been disabled
          with the wm resizable command, then this command has no
          effect.  See the sections on geometry management  below
          for more information.

     wm overrideredirect window ?boolean?
          If boolean is specified, it must have a proper  boolean
          form  and  the override-redirect flag for window is set
          to that value.  If boolean is not specified then 1 or 0
          is  returned  to  indicate whether or not the override-
          redirect flag is currently set for window.  Setting the
          override-redirect  flag  for  a  window causes it to be
          ignored by the window  manager;   among  other  things,
          this  means that the window will not be reparented from
          the root window into a decorative frame  and  the  user
          will  not  be  able  to manipulate the window using the
          normal window manager mechanisms.

     wm positionfrom window ?who?
          If who is specified, it must be either program or user,
          or  an  abbreviation of one of these two.  It indicates
          whether window's current position was requested by  the
          program  or  by  the user.  Many window managers ignore
          program-requested initial positions and ask the user to
          manually  position  the  window;   if user is specified
          then the window manager should position the  window  at
          the given place without asking the user for assistance.
          If who is  specified  as  an  empty  string,  then  the
          current position source is cancelled.  If who is speci-
          fied, then the command returns an empty string.  Other-
          wise  it  returns user or window to indicate the source
          of the window's current position, or an empty string if
          no source has been specified yet.  Most window managers
          interpret ``no source'' as equivalent to  program.   Tk
          will automatically set the position source to user when
          a wm geometry command is invoked, unless the source has
          been set explicitly to program.

     wm protocol window ?name? ?command?
          This command is used to manage window manager protocols
          such  as WM_DELETE_WINDOW.  Name is the name of an atom
          corresponding to a window  manager  protocol,  such  as
          WM_DELETE_WINDOW  or WM_SAVE_YOURSELF or WM_TAKE_FOCUS.
          If both name and command are specified, then command is
          associated  with  the protocol specified by name.  Name
          will be added to window's WM_PROTOCOLS property to tell
          the  window manager that the application has a protocol
          handler for name, and command will be  invoked  in  the
          future  whenever  the window manager sends a message to
          the client for that protocol.  In this case the command
          returns an empty string.  If name is specified but com-
          mand isn't,  then  the  current  command  for  name  is
          returned,  or  an  empty  string if there is no handler
          defined for name.  If command is specified as an  empty
          string then the current handler for name is deleted and
          it is removed from the WM_PROTOCOLS property on window;
          an  empty  string is returned.  Lastly, if neither name
          nor command is specified, the command returns a list of
          all  the  protocols  for  which  handlers are currently
          defined for window.

          Tk   always   defines   a    protocol    handler    for
          WM_DELETE_WINDOW,  even  if  you  haven't asked for one
          with  wm  protocol.   If  a  WM_DELETE_WINDOW   message
          arrives  when  you  haven't  defined a handler, then Tk
          handles the message by destroying the window for  which
          it was received.

     wm resizable window ?width height?
          This command controls  whether  or  not  the  user  may
          interactively  resize a top-level window.  If width and
          height are specified,  they  are  boolean  values  that
          determine whether the width and height of window may be
          modified by the user.  In this case the command returns
          an  empty string.  If width and height are omitted then
          the command returns a list with two 0/1  elements  that
          indicate  whether  the  width  and height of window are
          currently resizable.  By default, windows are resizable
          in  both dimensions.  If resizing is disabled, then the
          window's size will be the size  from  the  most  recent
          interactive  resize  or  wm geometry command.  If there
          has been no such operation then  the  window's  natural
          size will be used.

     wm sizefrom window ?who?
          If who is specified, it must be either program or user,
          or  an  abbreviation of one of these two.  It indicates
          whether window's current size was requested by the pro-
          gram  or  by  the  user.   Some  window managers ignore
          program-requested sizes and ask the  user  to  manually
          size  the window;  if user is specified then the window
          manager should  give  the  window  its  specified  size
          without  asking  the  user  for  assistance.  If who is
          specified as an empty string,  then  the  current  size
          source  is  cancelled.   If  who is specified, then the
          command returns an empty string.  Otherwise it  returns
          user  or  window to indicate the source of the window's
          current size, or an empty string if no source has  been
          specified  yet.   Most  window  managers interpret ``no
          source'' as equivalent to program.

     wm state window
          Returns the current state of  window:   either  normal,
          iconic,  withdrawn,  or  icon.   The difference between
          iconic and icon is that iconic refers to a window  that
          has  been iconified (e.g., with the wm iconify command)
          while icon refers to a window whose only purpose is  to
          serve  as  the  icon  for some other window (via the wm
          iconwindow command).

     wm title window ?string?
          If string is specified, then it will be passed  to  the
          window  manager  for  use  as the title for window (the
          window manager should display this string  in  window's
          title  bar).  In this case the command returns an empty
          string.  If string isn't  specified  then  the  command
          returns  the  current  title for the window.  The title
          for a window defaults to its name.

     wm transient window ?master?
          If master is specified,  then  the  window  manager  is
          informed  that window is a transient window (e.g. pull-
          down menu) working on behalf of master (where master is
          the  path  name  for  a top-level window).  Some window
          managers will use this  information  to  manage  window
          specially.   If  master is specified as an empty string
          then window is marked as not being a  transient  window
          any  more.   If  master  is specified, then the command
          returns an empty string.  Otherwise the command returns
          the  path  name of window's current master, or an empty
          string if window isn't currently a transient window.

     wm withdraw window
          Arranges for window to be withdrawn  from  the  screen.
          This  causes  the  window  to be unmapped and forgotten
          about by the window manager.  If the window  has  never
          been  mapped, then this command causes the window to be
          mapped in the withdrawn state.  Not all window managers
          appear to know how to handle windows that are mapped in
          the withdrawn state.  Note: it sometimes  seems  to  be
          necessary to withdraw a window and then re-map it (e.g.
          with wm deiconify) to get some window managers  to  pay
          attention  to  changes  in  window  attributes  such as
          group.

GEOMETRY MANAGEMENT

     By default a top-level window appears on the screen  in  its
     natural  size, which is the one determined internally by its
     widgets and geometry managers.  If the  natural  size  of  a
     top-level  window changes, then the window's size changes to
     match.  A top-level window can be given a  size  other  than
     its  natural  size  in two ways.  First, the user can resize
     the window manually  using  the  facilities  of  the  window
     manager,  such  as  resize handles.  Second, the application
     can request a particular size for a top-level  window  using
     the wm geometry command.  These two cases are handled ident-
     ically by Tk;  in either case, the requested size  overrides
     the  natural size.  You can return the window to its natural
     by invoking wm geometry with an empty geometry string.

     Normally a top-level window can have any size from one pixel
     in  each  dimension  up to the size of its screen.  However,
     you can use the wm minsize and wm maxsize commands to  limit
     the  range  of allowable sizes.  The range set by wm minsize
     and wm maxsize applies to all forms of  resizing,  including
     the  window's natural size as well as manual resizes and the
     wm geometry command.  You can also use the command wm resiz-
     able  to  completely  disable interactive resizing in one or
     both dimensions.

GRIDDED GEOMETRY MANAGEMENT

     Gridded geometry management occurs when one of  the  widgets
     of  an  application  supports a range of useful sizes.  This
     occurs, for example, in a text editor where the  scrollbars,
     menus,  and  other adornments are fixed in size but the edit
     widget can support any number of lines of text or characters
     per  line.  In this case, it is usually desirable to let the
     user specify the number  of  lines  or  characters-per-line,
     either  with  the  wm  geometry  command or by interactively
     resizing the window.  In the case  of  text,  and  in  other
     interesting  cases  also,  only discrete sizes of the window
     make  sense,  such  as  integral  numbers   of   lines   and
     characters-per-line;  arbitrary pixel sizes are not useful.

     Gridded geometry management provides support for  this  kind
     of  application.   Tk  (and  the window manager) assume that
     there is a grid of some sort within the application and that
     the  application  should  be  resized in terms of grid units
     rather than pixels.  Gridded geometry  management  is  typi-
     cally invoked by turning on the setGrid option for a widget;
     it can also be invoked with the wm grid command or  by  cal-
     ling Tk_SetGrid.  In each of these approaches the particular
     widget (or sometimes code in the  application  as  a  whole)
     specifies  the  relationship between integral grid sizes for
     the window  and  pixel  sizes.   To  return  to  non-gridded
     geometry  management,  invoke  wm  grid  with empty argument
     strings.

     When gridded geometry management is  enabled  then  all  the
     dimensions  specified  in  wm  minsize,  wm  maxsize, and wm
     geometry commands are treated  as  grid  units  rather  than
     pixel  units.   Interactive  resizing is also carried out in
     even numbers of grid units rather than pixels.

BUGS

     Most existing window  managers  appear  to  have  bugs  that
     affect  the  operation of the wm command.  For example, some
     changes won't take effect if the window is  already  active:
     the  window  will  have  to be withdrawn and de-iconified in
     order to make the change happen.

KEYWORDS

     aspect ratio, deiconify, focus model, geometry, grid, group,
     icon,  iconify, increments, position, size, title, top-level
     window, units, window manager
itcl2.2/itcl/ 40755 1751 0 0 6423554706 11701 5ustar kunkeewheelitcl2.2/itcl/CVS/ 40755 1751 0 0 6423570013 12321 5ustar kunkeewheelitcl2.2/itcl/CVS/Root100644 1751 0 26 6423554674 13241 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/itcl/CVS/Repository100644 1751 0 11 6423674264 14465 0ustar kunkeewheel/usr/cvs itcl2.2/itcl/CVS/Entries100644 1751 0 62 6423570013 13710 0ustar kunkeewheel/license.terms/1.1.1.1/Thu Oct 23 04:59:40 1997// itcl2.2/itcl/doc/ 40755 1751 0 0 6423554676 12454 5ustar kunkeewheelitcl2.2/itcl/doc/CVS/ 40755 1751 0 0 6423570014 13067 5ustar kunkeewheelitcl2.2/itcl/doc/CVS/Root100644 1751 0 26 6423554675 14007 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/itcl/doc/CVS/Repository100644 1751 0 11 6423674264 15232 0ustar kunkeewheel/usr/cvs itcl2.2/itcl/doc/CVS/Entries100644 1751 0 1125 6423570013 14516 0ustar kunkeewheel/body.n/1.1.1.1/Thu Oct 23 04:59:41 1997// /class.n/1.1.1.1/Thu Oct 23 04:59:41 1997// /configbody.n/1.1.1.1/Thu Oct 23 04:59:41 1997// /delete.n/1.1.1.1/Thu Oct 23 04:59:41 1997// /info.n/1.1.1.1/Thu Oct 23 04:59:41 1997// /itcl.n/1.1.1.1/Thu Oct 23 04:59:41 1997// /itcl_class.n/1.1.1.1/Thu Oct 23 04:59:41 1997// /itcl_info.n/1.1.1.1/Thu Oct 23 04:59:41 1997// /itclsh.1/1.1.1.1/Thu Oct 23 04:59:41 1997// /itclvars.n/1.1.1.1/Thu Oct 23 04:59:41 1997// /license.terms/1.1.1.1/Thu Oct 23 04:59:41 1997// /local.n/1.1.1.1/Thu Oct 23 04:59:41 1997// /man.macros/1.1.1.1/Thu Oct 23 04:59:42 1997// itcl2.2/itcl/doc/class.n100666 1751 0 50043 6423554675 14062 0ustar kunkeewheel'\" '\" Copyright (c) 1996 Lucent Technologies '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" $Id: class.n,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ '\" .so man.macros '\" # CS - begin display of code example .de CS .in +0.4i .nf \fC .. '\" # CE - end display of code example .de CE \fP .fi .in -0.4i .. .TH class n "" itcl "[incr\ Tcl]" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME class \- create a class of objects .SH SYNOPSIS \fBclass \fIclassName\fR \fB{ .br \fBinherit \fIbaseClass\fR ?\fIbaseClass\fR...? .br \fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR .br \fBdestructor \fIbody\fR .br \fBmethod \fIname\fR ?\fIargs\fR? ?\fIbody\fR? .br \fBproc \fIname ?\fIargs\fR? ?\fIbody\fR? .br \fBvariable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR? .br \fBcommon \fIvarName\fR ?\fIinit\fR? .sp \fBpublic \fIcommand\fR ?\fIarg arg ...\fR? .br \fBprotected \fIcommand\fR ?\fIarg arg ...\fR? .br \fBprivate \fIcommand\fR ?\fIarg arg ...\fR? .sp \fBset \fIvarName\fR ?\fIvalue\fR? .br \fBarray \fIoption\fR ?\fIarg arg ...\fR? .br \fB}\fR .sp \fIclassName objName\fR ?\fIarg arg ...\fR? .sp \fIobjName method\fR ?\fIarg arg ...\fR? .sp \fIclassName::proc ?\fIarg arg ...\fR? .BE .SH DESCRIPTION .PP The fundamental construct in \fB[incr\ Tcl]\fR is the class definition. Each class acts as a template for actual objects that can be created. The class itself is a namespace which contains things common to all objects. Each object has its own unique bundle of data which contains instances of the "variables" 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. .PP Two types of functions can be included in the class definition. "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. .PP If the body of any method or proc starts with "\fB@\fR", 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. .PP 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 \fBbody\fR and \fBconfigbody\fR commands for details. .PP Each namespace can have its own collection of objects and classes. The list of classes available in the current context can be queried using the "\fBinfo classes\fR" command, and the list of objects, with the "\fBinfo objects\fR" command. .PP A class can be deleted using the "\fBdelete class\fR" command. Individual objects can be deleted using the "\fBdelete object\fR" command. .SH CLASS DEFINITIONS .TP \fBclass \fIclassName definition\fR Provides the definition for a class named \fIclassName\fR. If the class \fIclassName\fR already exists, or if a command called \fIclassName\fR exists in the current namespace context, this command returns an error. If the class definition is successfully parsed, \fIclassName\fR becomes a command in the current context, handling the creation of objects for this class. .PP The class \fIdefinition\fR is evaluated as a series of Tcl statements that define elements within the class. The following class definition commands are recognized: .RS .TP \fBinherit \fIbaseClass\fR ?\fIbaseClass\fR...? Causes the current class to inherit characteristics from one or more base classes. Classes must have been defined by a previous \fBclass\fR command, or must be available to the auto-loading facility (see "AUTO-LOADING" below). A single class definition can contain no more than one \fBinherit\fR command. .sp The order of \fIbaseClass\fR names in the \fBinherit\fR 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 \fBinherit\fR list takes precedence. For example, if classes "Foo" and "Bar" both contain the member "x", and if another class has the "\fBinherit\fR" statement: .CS inherit Foo Bar .CE then the name "x" means "Foo::x". Other inherited members named "x" must be referenced with their explicit name, like "Bar::x". .TP \fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR Declares the \fIargs\fR argument list and \fIbody\fR used for the constructor, which is automatically invoked whenever an object is created. .sp Before the \fIbody\fR is executed, the optional \fIinit\fR statement is used to invoke any base class constructors that require arguments. Variables in the \fIargs\fR specification can be accessed in the \fIinit\fR code fragment, and passed to base class constructors. After evaluating the \fIinit\fR statement, any base class constructors that have not been executed are invoked automatically without arguments. This ensures that all base classes are fully constructed before the constructor \fIbody\fR 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 \fBinfo heritage\fR command. .sp If construction is successful, the constructor always returns the object name\-regardless of how the \fIbody\fR is defined\-and the object name becomes a command in the current namespace context. If construction fails, an error message is returned. .TP \fBdestructor \fIbody\fR Declares the \fIbody\fR 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. .sp 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 "\fBinfo heritage\fR" command, and it is exactly the opposite of the default constructor order. .TP \fBmethod \fIname\fR ?\fIargs\fR? ?\fIbody\fR? Declares a method called \fIname\fR. When the method \fIbody\fR is executed, it will have automatic access to object-specific variables and common data members. .sp If the \fIargs\fR list is specified, it establishes the usage information for this method. The \fBbody\fR command can be used to redefine the method body, but the \fIargs\fR list must match this specification. .sp 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 manipulates. Methods in a base class that are redefined in the current class, or hidden by another base class, can be qualified using the "\fIclassName\fR::\fImethod\fR" syntax. .TP \fBproc \fIname\fR ?\fIargs\fR? ?\fIbody\fR? Declares a proc called \fIname\fR. A proc is an ordinary procedure within the class namespace. Unlike a method, a proc is invoked without referring to a specific object. When the proc \fIbody\fR is executed, it will have automatic access only to common data members. .sp If the \fIargs\fR list is specified, it establishes the usage information for this proc. The \fBbody\fR command can be used to redefine the proc body, but the \fIargs\fR list must match this specification. .sp 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 context, the proc is invoked using a qualified name like "\fIclassName\fB::\fIproc\fR". 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. .TP \fBvariable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR? Defines an object-specific variable named \fIvarName\fR. All object-specific variables are automatically available in class methods. They need not be declared with anything like the \fBglobal\fR command. .sp If the optional \fIinit\fR 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; uninitialized variables, on the other hand, can be set within the constructor and used as arrays. .sp The optional \fIconfig\fR script is only allowed for public variables. If specified, this code fragment is executed whenever a public variable is modified by the built-in "configure" method. The \fIconfig\fR script can also be specified outside of the class definition using the \fBconfigbody\fR command. .TP \fBcommon \fIvarName\fR ?\fIinit\fR? Declares a common variable named \fIvarName\fR. 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 \fBglobal\fR command. They are automatically visible in all class methods and procs. .sp If the optional \fIinit\fR string is specified, it is used as the initial value of the variable. Initialization forces the variable to be a simple scalar value; uninitialized variables, on the other hand, can be set with subsequent \fBset\fR and \fBarray\fR commands and used as arrays. .sp Once a common data member has been defined, it can be set using \fBset\fR and \fBarray\fR commands within the class definition. This allows common data members to be initialized as arrays. For example: .CS class Foo { common boolean set boolean(true) 1 set boolean(false) 0 } .CE Note that if common data members are initialized within the constructor, they get initialized again and again whenever new objects are created. .TP \fBpublic \fIcommand\fR ?\fIarg arg ...\fR? .TP \fBprotected \fIcommand\fR ?\fIarg arg ...\fR? .TP \fBprivate \fIcommand\fR ?\fIarg arg ...\fR? These commands are used to set the protection level for class members that are created when \fIcommand\fR is evaluated. The \fIcommand\fR is usually \fBmethod\fR, \fBproc\fR, \fBvariable\fR or\fBcommon\fR, and the remaining \fIarg\fR's complete the member definition. However, \fIcommand\fR can also be a script containing many different member definitions, and the protection level will apply to all of the members that are created. .SH CLASS USAGE .PP Once a class has been defined, the class name can be used as a command to create new objects belonging to the class. .TP \fIclassName objName\fR ?\fIargs...\fR? Creates a new object in class \fIclassName\fR with the name \fIobjName\fR. Remaining arguments are passed to the constructor 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 \fIobjName\fR is created in the current namespace context, and \fIobjName\fR is returned as the result of this operation. If an error is encountered during construction, the destructors are automatically invoked to free any resources that have been allocated, the object is deleted, and an error is returned. .sp If \fIobjName\fR contains the string "\fB#auto\fR", that string is replaced with an automatically generated name. Names have the form \fIclassName\fR, where the \fIclassName\fR part is modified to start with a lowercase letter. In class "Toaster", for example, the "\fB#auto\fR" specification would produce names like toaster0, toaster1, etc. Note that "\fB#auto\fR" can be also be buried within an object name: .CS fileselectiondialog .foo.bar.#auto -background red .CE This would generate an object named ".foo.bar.fileselectiondialog0". .SH 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. .TP \fIobjName method\fR ?\fIargs...\fR? Invokes a method named \fImethod\fR on an object named \fIobjName\fR. Remaining arguments are passed to the argument list for the method. The method name can be "constructor", "destructor", any method name appearing in the class definition, or any of the following built-in methods. .SH BUILT-IN METHODS .TP \fIobjName\fR \fBcget option\fR Provides access to public variables as configuration options. This mimics the behavior of the usual "cget" operation for Tk widgets. The \fIoption\fR argument is a string of the form "\fB-\fIvarName\fR", and this method returns the current value of the public variable \fIvarName\fR. .TP \fIobjName\fR \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? Provides access to public variables as configuration options. This mimics the behavior of the usual "configure" operation for Tk widgets. With no arguments, this method returns a list of lists describing all of the public variables. Each list has three elements: the variable name, its initial value and its current value. .sp If a single \fIoption\fR of the form "\fB-\fIvarName\fR" is specified, then this method returns the information for that one variable. .sp Otherwise, the arguments are treated as \fIoption\fR/\fIvalue\fR 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 \fBconfigure\fR method returns an error. .TP \fIobjName\fR \fBisa \fIclassName\fR Returns non-zero if the given \fIclassName\fR can be found in the object's heritage, and zero otherwise. .TP \fIobjName\fR \fBinfo \fIoption\fR ?\fIargs...\fR? Returns information related to a particular object named \fIobjName\fR, or to its class definition. The \fIoption\fR parameter includes the following things, as well as the options recognized by the usual Tcl "info" command: .RS .TP \fIobjName\fR \fBinfo class\fR Returns the name of the most-specific class for object \fIobjName\fR. .TP \fIobjName\fR \fBinfo inherit\fR Returns the list of base classes as they were defined in the "\fBinherit\fR" command, or an empty string if this class has no base classes. .TP \fIobjName\fR \fBinfo heritage\fR Returns the current class name and the entire list of base classes in the order that they are traversed for member lookup and object destruction. .TP \fIobjName\fR \fBinfo function\fR ?\fIcmdName\fR? ?\fB-protection\fR? ?\fB-type\fR? ?\fB-name\fR? ?\fB-args\fR? ?\fB-body\fR? With no arguments, this command returns a list of all class methods and procs. If \fIcmdName\fR is specified, 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. .TP \fIobjName\fR \fBinfo variable\fR ?\fIvarName\fR? ?\fB-protection\fR? ?\fB-type\fR? ?\fB-name\fR? ?\fB-init\fR? ?\fB-value\fR? ?\fB-config\fR? With no arguments, this command returns a list of all object-specific variables and common data members. If \fIvarName\fR 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 \fIvarName\fR is a public variable, the "config" code is included on this list. Flags can be used to request specific elements from this list. .SH CHAINING METHODS/PROCS Sometimes a base class has a method or proc that is redefined 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: .CS 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 } } .CE We might create another class like SmartToaster that redefines the "toast" method. If we want to access the base class method, we can qualify it with the base class name, to avoid ambiguity: .CS class SmartToaster { inherit Toaster method toast {nslices} { if {$crumbs > 40} { clean } return [Toaster::toast $nslices] } } .CE Instead of hard-coding the base class name, we can use the "chain" command like this: .CS class SmartToaster { inherit Toaster method toast {nslices} { if {$crumbs > 40} { clean } return [chain $nslices] } } .CE 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. .SH AUTO-LOADING .PP 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 \fB[incr\ Tcl]\fR class definition and the file where the definition can be found. .PP For example, suppose a directory contains the definitions for classes "Toaster" and "SmartToaster". Then the "tclIndex" file for this directory would look like: .CS # 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" .PP The \fBauto_mkindex\fR command is used to automatically generate "tclIndex" files. .CE The auto-loader must be made aware of this directory by appending 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. .SH C PROCEDURES .PP C procedures can be integrated into an \fB[incr\ Tcl]\fR class definition to implement methods, procs, and the "config" code for public variables. Any body that starts with "\fB@\fR" is treated as the symbolic name for a C procedure. .PP Symbolic names are established by registering procedures via \fBItcl_RegisterC()\fR. This is usually done in the \fBTcl_AppInit()\fR procedure, which is automatically called when the interpreter starts up. In the following example, the procedure \fCMy_FooCmd()\fR is registered with the symbolic name "foo". This procedure can be referenced in the \fBbody\fR command as "\fC@foo\fR". .CS 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; } } .CE C procedures are implemented just like ordinary Tcl commands. See the \fBCrtCommand\fR man page for details. Within the procedure, class data members can be accessed like ordinary variables using \fBTcl_SetVar()\fR, \fBTcl_GetVar()\fR, \fBTcl_TraceVar()\fR, etc. Class methods and procs can be executed like ordinary commands using \fBTcl_Eval()\fR. \fB[incr\ Tcl]\fR makes this possible by automatically setting up the context before executing the C procedure. .PP 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. .SH KEYWORDS class, object, object-oriented itcl2.2/itcl/doc/body.n100666 1751 0 10062 6423554675 13707 0ustar kunkeewheel'\" '\" Copyright (c) 1996 Lucent Technologies '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" $Id: body.n,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ '\" .so man.macros '\" # CS - begin display of code example .de CS .in +0.4i .nf \fC .. '\" # CE - end display of code example .de CE \fP .fi .in -0.4i .. .TH body n "" itcl "[incr\ Tcl]" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME body \- change the body for a class method/proc .SH SYNOPSIS \fBbody \fIclassName\fB::\fIfunction args body\fR .BE .SH DESCRIPTION .PP The \fBbody\fR command is used outside of an \fB[incr\ Tcl]\fR 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 \fBclass\fR command with declarations for methods, procs, instance variables and common variables. The "implementation" part is a series of \fBbody\fR and \fBconfigbody\fR 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 \fBemacs\fR editor, the "interface" 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. .PP The name "\fIclassName\fB::\fIfunction\fR" identifies the method/proc being changed. .PP If an \fIargs\fR list was specified when the \fIfunction\fR was defined in the class definition, the \fIargs\fR list for the \fBbody\fR 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 \fBargs\fR argument acts as a wildcard when included in the \fIargs\fR list in the class definition; it will match zero or more arguments of any type when the body is redefined. .PP If the \fIbody\fR string starts with "\fB@\fR", it is treated as the symbolic name for a C procedure. The \fIargs\fR 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 \fIbody\fR does not start with "\fB@\fR", it is treated as a Tcl command script. When the function is invoked, command line arguments are matched against the \fIargs\fR list, and local variables are created to represent each argument. This is the usual behavior for a Tcl-style proc. .PP Symbolic names for C procedures are established by registering procedures via \fBItcl_RegisterC()\fR. This is usually done in the \fBTcl_AppInit()\fR procedure, which is automatically called when the interpreter starts up. In the following example, the procedure \fCMy_FooCmd()\fR is registered with the symbolic name "foo". This procedure can be referenced in the \fBbody\fR command as "\fC@foo\fR". .CS 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; } } .CE .SH 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 \fBbody\fR command. Note that the bodies of the constructor/destructor must be included in the class definition, but they can be redefined via the \fBbody\fR command as well. .CS 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 .CE .SH KEYWORDS class, object, procedure itcl2.2/itcl/doc/configbody.n100666 1751 0 7450 6423554675 15064 0ustar kunkeewheel'\" '\" Copyright (c) 1996 Lucent Technologies '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" $Id: configbody.n,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ '\" .so man.macros '\" # CS - begin display of code example .de CS .in +0.4i .nf \fC .. '\" # CE - end display of code example .de CE \fP .fi .in -0.4i .. .TH configbody n "" itcl "[incr\ Tcl]" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME configbody \- change the "config" code for a public variable .SH SYNOPSIS \fBconfigbody \fIclassName\fB::\fIvarName body\fR .BE .SH DESCRIPTION .PP The \fBconfigbody\fR command is used outside of an \fB[incr\ Tcl]\fR 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 \fBconfigure\fR method. Each variable can have a bit of "config" code associate with it that is automatically executed when the variable is configured. The \fBconfigbody\fR command can be used to define or redefine this body of code. .PP Like the \fBbody\fR command, this facility allows a class definition to have separate "interface" and "implementation" parts. The "interface" part is a \fBclass\fR command with declarations for methods, procs, instance variables and common variables. The "implementation" part is a series of \fBbody\fR and \fBconfigbody\fR 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 \fBemacs\fR editor, the "interface" 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. .PP The name "\fIclassName\fB::\fIvarName\fR" identifies the public variable being updated. If the \fIbody\fR string starts with "\fB@\fR", it is treated as the symbolic name for a C procedure. Otherwise, it is treated as a Tcl command script. .PP Symbolic names for C procedures are established by registering procedures via \fBItcl_RegisterC()\fR. This is usually done in the \fBTcl_AppInit()\fR procedure, which is automatically called when the interpreter starts up. In the following example, the procedure \fCMy_FooCmd()\fR is registered with the symbolic name "foo". This procedure can be referenced in the \fBconfigbody\fR command as "\fC@foo\fR". .CS 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; } } .CE .SH EXAMPLE In the following example, a "File" class is defined to represent open files. Whenever the "-name" option is configured, 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. .CS 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 .CE .SH KEYWORDS class, object, variable, configure itcl2.2/itcl/doc/delete.n100666 1751 0 5004 6423554675 14174 0ustar kunkeewheel'\" '\" Copyright (c) 1996 Lucent Technologies '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" $Id: delete.n,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ '\" .so man.macros '\" # CS - begin display of code example .de CS .in +0.4i .nf \fC .. '\" # CE - end display of code example .de CE \fP .fi .in -0.4i .. .TH delete n "" itcl "[incr\ Tcl]" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME delete \- delete things in the interpreter .SH SYNOPSIS \fBdelete \fIoption\fR ?\fIarg arg ...\fR? .BE .SH DESCRIPTION .PP The \fBdelete\fR command is used to delete things in the interpreter. It is implemented as an ensemble, so extensions can add their own options and extend the behavior of this command. By default, the \fBdelete\fR command handles the destruction of namespaces. .PP The \fIoption\fR argument determines what action is carried out by the command. The legal \fIoptions\fR (which may be abbreviated) are: .TP \fBdelete class \fIname\fR ?\fIname...\fR? Deletes one or more \fB[incr\ Tcl]\fR classes called \fIname\fR. This deletes all objects in the class, and all derived classes as well. .sp 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 "\fBdelete namespace\fR" command. .TP \fBdelete object \fIname\fR ?\fIname...\fR? Deletes one or more \fB[incr\ Tcl]\fR objects called \fIname\fR. 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 \fIname\fR is removed as a command from the interpreter. .sp If the access command for an object resides in another namespace, then its qualified name can be used: .CS delete object foo::bar::x .CE If an error is encountered while destructing an object, the \fBdelete\fR command is aborted and the object remains alive. To destroy an object without regard for errors, use the "\fBrename\fR" command to destroy the object access command. .TP \fBdelete namespace \fIname\fR ?\fIname...\fR? Deletes one or more namespaces called \fIname\fR. 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. .SH KEYWORDS namespace, proc, variable, ensemble itcl2.2/itcl/doc/info.n100666 1751 0 24143 6423554675 13712 0ustar kunkeewheel'\" '\" Copyright (c) 1993 The Regents of the University of California. '\" Copyright (c) 1994 Sun Microsystems, Inc. '\" Copyright (c) 1996 Lucent Technologies '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" @(#) info.n 1.6 95/06/28 13:41:53 '\" .so man.macros .TH info n 7.0 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME info \- Return information about the state of the Tcl interpreter .SH SYNOPSIS \fBinfo \fIoption \fR?\fIarg arg ...\fR? .BE .SH DESCRIPTION .PP This command provides information about various internals of the Tcl interpreter. The legal \fIoption\fR's (which may be abbreviated) are: .TP \fBinfo args \fIprocname\fR Returns a list containing the names of the arguments to procedure \fIprocname\fR, in order. \fIProcname\fR must be the name of a Tcl command procedure. .TP \fBinfo body \fIprocname\fR Returns the body of procedure \fIprocname\fR. \fIProcname\fR must be the name of a Tcl command procedure. .TP \fBinfo classes ?\fIpattern\fR? Returns a list of classes available in the current namespace context. .VS If a class belongs to the current namespace context, its simple name is reported; otherwise, if a class is imported from another namespace, its fully-qualified name is reported. .VE .sp If the optional \fIpattern\fR is specified, then the reported names are compared using the rules of the "\fBstring match\fR" command, and only matching names are reported. .TP \fBinfo cmdcount\fR Returns a count of the total number of commands that have been invoked in this interpreter. .TP \fBinfo commands \fR?\fIpattern\fR? If \fIpattern\fR isn't specified, returns a list of names of all the Tcl commands .VS in the current namespace context, .VE including both the built-in commands written in C and the command procedures defined using the \fBproc\fR command. If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. .TP \fBinfo complete \fIcommand\fR Returns 1 if \fIcommand\fR 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 typically 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. .TP \fBinfo context\fR .VS Returns the fully-qualified name for the current namespace context. The global namespace ("\fC::\fR") is represented as a null string, making it easy to build namespace names like "\fC[info context]::foo\fR". .VE .TP \fBinfo default \fIprocname arg varname\fR \fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR must be the name of an argument to that procedure. If \fIarg\fR doesn't have a default value then the command returns \fB0\fR. Otherwise it returns \fB1\fR and places the default value of \fIarg\fR into variable \fIvarname\fR. .TP \fBinfo exists \fIvarName\fR Returns \fB1\fR if the variable named \fIvarName\fR exists in the current context (either as a global or local variable), returns \fB0\fR otherwise. .TP \fBinfo globals \fR?\fIpattern\fR? If \fIpattern\fR isn't specified, returns a list of all the names of currently-defined global variables .VS in the current namespace context. .VE If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. .TP \fBinfo level\fR ?\fInumber\fR? If \fInumber\fR is not specified, this command returns a number giving the stack level of the invoking procedure, or 0 if the command is invoked at top-level. If \fInumber\fR is specified, then the result is a list consisting of the name and arguments for the procedure call at level \fInumber\fR on the stack. If \fInumber\fR is positive 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 procedure, -1 to its caller, and so on). See the \fBuplevel\fR command for more information on what stack levels mean. .TP \fBinfo library\fR Returns the name of the library directory in which standard Tcl scripts are stored. .VS This is actually the value of the \fBtcl_library\fR variable and may be changed by setting \fBtcl_library\fR. See the \fBtclvars\fR manual entry for more information. .VE .TP \fBinfo locals \fR?\fIpattern\fR? If \fIpattern\fR 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 \fBglobal\fR and \fBupvar\fR commands will not be returned. If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. .TP \fBinfo namespace\fR \fIoption\fR ?\fIarg arg ...\fR? .VS A collection of queries regarding namespaces. The \fIoption\fR argument should be one of the following: .VE .RS .TP \fBinfo namespace all\fR ?\fIpattern\fR? .VS 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. .VE .TP \fBinfo namespace children\fR ?\fIname\fR? .VS Returns a list of all child namespaces in the namespace \fIname\fR. If \fIname\fR is not specified, then children are reported in the current namespace context. Unlike the "\fBinfo namespace all\fR" command, this command reports only the children directly contained within the namespace, and it reports them with fully-qualified names. .VE .TP \fBinfo namespace parent\fR ?\fIname\fR? .VS Returns the fully-qualified name of the parent for namespace \fIname\fR. If \fIname\fR is not specified, then the parent of the current namespace context is reported. .VE .TP \fBinfo namespace qualifiers\fR \fIstring\fR .VS Returns the leading namespace qualifiers for the specified string. Qualifiers are namespace names separated by the "\fC::\fR" string. For the string "::foo::bar::x", this command would return "::foo::bar". .VE .TP \fBinfo namespace tail\fR \fIstring\fR .VS Returns the simple name at the end of qualified string. Qualifiers are namespace names separated by the "\fC::\fR" string. For the string "::foo::bar::x", this command would return "x". .VE .RE .TP \fBinfo objects ?\fIpattern\fR? ?\fB-class \fIclassName\fR? ?\fB-isa \fIclassName\fR? Returns a list of objects available in the current namespace context. .VS If an object belongs to the current namespace context, its simple name is reported; otherwise, if an object is imported from another namespace, its fully-qualified access command is reported. .VE .sp If the optional \fIpattern\fR is specified, then the reported names are compared using the rules of the "\fBstring match\fR" command, and only matching names are reported. If the optional "\fB-class\fR" parameter is specified, this list is restricted to objects whose most-specific class is \fIclassName\fR. If the optional "\fB-isa\fR" parameter is specified, this list is further restricted to objects having the given \fIclassName\fR anywhere in their heritage. .TP \fBinfo patchlevel\fR .VS Returns the value of the global variable \fBtcl_patchLevel\fR; see the \fBtclvars\fR manual entry for more information. .VE .TP \fBinfo procs \fR?\fIpattern\fR? If \fIpattern\fR isn't specified, returns a list of all the names of Tcl command procedures .VS in the current namespace context. .VE If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. .TP \fBinfo protection\fR ?\fB-command\fR? ?\fB-variable\fR? \fIname\fR .VS Returns the current protection level (public, protected or private) for the specified \fIname\fR. The protection level is set using the \fBpublic\fR, \fBprotected\fR and \fBprivate\fR 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 \fBnamespace\fR for the rules regarding command/variable access. If no flags specified, or if the \fB-command\fR flag is included, \fIname\fR is treated as a command name. If the \fB-variable\fR flag is included, \fIname\fR is treated as a variable name. .VE .TP \fBinfo script\fR If a Tcl script file is currently being evaluated (i.e. there is a call to \fBTcl_EvalFile\fR active or there is an active invocation of the \fBsource\fR command), then this command returns the name of the innermost file being processed. Otherwise the command returns an empty string. .TP \fBinfo tclversion\fR .VS Returns the value of the global variable \fBtcl_version\fR; see the \fBtclvars\fR manual entry for more information. .VE .TP \fBinfo vars\fR ?\fIpattern\fR? If \fIpattern\fR isn't specified, returns a list of all the names of currently-visible variables, including both locals and currently-visible globals. If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. .TP \fBinfo which\fR ?\fB-command\fR? ?\fB-variable\fR? ?\fB-namespace\fR? \fIname\fR .VS Resolves the specified \fIname\fR in the current namespace context and returns a fully-qualified name which uniquely identifies it. See the documentation on \fBnamespace\fR for the rules regarding name resolution. If no flags specified, or if the \fB-command\fR flag is included, \fIname\fR is treated as a command name. If the \fB-variable\fR flag is included, \fIname\fR is treated as a variable name. If the \fB-namespace\fR flag is included, \fIname\fR is treated as a namespace name. .VE .SH KEYWORDS command, information, interpreter, level, procedure, variable itcl2.2/itcl/doc/itcl.n100666 1751 0 16443 6423554675 13716 0ustar kunkeewheel'\" '\" Copyright (c) 1996 Lucent Technologies '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" $Id: itcl.n,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ '\" .so man.macros '\" # CS - begin display of code example .de CS .in +0.4i .nf \fC .. '\" # CE - end display of code example .de CE \fP .fi .in -0.4i .. .TH itcl n "" itcl "[incr\ Tcl]" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME itcl \- object-oriented extensions to Tcl .BE .SH DESCRIPTION .PP \fB[incr\ Tcl]\fR 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, \fB[incr\ Tcl]\fR 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 inheritance. .SH CLASSES .PP The fundamental construct in \fB[incr\ Tcl]\fR is the class definition. 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 "\fBbutton\fR" widget, for example, has methods such as "flash" and "invoke" that cause a particular button to blink and invoke its command. .PP Within the body of a method, the "variables" defined in the class are automatically available. They need not be declared with anything like the \fBglobal\fR 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. .PP Each class has its own namespace containing things that are common to all objects which belong to the class. For example, "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 definition, they need not be declared using the \fBglobal\fR 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 \fBglobal\fR command each time they are used. .PP 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 qualified with the class namespace like "\fIclassName\fB::\fIproc\fR". 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. .PP 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. .PP 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 public interface says \fIwhat\fR an object will do but not \fIhow\fR it will do it. Protected and private members, along with the bodies of class methods and procs, provide the implementation 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. .PP The fact that \fB[incr\ Tcl]\fR objects look like Tk widgets is no accident. \fB[incr\ Tcl]\fR was designed this way, to blend naturally into a Tcl/Tk application. But \fB[incr\ Tcl]\fR extends the Tk paradigm from being merely object-based to being fully object-oriented. An object-oriented system supports inheritance, allowing classes to share common behaviors by inheriting 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 \fIshared\fR rather than \fIcopied\fR. The resulting application is easier to understand and maintain, and derived classes (e.g., specialized appliances) can be added or removed more easily. .PP This description was merely a brief overview of object-oriented programming and \fB[incr\ Tcl]\fR. A more tutorial introduction is presented in the paper included with this distribution. See the \fBclass\fR command for more details on creating and using classes. .SH NAMESPACES .PP \fB[incr\ Tcl]\fR 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 "\fC::\fR") is the root namespace for an interpreter; all other namespaces are contained within it. .PP See the \fBnamespace\fR command for details on creating and using namespaces. .SH MEGA-WIDGETS .PP 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 listboxes, some entry widgets and some control buttons. These individual widgets are put together in a way that makes them act like one big widget. .PP \fB[incr\ Tk]\fR is a framework for building mega-widgets. It uses \fB[incr\ Tcl]\fR to support the object paradigm, and adds base classes which provide default widget behaviors. See the \fBitk\fR man page for more details. .PP \fB[incr\ Widgets]\fR is a library of mega-widgets built using \fB[incr\ Tk]\fR. 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. .SH KEYWORDS class, object, object-oriented, namespace, mega-widget itcl2.2/itcl/doc/itcl_class.n100666 1751 0 42566 6423554675 15110 0ustar kunkeewheel'\" '\" Copyright (c) 1996 Lucent Technologies '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" $Id: itcl_class.n,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ '\" .so man.macros '\" # CS - begin display of code example .de CS .in +0.4i .nf \fC .. '\" # CE - end display of code example .de CE \fP .fi .in -0.4i .. .TH itcl_class n "" itcl "[incr\ Tcl]" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME itcl_class \- create a class of objects (obsolete) .SH SYNOPSIS \fBitcl_class \fIclassName\fR \fB{ .br \fBinherit \fIbaseClass\fR ?\fIbaseClass\fR...? .br \fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR .br \fBdestructor \fIbody\fR .br \fBmethod \fIname args body\fR .br \fBproc \fIname args body\fR .br \fBpublic \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR? .br \fBprotected \fIvarName\fR ?\fIinit\fR? .br \fBcommon \fIvarName\fR ?\fIinit\fR? .br \fB}\fR .sp \fIclassName objName\fR ?\fIargs...\fR? .br \fIclassName\fR \fB#auto\fR ?\fIargs...\fR? .br \fIclassName\fR \fB::\fR \fIproc\fR ?\fIargs...\fR? .sp \fIobjName method\fR ?\fIargs...\fR? .sp \fICommands available within class methods/procs:\fR .br \fBglobal \fIvarName\fR ?\fIvarName...\fR? .br \fBprevious \fIcommand\fR ?\fIargs...\fR? .br \fBvirtual \fIcommand\fR ?\fIargs...\fR? .BE .SH DESCRIPTION .PP This command is considered obsolete, but is retained for backward-compatibility with earlier versions of \fB[incr\ Tcl]\fR. It has been replaced by the \fBclass\fR command, which should be used for any new development. .TP \fBitcl_class \fIclassName definition\fR Provides the definition for a class named \fIclassName\fR. If \fIclassName\fR is already defined, then this command returns an error. If the class definition is successfully parsed, \fIclassName\fR becomes a command in the current namespace context, handling the creation of objects and providing access to class scope. The class \fIdefinition\fR is evaluated as a series of Tcl statements that define elements within the class. In addition to the usual commands, the following class definition commands are recognized: .RS .TP \fBinherit \fIbaseClass\fR ?\fIbaseClass\fR...? Declares one or more base classes, causing the current class to inherit their characteristics. Classes must have been defined by a previous \fBitcl_class\fR command, or must be available to the auto-loading facility (see "AUTO-LOADING" below). A single class definition can contain no more than one \fBinherit\fR command. .RS .LP When the same member name appears in two or more base classes, the base class that appears first in the \fBinherit\fR list takes precedence. For example, if classes "Foo" and "Bar" both contain the member "x", then the "\fBinherit\fR" statement: .CS inherit Foo Bar .CE 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 "\fIclass\fR::\fImember\fR" name. .RE .TP \fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR Declares the argument list and body used for the constructor, which is automatically invoked whenever an object is created. Before .VS the \fIbody\fR is executed, the optional \fIinit\fR statement is used to invoke any base class constructors that require arguments. Variables in the \fIargs\fR specification can be accessed in the \fIinit\fR code fragment, and passed to base class constructors. After evaluating the \fIinit\fR statement, any base class constructors that have not been executed are invoked without arguments. This ensures that all base classes are fully constructed before the constructor \fIbody\fR is executed. .VE If construction is successful, the constructor always returns the object name\-regardless of how the \fIbody\fR is defined\-and the object name becomes a command in the current namespace context. If construction fails, an error message is returned. .TP \fBdestructor \fIbody\fR 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. .RS .LP .VS 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 "\fBinfo heritage\fR" command, and it is exactly the opposite of the default constructor order. .VE .RE .TP \fBmethod \fIname args body\fR Declares a method called \fIname\fR with an argument list \fIargs\fR and a \fIbody\fR of Tcl statements. A method is just like the usual Tcl "proc" except that it has transparent access to .VS object-specific variables, as well as .VE 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 prefaced 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 "\fIclass\fR::\fImethod\fR" syntax. .TP \fBproc \fIname args body\fR Declares a proc called \fIname\fR with an argument list \fIargs\fR and a \fIbody\fR of Tcl statements. A proc is similar to a method, except that it can be invoked without referring to a specific object, and therefore has access only to common variables\-not .VS to object-specific variables declared with the \fBpublic\fR and \fBprotected\fR commands. .VE Within the class scope, a proc can be invoked like any other command\-simply by using its name. In any other namespace context, the proc is invoked using a qualified name like "\fIclassName\fB::\fIproc\fR". 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. .TP \fBpublic \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR? Declares a public variable named \fIvarName\fR. Public variables are visible in methods within the scope of their class and any derived class. In addition, they can be modified outside of the class scope using the special "config" formal argument (see "ARGUMENT LISTS" above). If the optional \fIinit\fR is specified, it is used as the initial value of the variable when a new object is created. If the optional \fIconfig\fR command is specified, it is invoked whenever a public variable is modified via the "config" formal argument; if the \fIconfig\fR command returns an error, the public variable is reset to its value before configuration, and the method handling the configuration returns an error. .TP \fBprotected \fIvarName\fR ?\fIinit\fR? Declares a protected variable named \fIvarName\fR. 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 \fIinit\fR 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; uninitialized 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. .TP \fBcommon \fIvarName\fR ?\fIinit\fR? Declares a common variable named \fIvarName\fR. 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 \fIinit\fR is specified, it is used as the initial value of the variable. Initialization forces the variable to be a simple scalar value; uninitialized variables, on the other hand, can be used as arrays. .RS .LP 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: .CS itcl_class Foo { . . common boolean set boolean(true) 1 set boolean(false) 0 } .CE .RE .RE .SH CLASS USAGE .PP When a class definition has been loaded (or made available to the auto-loader), the class name can be used as a command. .TP \fIclassName objName\fR ?\fIargs...\fR? Creates a new object in class \fIclassName\fR with the name \fIobjName\fR. Remaining arguments are passed to the constructor. 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. .TP \fIclassName\fR #auto ?\fIargs...\fR? Creates a new object in class \fIclassName\fR with an automatically generated name. Names are of the form \fIclassName\fR, .VS where the \fIclassName\fR part is modified to start with a lowercase letter. In class "Toaster", for example, the "\fB#auto\fR" specification would produce names toaster0, toaster1, etc. Remaining arguments are .VE passed to the constructor. 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. .TP \fIclassName\fR :: \fIproc\fR ?\fIargs...\fR? Used outside of the class scope to invoke a class proc named \fIproc\fR. 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. .RS .LP .VS Notice that, unlike any other scope qualifier in \fB[incr\ Tcl]\fR, 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. .VE .RE .SH OBJECT USAGE .TP \fIobjName method\fR ?\fIargs...\fR? Invokes a method named \fImethod\fR to operate on the specified object. Remaining arguments are passed to the method. The method name can be "constructor", "destructor", any method name appearing in the class definition, or any of the following built-in methods. .SH BUILT-IN METHODS .TP \fIobjName\fR \fBisa \fIclassName\fR Returns non-zero if the given \fIclassName\fR can be found in the object's heritage, and zero otherwise. .TP \fIobjName\fR \fBdelete\fR Invokes the destructor associated with an object. If the destructor is successful, data associated with the object is deleted and \fIobjName\fR is removed as a command from the interpreter. Returns the empty string, regardless of the destructor body. .RS .LP .VS The built-in \fBdelete\fR method has been replaced by the "\fBdelete object\fR" command in the global namespace, and is considered obsolete. The capability is still supported, however, to provide backward-compatibility with earlier versions. .VE .RE .TP \fIobjName\fR \fBinfo \fIoption\fR ?\fIargs...\fR? Returns information related to the class definition or to a particular object named \fIobjName\fR. The \fIoption\fR parameter includes the following things, as well as the options recognized by the usual Tcl "info" command: .RS .TP \fIobjName\fR \fBinfo class\fR .VS Returns the name of the most-specific class for object \fIobjName\fR. .VE .TP \fIobjName\fR \fBinfo inherit\fR Returns the list of base classes as they were defined in the "\fBinherit\fR" command, or an empty string if this class has no base classes. .TP \fIobjName\fR \fBinfo heritage\fR Returns the current class name and the entire list of base classes in the order that they are traversed for member lookup and object destruction. .TP \fIobjName\fR \fBinfo method\fR ?\fImethodName\fR? ?\fB-args\fR? ?\fB-body\fR? With no arguments, this command returns a list of all class methods. If \fImethodName\fR is specified, it returns information for a specific method. If neither of the optional \fB-args\fR or \fB-body\fR 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 \fImethodName\fR is not recognized, an empty string is returned. .TP \fIobjName\fR \fBinfo proc\fR ?\fIprocName\fR? ?\fB-args\fR? ?\fB-body\fR? With no arguments, this command returns a list of all class procs. If \fIprocName\fR is specified, it returns information for a specific proc. If neither of the optional \fB-args\fR or \fB-body\fR 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 \fIprocName\fR is not recognized, an empty string is returned. .TP \fIobjName\fR \fBinfo public\fR ?\fIvarName\fR? ?\fB-init\fR? ?\fB-value\fR? ?\fB-config\fR? With no arguments, this command returns a list of all public variables. If \fIvarName\fR is specified, it returns information for a specific public variable. If none of the optional \fB-init\fR, \fB-value\fR or \fB-config\fR flags are specified, all available information is returned as a list of four elements including the variable name, initial value, current value, and configuration commands. Otherwise, the requested information is returned without the variable name. If the \fIvarName\fR is not recognized, an empty string is returned. .TP \fIobjName\fR \fBinfo protected\fR ?\fIvarName\fR? ?\fB-init\fR? ?\fB-value\fR? With no arguments, this command returns a list of all protected variables. If \fIvarName\fR is specified, it returns information for a specific protected variable. If neither of the optional \fB-init\fR or \fB-value\fR 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 \fIvarName\fR is not recognized, an empty string is returned. .TP \fIobjName\fR \fBinfo common\fR ?\fIvarName\fR? ?\fB-init\fR? ?\fB-value\fR? With no arguments, this command returns a list of all common variables. If \fIvarName\fR is specified, it returns information for a specific common variable. If neither of the optional \fB-init\fR or \fB-value\fR 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 \fIvarName\fR is not recognized, an empty string is returned. .RE .SH 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. .TP \fBglobal \fIvarName\fR ?\fIvarName...\fR? 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 \fIvarName\fR. This is useful when communicating with Tk widgets that rely on global variables. .TP \fBprevious \fIcommand\fR ?\fIargs...\fR? Invokes \fIcommand\fR in the scope of the most immediate base class .VS (i.e., the "previous" class) for the object. For classes using single .VE inheritance, this facility can be used to avoid hard-wired base class references of the form "\fIclass\fR::\fIcommand\fR", 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. .TP \fBvirtual \fIcommand\fR ?\fIargs...\fR? .VS Invokes \fIcommand\fR 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 programming, however, and should therefore be used sparingly. .VE .SH AUTO-LOADING .PP 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 \fB[incr\ Tcl]\fR class definition and the file where the definition can be found. .PP For example, suppose a directory contains the definitions for classes "Toaster" and "SmartToaster". Then the "tclIndex" file for this directory would look like: .CS # 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" .PP The \fBauto_mkindex\fR command is used to automatically generate "tclIndex" files. .CE The auto-loader must be made aware of this directory by appending 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. .SH KEYWORDS class, object, object-oriented itcl2.2/itcl/doc/itcl_info.n100666 1751 0 4706 6423554675 14710 0ustar kunkeewheel'\" '\" Copyright (c) 1996 Lucent Technologies '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" $Id: itcl_info.n,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ '\" .so man.macros '\" # CS - begin display of code example .de CS .in +0.4i .nf \fC .. '\" # CE - end display of code example .de CE \fP .fi .in -0.4i .. .TH itcl_info n "" itcl "[incr\ Tcl]" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME itcl_info \- query info regarding classes and objects (obsolete) .SH SYNOPSIS \fBitcl_info classes ?\fIpattern\fR? .br \fBitcl_info objects ?\fIpattern\fR? ?\fB-class \fIclassName\fR? ?\fB-isa \fIclassName\fR? .BE .SH DESCRIPTION .PP This command is considered obsolete, but is retained for backward-compatibility with earlier versions of \fB[incr\ Tcl]\fR. It has been replaced by the "\fBinfo classes\fR" and "\fBinfo objects\fR" commands, which should be used for any new development. .PP The following commands are available in the global namespace to query information about classes and objects that have been created. .TP \fBitcl_info classes ?\fIpattern\fR? Returns a list of classes available in the current namespace context. .VS If a class belongs to the current namespace context, its simple name is reported; otherwise, if a class is imported from another namespace, its fully-qualified name is reported. .VE .sp If the optional \fIpattern\fR is specified, then the reported names are compared using the rules of the "\fBstring match\fR" command, and only matching names are reported. .TP \fBitcl_info objects ?\fIpattern\fR? ?\fB-class \fIclassName\fR? ?\fB-isa \fIclassName\fR? Returns a list of objects available in the current namespace context. .VS If an object belongs to the current namespace context, its simple name is reported; otherwise, if an object is imported from another namespace, its fully-qualified access command is reported. .VE .sp If the optional \fIpattern\fR is specified, then the reported names are compared using the rules of the "\fBstring match\fR" command, and only matching names are reported. If the optional "\fB-class\fR" parameter is specified, this list is restricted to objects whose most-specific class is \fIclassName\fR. If the optional "\fB-isa\fR" parameter is specified, this list is further restricted to objects having the given \fIclassName\fR anywhere in their heritage. .SH KEYWORDS class, object, object-oriented itcl2.2/itcl/doc/itclsh.1100666 1751 0 1631 6423554675 14125 0ustar kunkeewheel'\" '\" Copyright (c) 1996 Lucent Technologies '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" $Id: itclsh.1,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ '\" .so man.macros .TH itclsh 1 "" itcl "[incr\ Tcl]" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME itclsh \- Simple shell for [incr Tcl] .SH SYNOPSIS \fBitclsh\fR ?\fIfileName arg arg ...\fR? .BE .SH DESCRIPTION .PP \fBitclsh\fR is a shell-like application that reads Tcl commands from its standard input, or from a file, and evaluates them. It is just like \fBtclsh\fR, but includes the \fB[incr\ Tcl]\fR extensions for object-oriented programming. .PP See the \fBtclsh\fR man page for details concerning usage. See the \fBitcl\fR man page for an overview of \fB[incr\ Tcl]\fR. .SH KEYWORDS Tcl, itcl, interpreter, script file, shell itcl2.2/itcl/doc/itclvars.n100666 1751 0 7464 6423554675 14575 0ustar kunkeewheel'\" '\" Copyright (c) 1996 Lucent Technologies '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" $Id: itclvars.n,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ '\" .so man.macros '\" # CS - begin display of code example .de CS .in +0.4i .nf \fC .. '\" # CE - end display of code example .de CE \fP .fi .in -0.4i .. .TH itclvars n "" itcl "[incr\ Tcl]" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME itclvars \- variables used by [incr\ Tcl] .BE .SH DESCRIPTION .PP The following global variables are created and managed automatically by the \fB[incr\ Tcl]\fR library. Except where noted below, these variables should normally be treated as read-only by application-specific code and by users. .TP \fBitcl::library\fR When an interpreter is created, \fB[incr\ Tcl]\fR initializes this variable to hold the name of a directory containing the system library of \fB[incr\ Tcl]\fR scripts. The initial value of \fBitcl::library\fR is set from the ITCL_LIBRARY environment variable if it exists, or from a compiled-in value otherwise. .TP \fBitcl::patchLevel\fR When an interpreter is created, \fB[incr\ Tcl]\fR initializes this variable to hold the current patch level for \fB[incr\ Tcl]\fR. For example, the value "\fB2.0p1\fR" indicates \fB[incr\ Tcl]\fR version 2.0 with the first set of patches applied. .TP \fBitcl::purist\fR When an interpreter is created containing Tcl/Tk and the \fB[incr\ Tcl]\fR namespace facility, this variable controls a "backward-compatibility" mode for widget access. .sp 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, .CS namespace foo { namespace bar { button .b -text "Testing" } } foo::bar::.b configure -background red pack .b .CE Note that the window name "\fC.b\fR" is still used in conjunction with commands like \fBpack\fR and \fBdestroy\fR. However, the access command for the widget (i.e., name that appears as the \fIfirst\fR argument on a command line) must be more specific. .sp The "\fBwinfo command\fR" command can be used to query the fully-qualified access command for any widget, so one can write: .CS [winfo command .b] configure -background red .CE and this is good practice when writing library procedures. Also, in conjunction with the \fBbind\fR command, the "%q" field can be used in place of "%W" as the access command: .CS bind Button {%q flash; %q invoke} .CE 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. .sp The \fBitcl::purist\fR 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 \fBunknown\fR procedure stumbles across a widget name, it simply uses "\fBwinfo command\fR" to determine the appropriate command name. If this variable 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. .TP \fBitcl::version\fR When an interpreter is created, \fB[incr\ Tcl]\fR initializes this variable to hold the version number of the form \fIx.y\fR. Changes to \fIx\fR represent major changes with probable incompatibilities and changes to \fIy\fR represent small enhancements and bug fixes that retain backward compatibility. .SH KEYWORDS itcl, variables itcl2.2/itcl/doc/license.terms100666 1751 0 2751 6423554675 15257 0ustar kunkeewheel------------------------------------------------------------------------ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>> [incr Tcl] <<<<<<<<<<<<<<<<<<<<<<<<<<<<<< AUTHOR: Michael J. McLennan Bell Labs Innovations for Lucent Technologies mmclennan@lucent.com http://www.tcltk.com/itcl ======================================================================== Copyright (c) 1993-1996 Lucent Technologies ======================================================================== Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that the copyright notice and warranty disclaimer appear in supporting documentation, and that the names of Lucent Technologies any of their entities not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. Lucent Technologies disclaims all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall Lucent be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortuous action, arising out of or in connection with the use or performance of this software. ======================================================================== itcl2.2/itcl/doc/local.n100666 1751 0 3761 6423554675 14034 0ustar kunkeewheel'\" '\" Copyright (c) 1996 Lucent Technologies '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" $Id: local.n,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ '\" .so man.macros '\" # CS - begin display of code example .de CS .in +0.4i .nf \fC .. '\" # CE - end display of code example .de CE \fP .fi .in -0.4i .. .TH local n "" itcl "[incr\ Tcl]" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME local \- create an object local to a procedure .SH SYNOPSIS \fBlocal \fIclassName objName\fR ?\fIarg arg ...\fR? .BE .SH DESCRIPTION .PP The \fBlocal\fR command creates an \fB[incr\ Tcl]\fR 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. .PP As a side effect, this command creates a variable named "\fCitcl-local-\fIxxx\fR", where \fIxxx\fR is the name of the object that is created. This variable detects when the call frame is destroyed and automatically deletes the associated object. .SH 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 \fBputs\fR statements included in the constructor/destructor show the object coming and going as the procedure is called. .CS 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]" .CE .SH KEYWORDS class, object, procedure itcl2.2/itcl/doc/man.macros100666 1751 0 6460 6423554676 14544 0ustar kunkeewheel'\" The definitions below are for supplemental macros used in Tcl/Tk '\" manual entries. '\" '\" .AP type name in/out [indent] '\" Start paragraph describing an argument to a library procedure. '\" type is type of argument (int, etc.), in/out is either "in", "out", '\" or "in/out" to describe whether procedure reads or modifies arg, '\" and indent is equivalent to second arg of .IP (shouldn't ever be '\" needed; use .AS below instead) '\" '\" .AS [type [name]] '\" Give maximum sizes of arguments for setting tab stops. Type and '\" name are examples of largest possible arguments that will be passed '\" to .AP later. If args are omitted, default tab stops are used. '\" '\" .BS '\" Start box enclosure. From here until next .BE, everything will be '\" enclosed in one large box. '\" '\" .BE '\" End of box enclosure. '\" '\" .VS '\" Begin vertical sidebar, for use in marking newly-changed parts '\" of man pages. '\" '\" .VE '\" End of vertical sidebar. '\" '\" .DS '\" Begin an indented unfilled display. '\" '\" .DE '\" End of indented unfilled display. '\" '\" @(#) man.macros 1.3 95/05/06 15:19:04 '\" '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. .if t .wh -1.3i ^B .nr ^l \n(.l .ad b '\" # Start an argument description .de AP .ie !"\\$4"" .TP \\$4 .el \{\ . ie !"\\$2"" .TP \\n()Cu . el .TP 15 .\} .ie !"\\$3"" \{\ .ta \\n()Au \\n()Bu \&\\$1 \\fI\\$2\\fP (\\$3) .\".b .\} .el \{\ .br .ie !"\\$2"" \{\ \&\\$1 \\fI\\$2\\fP .\} .el \{\ \&\\fI\\$1\\fP .\} .\} .. '\" # define tabbing values for .AP .de AS .nr )A 10n .if !"\\$1"" .nr )A \\w'\\$1'u+3n .nr )B \\n()Au+15n .\" .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n .nr )C \\n()Bu+\\w'(in/out)'u+2n .. '\" # BS - start boxed text '\" # ^y = starting y location '\" # ^b = 1 .de BS .br .mk ^y .nr ^b 1u .if n .nf .if n .ti 0 .if n \l'\\n(.lu\(ul' .if n .fi .. '\" # BE - end boxed text (draw box now) .de BE .nf .ti 0 .mk ^t .ie n \l'\\n(^lu\(ul' .el \{\ .\" Draw four-sided box normally, but don't draw top of .\" box if the box started on an earlier page. .ie !\\n(^b-1 \{\ \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .el \}\ \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .\} .fi .br .nr ^b 0 .. '\" # VS - start vertical sidebar '\" # ^Y = starting y location '\" # ^v = 1 (for troff; for nroff this doesn't matter) .de VS .mk ^Y .ie n 'mc \s12\(br\s0 .el .nr ^v 1u .. '\" # VE - end of vertical sidebar .de VE .ie n 'mc .el \{\ .ev 2 .nf .ti 0 .mk ^t \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' .sp -1 .fi .ev .\} .nr ^v 0 .. '\" # Special macro to handle page bottom: finish off current '\" # box/sidebar if in box/sidebar mode, then invoked standard '\" # page bottom macro. .de ^B .ev 2 'ti 0 'nf .mk ^t .if \\n(^b \{\ .\" Draw three-sided box if this is the box's first page, .\" draw two sides but no top otherwise. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .\} .if \\n(^v \{\ .nr ^x \\n(^tu+1v-\\n(^Yu \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c .\} .bp 'fi .ev .if \\n(^b \{\ .mk ^y .nr ^b 2 .\} .if \\n(^v \{\ .mk ^Y .\} .. '\" # DS - begin display .de DS .RS .nf .sp .. '\" # DE - end display .de DE .fi .RE .sp .. itcl2.2/itcl/mac/ 40755 1751 0 0 6423554702 12435 5ustar kunkeewheelitcl2.2/itcl/mac/CVS/ 40755 1751 0 0 6423570014 13062 5ustar kunkeewheelitcl2.2/itcl/mac/CVS/Root100644 1751 0 26 6423554701 13770 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/itcl/mac/CVS/Repository100644 1751 0 11 6423674264 15225 0ustar kunkeewheel/usr/cvs itcl2.2/itcl/mac/CVS/Entries100644 1751 0 572 6423570014 14477 0ustar kunkeewheel/itclMacApplication.r/1.1.1.1/Thu Oct 23 04:59:45 1997// /itclMacLibrary.r/1.1.1.1/Thu Oct 23 04:59:45 1997// /itclMacResource.r/1.1.1.1/Thu Oct 23 04:59:45 1997// /itclMacTclCode.r/1.1.1.1/Thu Oct 23 04:59:45 1997// /itclStaticApplication.r/1.1.1.1/Thu Oct 23 04:59:45 1997// /pkgIndex.tcl/1.1.1.1/Thu Oct 23 04:59:45 1997// /tclMacAppInit.c/1.1.1.1/Thu Oct 23 04:59:46 1997// itcl2.2/itcl/mac/itclMacApplication.r100666 1751 0 5201 6423554701 16456 0ustar kunkeewheel/* * tclMacApplication.r -- * * This file creates resources for use Tcl Shell application. * It should be viewed as an example of how to create a new * Tcl application using the shared Tcl libraries. * * Copyright (c) 1996 Sun Microsystems, Inc. * * See the file "license.terms" for information on usage and redistribution * of this file, and for a DISCLAIMER OF ALL WARRANTIES. * * SCCS: @(#) tclMacApplication.r 1.1 96/09/11 21:12:54 */ #include #include /* * The folowing include and defines help construct * the version string for Tcl. */ #define RESOURCE_INCLUDED #include "tcl.h" #include "itcl.h" #include "itclPatch.h" /* Should really have one of these in itcl too, but for now... */ #if (TCL_RELEASE_LEVEL == 0) # define RELEASE_LEVEL alpha #elif (TCL_RELEASE_LEVEL == 1) # define RELEASE_LEVEL beta #elif (TCL_RELEASE_LEVEL == 2) # define RELEASE_LEVEL final #endif #if (TCL_RELEASE_LEVEL == 2) # define MINOR_VERSION (ITCL_MINOR_VERSION * 16) + TCL_RELEASE_SERIAL #else # define MINOR_VERSION ITCL_MINOR_VERSION * 16 #endif resource 'vers' (1) { ITCL_MAJOR_VERSION, MINOR_VERSION, RELEASE_LEVEL, 0x00, verUS, ITCL_PATCH_LEVEL, ITCL_PATCH_LEVEL ", by Michael McLennan © Lucent Technologies" }; resource 'vers' (2) { ITCL_MAJOR_VERSION, MINOR_VERSION, RELEASE_LEVEL, 0x00, verUS, ITCL_PATCH_LEVEL, "Itcl Shell " ITCL_PATCH_LEVEL " © 1996" }; #define ITCL_APP_CREATOR 'ITcL' type ITCL_APP_CREATOR as 'STR '; resource ITCL_APP_CREATOR (0, purgeable) { "Itcl Shell " ITCL_PATCH_LEVEL " © 1996" }; /* * The 'kind' resource works with a 'BNDL' in Macintosh Easy Open * to affect the text the Finder displays in the "kind" column and * file info dialog. This information will be applied to all files * with the listed creator and type. */ resource 'kind' (128, "Itcl kind", purgeable) { ITCL_APP_CREATOR, 0, /* region = USA */ { 'APPL', "Itcl Shell", } }; /* * The following resource is used when creating the 'env' variable in * the Macintosh environment. The creation mechanisim looks for the * 'STR#' resource named "Tcl Environment Variables" rather than a * specific resource number. (In other words, feel free to change the * resource id if it conflicts with your application.) Each string in * the resource must be of the form "KEYWORD=SOME STRING". See Tcl * documentation for futher information about the env variable. * * A good example of something you may want to set is: "TCL_LIBRARY=My * disk:etc." */ resource 'STR#' (128, "Tcl Environment Variables") { { "SCHEDULE_NAME=Agent Controller Schedule", "SCHEDULE_PATH=Lozoya:System Folder:Tcl Lib:Tcl-Scheduler" }; }; itcl2.2/itcl/mac/itclMacLibrary.r100666 1751 0 10420 6423554701 15636 0ustar kunkeewheel/* * tclMacLibrary.r -- * * This file creates resources used by the Tcl shared library. * Many thanks go to "Jay Lieske, Jr." who * wrote the initial version of this file. * * Copyright (c) 1996 Sun Microsystems, Inc. * * See the file "license.terms" for information on usage and redistribution * of this file, and for a DISCLAIMER OF ALL WARRANTIES. * * SCCS: @(#) tclMacLibrary.r 1.3 96/09/12 17:40:07 */ #include #include /* * The folowing include and defines help construct * the version string for Tcl. */ #define RESOURCE_INCLUDED #include "tcl.h" #include "itcl.h" #include "itclPatch.h" #if (TCL_RELEASE_LEVEL == 0) # define RELEASE_LEVEL alpha #elif (TCL_RELEASE_LEVEL == 1) # define RELEASE_LEVEL beta #elif (TCL_RELEASE_LEVEL == 2) # define RELEASE_LEVEL final #endif #if (TCL_RELEASE_LEVEL == 2) # define MINOR_VERSION (ITCL_MINOR_VERSION * 16) + TCL_RELEASE_SERIAL #else # define MINOR_VERSION ITCL_MINOR_VERSION * 16 #endif resource 'vers' (1) { ITCL_MAJOR_VERSION, MINOR_VERSION, RELEASE_LEVEL, 0x00, verUS, ITCL_PATCH_LEVEL, ITCL_PATCH_LEVEL ", by Michael McLennan © Lucent Technologies" }; resource 'vers' (2) { ITCL_MAJOR_VERSION, MINOR_VERSION, RELEASE_LEVEL, 0x00, verUS, ITCL_PATCH_LEVEL, "Itcl Shell " ITCL_PATCH_LEVEL " © 1996" }; /* * Currently the creator for all Tcl/Tk libraries and extensions * should be 'TclL'. This will allow those extension and libraries * to use the common icon for Tcl extensions. However, this signature * still needs to be approved by the signature police at Apple and may * change. */ #define ITCL_CREATOR 'ITcL' #define TCL_LIBRARY_RESOURCES 2000 #define ITCL_LIBRARY_RESOURCES 2000 /* * The 'BNDL' resource is the primary link between a file's * creator/type and its icon. This resource acts for all Tcl shared * libraries; other libraries will not need one and ought to use * custom icons rather than new file types for a different appearance. */ resource 'BNDL' (TCL_LIBRARY_RESOURCES, "Tcl bundle", purgeable) { ITCL_CREATOR, 0, { /* array TypeArray: 2 elements */ /* [1] */ 'FREF', { /* array IDArray: 1 elements */ /* [1] */ 0, TCL_LIBRARY_RESOURCES }, /* [2] */ 'ICN#', { /* array IDArray: 1 elements */ /* [1] */ 0, TCL_LIBRARY_RESOURCES } } }; resource 'FREF' (TCL_LIBRARY_RESOURCES, purgeable) { 'shlb', 0, "" }; type ITCL_CREATOR as 'STR '; resource ITCL_CREATOR (0, purgeable) { "Itcl Library " ITCL_PATCH_LEVEL " © 1996" }; /* * The 'kind' resource works with a 'BNDL' in Macintosh Easy Open * to affect the text the Finder displays in the "kind" column and * file info dialog. This information will be applied to all files * with the listed creator and type. */ resource 'kind' (TCL_LIBRARY_RESOURCES, "Itcl kind", purgeable) { ITCL_CREATOR, 0, /* region = USA */ { 'shlb', "Itcl Library" } }; /* * The -16397 string will be displayed by Finder when a user * tries to open the shared library. The string should * give the user a little detail about the library's capabilities * and enough information to install the library in the correct location. * A similar string should be placed in all shared libraries. */ resource 'STR ' (-16397, purgeable) { "Itcl Library\n\n" "This is one of the libraries needed to run the Itcl flavor of the Tool Command Language programs. " "To work properly, it should be placed in the ÔTool Command LanguageÕ folder " "within the Extensions folder." }; /* * The mechanisim below loads Tcl source into the resource fork of the * application. The example below creates a TEXT resource named * "Init" from the file "init.tcl". This allows applications to use * Tcl to define the behavior of the application without having to * require some predetermined file structure - all needed Tcl "files" * are located within the application. To source a file for the * resource fork the source command has been modified to support * sourcing from resources. In the below case "source -rsrc {Init}" * will load the TEXT resource named "Init". */ #include "itclMacTclCode.r" data 'TEXT' (ITCL_LIBRARY_RESOURCES+1,"pkgIndex",purgeable, preload) { "# Tcl package index file, version 1.0\n" "package ifneeded Itcl 2.2 [list load [file join $dir itcl2.2[info sharedlibextension]] Itcl]\n" }; itcl2.2/itcl/mac/itclMacResource.r100666 1751 0 6023 6423554701 16005 0ustar kunkeewheel/* * tclMacResource.r -- * * This file creates resources for use in a simple shell. * This is designed to be an example of using the Tcl libraries * statically in a Macintosh Application. For an example of * of using the dynamic libraries look at tclMacApplication.r. * * Copyright (c) 1993-94 Lockheed Missle & Space Company * Copyright (c) 1994-96 Sun Microsystems, Inc. * * See the file "license.terms" for information on usage and redistribution * of this file, and for a DISCLAIMER OF ALL WARRANTIES. * * SCCS: @(#) tclMacResource.r 1.14 96/09/11 21:14:36 */ #include #include /* * The folowing include and defines help construct * the version string for Tcl. */ #define RESOURCE_INCLUDED #include "tcl.h" #include "itcl.h" #include "itclPatch.h" #if (TCL_RELEASE_LEVEL == 0) # define RELEASE_LEVEL alpha #elif (TCL_RELEASE_LEVEL == 1) # define RELEASE_LEVEL beta #elif (TCL_RELEASE_LEVEL == 2) # define RELEASE_LEVEL final #endif #if (TCL_RELEASE_LEVEL == 2) # define MINOR_VERSION (ITCL_MINOR_VERSION * 16) + TCL_RELEASE_SERIAL #else # define MINOR_VERSION ITCL_MINOR_VERSION * 16 #endif resource 'vers' (1) { ITCL_MAJOR_VERSION, MINOR_VERSION, RELEASE_LEVEL, 0x00, verUS, ITCL_PATCH_LEVEL, ITCL_PATCH_LEVEL ", by Michael McLennan © Lucent Technologies" }; resource 'vers' (2) { ITCL_MAJOR_VERSION, MINOR_VERSION, RELEASE_LEVEL, 0x00, verUS, ITCL_PATCH_LEVEL, "Simple Itcl Shell " ITCL_PATCH_LEVEL " © 1996" }; #define TCL_LIBRARY_RESOURCES 1000 #define ITCL_LIBRARY_RESOURCES 2000 /* * The mechanisim below loads Tcl source into the resource fork of the * application. The example below creates a TEXT resource named * "Init" from the file "init.tcl". This allows applications to use * Tcl to define the behavior of the application without having to * require some predetermined file structure - all needed Tcl "files" * are located within the application. To source a file for the * resource fork the source command has been modified to support * sourcing from resources. In the below case "source -rsrc {Init}" * will load the TEXT resource named "Init". */ read 'TEXT' (TCL_LIBRARY_RESOURCES, "Init", purgeable, preload) ":::tcl" TCL_VERSION ":library:init.tcl"; read 'TEXT' (ITCL_LIBRARY_RESOURCES, "itcl", purgeable,preload) "::library:itcl.tcl"; /* * The following resource is used when creating the 'env' variable in * the Macintosh environment. The creation mechanisim looks for the * 'STR#' resource named "Tcl Environment Variables" rather than a * specific resource number. (In other words, feel free to change the * resource id if it conflicts with your application.) Each string in * the resource must be of the form "KEYWORD=SOME STRING". See Tcl * documentation for futher information about the env variable. * * A good example of something you may want to set is: "TCL_LIBRARY=My * disk:etc." */ resource 'STR#' (128, "Tcl Environment Variables") { { "SCHEDULE_NAME=Agent Controller Schedule", "SCHEDULE_PATH=Lozoya:System Folder:Tcl Lib:Tcl-Scheduler" }; }; itcl2.2/itcl/mac/itclMacTclCode.r100666 1751 0 2060 6423554701 15530 0ustar kunkeewheel/* * itclMacTclCode.r * * This file includes the Itcl code that is needed to startup Tcl. * It is to be included either in the resource fork of the shared library, or in the * resource fork of the application for a statically bound application. * * Jim Ingham * Lucent Technologies 1996 * */ #include #include #define ITCL_LIBRARY_RESOURCES 2500 /* * The mechanisim below loads Tcl source into the resource fork of the * application. The example below creates a TEXT resource named * "Init" from the file "init.tcl". This allows applications to use * Tcl to define the behavior of the application without having to * require some predetermined file structure - all needed Tcl "files" * are located within the application. To source a file for the * resource fork the source command has been modified to support * sourcing from resources. In the below case "source -rsrc {Init}" * will load the TEXT resource named "Init". */ read 'TEXT' (ITCL_LIBRARY_RESOURCES, "itcl", purgeable,preload) "::library:itcl.tcl"; itcl2.2/itcl/mac/itclStaticApplication.r100666 1751 0 1240 6423554701 17204 0ustar kunkeewheel/* * itkStaticPkgIndex.r -- * * This file creates resources which bind in the static version of the * pkgIndex files. * * Copyright (c) 1996 Sun Microsystems, Inc. * * See the file "license.terms" for information on usage and redistribution * of this file, and for a DISCLAIMER OF ALL WARRANTIES. * * SCCS: @(#) tkMacLibrary.r 1.5 96/10/03 17:54:21 */ #include #include #include #define ITCL_LIBRARY_RESOURCES 2500 #include "itclMacTclCode.r" data 'TEXT' (ITCL_LIBRARY_RESOURCES+20,"itcl:pkgIndex",purgeable, preload) { "# Tcl package index file, version 1.0\n" "package ifneeded Itcl 2.2 {load {} Itcl}\n" }; itcl2.2/itcl/mac/pkgIndex.tcl100666 1751 0 203 6423554701 14765 0ustar kunkeewheel# Tcl package index file, version 1.0 package ifneeded Itcl 2.2 [list load [file join $dir itcl22[info sharedlibextension]] Itcl] itcl2.2/itcl/mac/tclMacAppInit.c100666 1751 0 12212 6423554702 15410 0ustar kunkeewheel/* * tclMacAppInit.c -- * * Provides a version of the Tcl_AppInit procedure for the example shell. * * Copyright (c) 1993-1994 Lockheed Missle & Space Company, AI Center * Copyright (c) 1995-1996 Sun Microsystems, Inc. * * See the file "license.terms" for information on usage and redistribution * of this file, and for a DISCLAIMER OF ALL WARRANTIES. * * SCCS: @(#) tclMacAppInit.c 1.15 96/09/05 18:26:31 */ #include "tcl.h" #include "tclInt.h" #include "tclPort.h" #include "tclMacInt.h" #include "itcl.h" #if defined(THINK_C) # include #elif defined(__MWERKS__) # include short InstallConsole _ANSI_ARGS_((short fd)); #endif #ifdef TCL_TEST EXTERN int Tcltest_Init _ANSI_ARGS_((Tcl_Interp *interp)); #endif /* TCL_TEST */ /* * Forward declarations for procedures defined later in this file: */ static int MacintoshInit _ANSI_ARGS_((void)); /* *---------------------------------------------------------------------- * * main -- * * Main program for tclsh. This file can be used as a prototype * for other applications using the Tcl library. * * Results: * None. This procedure never returns (it exits the process when * it's done. * * Side effects: * This procedure initializes the Macintosh world and then * calls Tcl_Main. Tcl_Main will never return except to exit. * *---------------------------------------------------------------------- */ void main(argc, argv) int argc; /* Number of arguments. */ char **argv; /* Array of argument strings. */ { char *newArgv[2]; if (MacintoshInit() != TCL_OK) { Tcl_Exit(1); } argc = 1; newArgv[0] = "tclsh"; newArgv[1] = NULL; Tcl_Main(argc, newArgv, Tcl_AppInit); } /* *---------------------------------------------------------------------- * * Tcl_AppInit -- * * This procedure performs application-specific initialization. * Most applications, especially those that incorporate additional * packages, will have their own version of this procedure. * * Results: * Returns a standard Tcl completion code, and leaves an error * message in interp->result if an error occurs. * * Side effects: * Depends on the startup script. * *---------------------------------------------------------------------- */ int Tcl_AppInit(interp) Tcl_Interp *interp; /* Interpreter for application. */ { if (Tcl_Init(interp) == TCL_ERROR) { return TCL_ERROR; } #ifdef TCL_TEST if (Tcltest_Init(interp) == TCL_ERROR) { return TCL_ERROR; } #endif /* TCL_TEST */ /* * Call the init procedures for included packages. Each call should * look like this: * * if (Mod_Init(interp) == TCL_ERROR) { * return TCL_ERROR; * } * * where "Mod" is the name of the module. */ if (Itcl_Init(interp) == TCL_ERROR) { return TCL_ERROR; } Tcl_StaticPackage(interp, "Itcl", Itcl_Init, Itcl_SafeInit); /* * Call Tcl_CreateCommand for application-specific commands, if * they weren't already created by the init procedures called above. * Each call would loo like this: * * Tcl_CreateCommand(interp, "tclName", CFuncCmd, NULL, NULL); */ /* * Specify a user-specific startup script to invoke if the application * is run interactively. On the Mac we can specifiy either a TEXT resource * which contains the script or the more UNIX like file location * may also used. (I highly recommend using the resource method.) */ Tcl_Eval(interp, "source -rsrc {itclshrc}"); Tcl_ResetResult(interp); /* Tcl_SetVar(interp, "tcl_rcFileName", "~/.itclshrc", TCL_GLOBAL_ONLY); */ return TCL_OK; } /* *---------------------------------------------------------------------- * * MacintoshInit -- * * This procedure calls initalization routines to set up a simple * console on a Macintosh. This is necessary as the Mac doesn't * have a stdout & stderr by default. * * Results: * Returns TCL_OK if everything went fine. If it didn't the * application should probably fail. * * Side effects: * Inits the appropiate console package. * *---------------------------------------------------------------------- */ static int MacintoshInit() { /* Itcl seems to be unstable, so I am trying increasing the stack to fix it... JCI - 3/28/97 */ SetApplLimit(GetApplLimit() - 64000); MaxApplZone(); #if defined(THINK_C) /* Set options for Think C console package */ /* The console package calls the Mac init calls */ console_options.pause_atexit = 0; console_options.title = "\pTcl Interpreter"; #elif defined(__MWERKS__) /* Set options for CodeWarrior SIOUX package */ SIOUXSettings.autocloseonquit = true; SIOUXSettings.showstatusline = true; SIOUXSettings.asktosaveonclose = false; InstallConsole(0); SIOUXSetTitle("\pTcl Interpreter"); #elif defined(applec) /* Init packages used by MPW SIOW package */ InitGraf((Ptr)&qd.thePort); InitFonts(); InitWindows(); InitMenus(); TEInit(); InitDialogs(nil); InitCursor(); #endif TclMacSetEventProc((TclMacConvertEventPtr) SIOUXHandleOneEvent); /* No problems with initialization */ return TCL_OK; } itcl2.2/itcl/license.terms100666 1751 0 4170 6423554674 14506 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. itcl2.2/itcl/generic/ 40755 1751 0 0 6423554700 13307 5ustar kunkeewheelitcl2.2/itcl/generic/CVS/ 40755 1751 0 0 6423570014 13736 5ustar kunkeewheelitcl2.2/itcl/generic/CVS/Root100644 1751 0 26 6423554676 14657 0ustar kunkeewheelneoworld.net:/usr/cvs itcl2.2/itcl/generic/CVS/Repository100644 1751 0 11 6423674264 16101 0ustar kunkeewheel/usr/cvs itcl2.2/itcl/generic/CVS/Entries100644 1751 0 1032 6423570014 15363 0ustar kunkeewheel/itcl.h/1.1.1.1/Thu Oct 23 04:59:42 1997// /itclInt.h/1.1.1.1/Thu Oct 23 04:59:42 1997// /itcl_bicmds.c/1.1.1.1/Thu Oct 23 04:59:42 1997// /itcl_class.c/1.1.1.1/Thu Oct 23 04:59:42 1997// /itcl_cmds.c/1.1.1.1/Thu Oct 23 04:59:42 1997// /itcl_linkage.c/1.1.1.1/Thu Oct 23 04:59:43 1997// /itcl_methods.c/1.1.1.1/Thu Oct 23 04:59:43 1997// /itcl_objects.c/1.1.1.1/Thu Oct 23 04:59:43 1997// /itcl_obsolete.c/1.1.1.1/Thu Oct 23 04:59:44 1997// /itcl_parse.c/1.1.1.1/Thu Oct 23 04:59:44 1997// /itcl_util.c/1.1.1.1/Thu Oct 23 04:59:44 1997// itcl2.2/itcl/generic/itclInt.h100666 1751 0 34305 6423554676 15230 0ustar kunkeewheel/* * ------------------------------------------------------------------------ * PACKAGE: [incr Tcl] * DESCRIPTION: Object-Oriented Extensions to Tcl * * [incr Tcl] provides object-oriented extensions to Tcl, much as * C++ provides object-oriented extensions to C. It provides a means * of encapsulating related procedures together with their shared data * in a local namespace that is hidden from the outside world. It * promotes code re-use through inheritance. More than anything else, * it encourages better organization of Tcl applications through the * object-oriented paradigm, leading to code that is easier to * understand and maintain. * * This file includes all declarations used internally by this * package. * * ======================================================================== * AUTHOR: Michael J. McLennan * Bell Labs Innovations for Lucent Technologies * mmclennan@lucent.com * http://www.tcltk.com/itcl * * RCS: $Id: itclInt.h,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ * ======================================================================== * Copyright (c) 1993-1996 Lucent Technologies * ------------------------------------------------------------------------ * See the file "license.terms" for information on usage and redistribution * of this file, and for a DISCLAIMER OF ALL WARRANTIES. */ #ifndef ITCLINT_H #define ITCLINT_H #ifndef ITCL_H #include "itcl.h" #endif #include "tclInt.h" /* * Common info for managing all known objects... */ typedef struct ItclObjectInfo { Tcl_Interp *interp; /* interpreter that manages this info */ Tcl_HashTable objects; /* list of all known objects */ Itcl_Stack cdefnStack; /* stack of class definitions being parsed */ } ItclObjectInfo; /* * Representation for each class... */ typedef struct ItclClass { char *name; /* class name */ Tcl_Interp *interp; /* interpreter that manages this info */ Itcl_Namespace namesp; /* namespace representing class scope */ Tcl_Command accessCmd; /* access command for creating instances */ /* ---- private stuff below this line ---- */ struct ItclObjectInfo *info; /* info about all known objects */ Itcl_List bases; /* list of base classes */ Itcl_List derived; /* list of all derived classes */ char *initCmd; /* initialization command for new objs */ Tcl_HashTable variables; /* var definitions for all data members */ int instanceVars; /* number of instance vars in virtualData */ Tcl_HashTable virtualData; /* most-specific vars for this class */ Tcl_HashTable virtualMethods; /* most-specific methods for this class */ int unique; /* unique number for #auto generation */ int flags; /* maintains class status */ } ItclClass; /* * Representation for each object... */ typedef struct ItclObject { ItclClass *cdefn; /* most-specific class */ Tcl_Command accessCmd; /* object access command */ /* ---- private stuff below this line ---- */ int dataSize; /* number of elements in data array */ Var** data; /* all object-specific data members */ Tcl_HashTable* constructed; /* temp storage used during construction */ Tcl_HashTable* destructed; /* temp storage used during destruction */ } ItclObject; #define ITCL_IGNORE_ERRS 0x002 /* useful for construction/destruction */ /* * COMMAND MEMBER IMPLEMENTATION */ typedef struct ItclCmdImplement { int flags; /* flags describing implementation */ Arg *arglist; /* list of arg names and initial values */ char *body; /* body of Tcl statements or "@proc" */ Tcl_CmdProc *proc; /* C procedure implementation or NULL */ } ItclCmdImplement; /* * Flag bits for ItclCmdImplement: */ #define ITCL_IMPLEMENT_NONE 0x001 /* no implementation */ #define ITCL_IMPLEMENT_TCL 0x002 /* Tcl implementation for body */ #define ITCL_IMPLEMENT_C 0x004 /* C implementation for body */ /* * COMMAND MEMBERS */ typedef struct ItclCmdMember { Tcl_Interp* interp; /* interpreter containing this command */ ItclClass* cdefn; /* class containing this command */ char* name; /* member name */ char* fullname; /* member name with "class::" qualifier */ int protection; /* protection level */ int flags; /* flags describing member (see below) */ ItclCmdImplement* implement; /* implementation */ Arg *arglist; /* list of arg names and initial values */ } ItclCmdMember; /* * Flag bits for ItclCmdMember: */ #define ITCL_CONSTRUCTOR 0x001 /* non-zero => is a constructor */ #define ITCL_DESTRUCTOR 0x002 /* non-zero => is a destructor */ #define ITCL_COMMON 0x004 /* non-zero => is a "proc" */ #define ITCL_ARG_SPEC 0x008 /* non-zero => has an argument spec */ #define ITCL_OLD_STYLE 0x010 /* non-zero => old-style method */ /* (process "config" argument) */ /* * VARIABLE DEFINITION */ typedef struct ItclVarDefn { char* name; /* variable name */ char* fullname; /* variable name with "class::" qualifier */ int flags; /* ITCL_COMMON => common variable */ /* ITCL_THIS_VAR => built-in "this" variable */ char* init; /* initial value */ ItclCmdImplement* config; /* code invoked when value is configured */ ItclClass* cdefn; /* class containing this variable */ int protection; /* protect level for variable */ } ItclVarDefn; #define ITCL_THIS_VAR 0x010 /* non-zero => built-in "this" variable */ /* * VARIABLE LOOKUP ENTRY */ typedef struct ItclVarLookup { int usage; /* number of uses for this record */ ItclVarDefn* vdefn; /* variable definition */ int accessible; /* non-zero => accessible from class with * this lookup record in its virtualData */ int vindex; /* index into virtual table (instance data) */ Tcl_Var var; /* variable (common data) */ } ItclVarLookup; /* * Functions used within the package, but not considered "public"... */ EXTERN int Itcl_InfoClassesCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp* interp, int argc, char** argv)); EXTERN int Itcl_InfoObjectsCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp* interp, int argc, char** argv)); EXTERN int Itcl_DelClassCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp* interp, int argc, char** argv)); EXTERN int Itcl_DelObjectCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp* interp, int argc, char** argv)); /* * Functions for manipulating classes... */ EXTERN int Itcl_CreateClass _ANSI_ARGS_((Tcl_Interp* interp, char* name, ItclObjectInfo *info, Itcl_Namespace* nsPtr)); EXTERN int Itcl_DeleteClass _ANSI_ARGS_((Tcl_Interp* interp, Itcl_Namespace ns)); EXTERN int Itcl_HandleClass _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ClassVarEnforcer _ANSI_ARGS_((Tcl_Interp* interp, char* name, Tcl_Var* varPtr, int flags)); EXTERN int Itcl_ClassUnknownCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN void Itcl_BuildVirtualTables _ANSI_ARGS_((ItclClass* cdefnPtr)); EXTERN int Itcl_CreateVarDefn _ANSI_ARGS_((Tcl_Interp *interp, Itcl_Class* cdefn, char* name, char* init, char* config, ItclVarDefn** vdefn)); EXTERN void Itcl_DeleteVarDefn _ANSI_ARGS_((ItclVarDefn *vdefn)); EXTERN int Itcl_FindVarDefn _ANSI_ARGS_((Tcl_Interp *interp, Itcl_Class* cdefn, char* name, ItclVarDefn **vdefnPtr)); EXTERN int Itcl_FindCmdDefn _ANSI_ARGS_((Tcl_Interp *interp, Itcl_Class* cdefn, char* name, ItclCmdMember **mdefnPtr)); EXTERN int Itcl_CanAccessMethod _ANSI_ARGS_((ItclCmdMember *mdefn, Itcl_Namespace ns)); EXTERN char* Itcl_GetCommonVar _ANSI_ARGS_((Tcl_Interp *interp, char* name, Itcl_Class* scope)); /* * Functions for manipulating objects... */ EXTERN int Itcl_CreateObject _ANSI_ARGS_((Tcl_Interp *interp, char* name, Itcl_Class *cdefn, int argc, char** argv, Itcl_Object **objPtr)); EXTERN int Itcl_DeleteObject _ANSI_ARGS_((Tcl_Interp *interp, Itcl_Object* obj)); EXTERN int Itcl_DestructObject _ANSI_ARGS_((Tcl_Interp *interp, Itcl_Object* obj, int flags)); EXTERN int Itcl_HandleInstance _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN char* Itcl_GetInstanceVar _ANSI_ARGS_((Tcl_Interp *interp, char* name, Itcl_Object* obj, Itcl_Class* scope)); /* * Functions for manipulating methods and procs... */ EXTERN int Itcl_BodyCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ConfigBodyCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_CreateMethod _ANSI_ARGS_((Tcl_Interp* interp, Itcl_Class *cdefn, char* name, char* arglist, char* body)); EXTERN int Itcl_CreateProc _ANSI_ARGS_((Tcl_Interp* interp, Itcl_Class *cdefn, char* name, char* arglist, char* body)); EXTERN int Itcl_CreateCmdMember _ANSI_ARGS_((Tcl_Interp* interp, Itcl_Class *cdefn, char* name, char* arglist, char* body, ItclCmdMember** mdefnPtr)); EXTERN int Itcl_ChangeCmdMember _ANSI_ARGS_((Tcl_Interp* interp, ItclCmdMember* mdefn, char* arglist, char* body)); EXTERN void Itcl_DeleteCmdMember _ANSI_ARGS_((ClientData cdata)); EXTERN int Itcl_CreateCmdImplement _ANSI_ARGS_((Tcl_Interp* interp, char* arglist, char* body, ItclCmdImplement** mimplPtr)); EXTERN void Itcl_DeleteCmdImplement _ANSI_ARGS_((ClientData cdata)); EXTERN int Itcl_GetCmdImplement _ANSI_ARGS_((Tcl_Interp* interp, ItclCmdMember* mdefn, ItclCmdImplement** mimplPtr)); EXTERN int Itcl_EvalCmdImplement _ANSI_ARGS_((Tcl_Interp* interp, ItclCmdMember* mdefn, ItclCmdImplement* mimpl, int argc, char** argv)); EXTERN int Itcl_CreateArgList _ANSI_ARGS_((Tcl_Interp* interp, char* decl, Arg** argPtr)); EXTERN Arg* Itcl_CreateArg _ANSI_ARGS_((char* name, char* init)); EXTERN void Itcl_DeleteArgList _ANSI_ARGS_((Arg* arg)); EXTERN char* Itcl_ArgList _ANSI_ARGS_((Arg* arg)); EXTERN int Itcl_EquivArgLists _ANSI_ARGS_((Arg* arg1, Arg* arg2)); EXTERN char* Itcl_GetCmdMemberUsage _ANSI_ARGS_((ItclCmdMember* mdefn, Itcl_Object* obj)); EXTERN int Itcl_ExecMethod _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ExecProc _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ConstructBase _ANSI_ARGS_((Tcl_Interp *interp, struct Itcl_Object* odefn, struct Itcl_Class* cdefn)); EXTERN int Itcl_ParseArgs _ANSI_ARGS_((Tcl_Interp* interp, int argc, char** argv, ItclCmdMember *mdefn, ItclCmdImplement* mimpl, int flags)); /* * Commands for parsing class definitions... */ EXTERN int Itcl_ParseInit _ANSI_ARGS_((Tcl_Interp* interp, ItclObjectInfo* info)); EXTERN int Itcl_ClassCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ClassInheritCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ClassConstructorCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ClassDestructorCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ClassMethodCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ClassProcCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ClassVariableCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ClassCommonCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ClassProtectionCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_ParseVarEnforcer _ANSI_ARGS_((Tcl_Interp* interp, char* name1, Tcl_Var* varPtr, int flags)); /* * Commands in the "builtin" namespace... */ EXTERN int Itcl_BiInit _ANSI_ARGS_((Tcl_Interp *interp)); EXTERN int Itcl_InstallBiMethods _ANSI_ARGS_((Tcl_Interp *interp, Itcl_Class *cdefn)); EXTERN int Itcl_BiIsaCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_BiConfigureCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_BiCgetCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_BiChainCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_BiInfoClassCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_BiInfoInheritCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_BiInfoHeritageCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_BiInfoFunctionCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_BiInfoVariableCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_BiInfoArgsCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_BiInfoBodyCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Itcl_DefaultInfoCmd _ANSI_ARGS_((ClientData cdata, Tcl_Interp *interp, int argc, char** argv)); /* * Utility functions... */ EXTERN void Itcl_InstallCallFrame _ANSI_ARGS_((Tcl_Interp *interp, CallFrame* frame, int argc, char** argv)); EXTERN void Itcl_RemoveCallFrame _ANSI_ARGS_((Tcl_Interp *interp)); EXTERN char* Itcl_GetCallFrameCmd _ANSI_ARGS_((Tcl_Interp *interp)); /* * Commands provided for backward compatibility... */ EXTERN int Itcl_OldInit _ANSI_ARGS_((Tcl_Interp* interp, ItclObjectInfo* info)); EXTERN int Itcl_InstallOldBiMethods _ANSI_ARGS_((Tcl_Interp *interp, Itcl_Class *cdefn)); #endif itcl2.2/itcl/generic/itcl.h100666 1751 0 11764 6423554676 14561 0ustar kunkeewheel/* * ------------------------------------------------------------------------ * PACKAGE: [incr Tcl] * DESCRIPTION: Object-Oriented Extensions to Tcl * * [incr Tcl] provides object-oriented extensions to Tcl, much as * C++ provides object-oriented extensions to C. It provides a means * of encapsulating related procedures together with their shared data * in a local namespace that is hidden from the outside world. It * promotes code re-use through inheritance. More than anything else, * it encourages better organization of Tcl applications through the * object-oriented paradigm, leading to code that is easier to * understand and maintain. * * ADDING [incr Tcl] TO A Tcl-BASED APPLICATION: * * To add [incr Tcl] facilities to a Tcl application, modify the * Tcl_AppInit() routine as follows: * * 1) Include this header file near the top of the file containing * Tcl_AppInit(): * * #include "itcl.h" * * 2) Within the body of Tcl_AppInit(), add the following lines: * * if (Itcl_Init(interp) == TCL_ERROR) { * return TCL_ERROR; * } * * 3) Link your application with libitcl.a * * NOTE: An example file "tclAppInit.c" containing the changes shown * above is included in this distribution. * * ======================================================================== * AUTHOR: Michael J. McLennan * Bell Labs Innovations for Lucent Technologies * mmclennan@lucent.com * http://www.tcltk.com/itcl * * RCS: $Id: itcl.h,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ * ======================================================================== * Copyright (c) 1993-1996 Lucent Technologies * ------------------------------------------------------------------------ * See the file "license.terms" for information on usage and redistribution * of this file, and for a DISCLAIMER OF ALL WARRANTIES. */ #ifndef ITCL_H #define ITCL_H #include "tcl.h" #define ITCL_VERSION "2.2" #define ITCL_MAJOR_VERSION 2 #define ITCL_MINOR_VERSION 2 #define ITCL_RELEASE_LEVEL 2 #define ITCL_RELEASE_SERIAL 2 #define ITCL_PATCH_LEVEL "2.2p2" /* * A special definition used to allow this header file to be included * in resource files so that they can get obtain version information from * this file. Resource compilers don't like all the C stuff, like typedefs * and procedure declarations, that occur below. */ #ifndef RESOURCE_INCLUDED /* * Data structures defined opaquely in this module. * * NOTE: Any change to the structures below must be mirrored * in their "real" definition in itclInt.h. */ typedef struct Itcl_Class { char *name; /* class name */ Tcl_Interp *interp; /* interpreter that manages this info */ Itcl_Namespace namesp; /* namespace representing class scope */ Tcl_Command accessCmd; /* access command for creating instances */ } Itcl_Class; typedef struct Itcl_Object { Itcl_Class *cdefn; /* most-specific class */ Tcl_Command accessCmd; /* object access command */ } Itcl_Object; typedef struct Itcl_HierIter { Itcl_Class *current; /* current position in hierarchy */ Itcl_Stack stack; /* stack used for traversal */ } Itcl_HierIter; #if defined(__WIN32__) # define WIN32_LEAN_AND_MEAN # include # undef WIN32_LEAN_AND_MEAN /* * VC++ has an alternate entry point called DllMain, so we need to rename * our entry point. */ # undef EXPORT # undef DllEntryPoint # if defined(_MSC_VER) # define EXPORT(a,b) __declspec(dllexport) a b # define DllEntryPoint DllMain # else # if defined(__BORLANDC__) # define EXPORT(a,b) a _export b # else # define EXPORT(a,b) a b # endif # endif #else # define EXPORT(a,b) a b #endif /* * Exported functions (public interface to this package) */ EXTERN EXPORT(int,Itcl_Init) _ANSI_ARGS_((Tcl_Interp *interp)); EXTERN EXPORT(int,Itcl_SafeInit) _ANSI_ARGS_((Tcl_Interp *interp)); EXTERN int Itcl_RegisterC _ANSI_ARGS_((Tcl_Interp* interp, char *name, Tcl_CmdProc *proc)); EXTERN Tcl_CmdProc* Itcl_FindC _ANSI_ARGS_((Tcl_Interp* interp, char *name)); EXTERN int Itcl_IsClass _ANSI_ARGS_((Itcl_Namespace ns)); EXTERN int Itcl_FindClass _ANSI_ARGS_((Tcl_Interp* interp, char* path, Itcl_Namespace* nsPtr)); EXTERN int Itcl_FindObject _ANSI_ARGS_((Tcl_Interp* interp, char* name, Itcl_Object** objPtr)); EXTERN int Itcl_IsObject _ANSI_ARGS_((Tcl_Command cmd)); EXTERN int Itcl_ObjectIsa _ANSI_ARGS_((Itcl_Object* obj, Itcl_Class* cdefn)); EXTERN int Itcl_GetClassContext _ANSI_ARGS_((Tcl_Interp* interp, Itcl_Namespace* classNsPtr, Itcl_Class** cdefnPtr, Itcl_Object** odefnPtr)); EXTERN void Itcl_InitHierIter _ANSI_ARGS_((Itcl_HierIter *iter, Itcl_Class *cdefn)); EXTERN void Itcl_DeleteHierIter _ANSI_ARGS_((Itcl_HierIter *iter)); EXTERN Itcl_Class* Itcl_AdvanceHierIter _ANSI_ARGS_((Itcl_HierIter *iter)); #endif /* RESOURCE INCLUDED */ #endif /* ITCL_H */ itcl2.2/itcl/generic/itcl_bicmds.c100666 1751 0 135222 6423554676 16111 0ustar kunkeewheel/* * ------------------------------------------------------------------------ * PACKAGE: [incr Tcl] * DESCRIPTION: Object-Oriented Extensions to Tcl * * [incr Tcl] provides object-oriented extensions to Tcl, much as * C++ provides object-oriented extensions to C. It provides a means * of encapsulating related procedures together with their shared data * in a local namespace that is hidden from the outside world. It * promotes code re-use through inheritance. More than anything else, * it encourages better organization of Tcl applications through the * object-oriented paradigm, leading to code that is easier to * understand and maintain. * * These procedures handle built-in class methods, including the * "isa" method (to query hierarchy info) and the "info" method * (to query class/object data). * * ======================================================================== * AUTHOR: Michael J. McLennan * Bell Labs Innovations for Lucent Technologies * mmclennan@lucent.com * http://www.tcltk.com/itcl * * RCS: $Id: itcl_bicmds.c,v 1.1.1.1 1997/10/20 03:58:23 kunkee Exp $ * ======================================================================== * Copyright (c) 1993-1996 Lucent Technologies * ------------------------------------------------------------------------ * See the file "license.terms" for information on usage and redistribution * of this file, and for a DISCLAIMER OF ALL WARRANTIES. */ #include #include "itclInt.h" /* * Standard list of built-in methods for all objects. */ typedef struct BiMethod { char* name; /* method name */ char* usage; /* string describing usage */ char* registration; /* registration name for C proc */ Tcl_CmdProc *proc; /* implementation C proc */ } BiMethod; static BiMethod BiMethodList[] = { { "cget", "-option", "@itcl-builtin-cget", Itcl_BiCgetCmd }, { "configure", "?-option? ?value -option value...?", "@itcl-builtin-configure", Itcl_BiConfigureCmd }, { "isa", "className", "@itcl-builtin-isa", Itcl_BiIsaCmd }, }; static int BiMethodListLen = sizeof(BiMethodList)/sizeof(BiMethod); /* * FORWARD DECLARATIONS */ static char* ItclReportPublicOpt _ANSI_ARGS_((Tcl_Interp *interp, ItclVarDefn *vdefn, Itcl_Object *obj)); /* * ------------------------------------------------------------------------ * Itcl_BiInit() * * Creates a namespace full of built-in methods/procs for [incr Tcl] * classes. This includes things like the "isa" method and "info" * for querying class info. Usually invoked by Itcl_Init() when * [incr Tcl] is first installed into an interpreter. * * Returns TCL_OK/TCL_ERROR to indicate success/failure. * ------------------------------------------------------------------------ */ int Itcl_BiInit(interp) Tcl_Interp *interp; /* current interpreter */ { int i; Itcl_Namespace ns; /* * Declare all of the built-in methods as C procedures. */ for (i=0; i < BiMethodListLen; i++) { if (Itcl_RegisterC(interp, BiMethodList[i].registration+1, BiMethodList[i].proc) != TCL_OK) { return TCL_ERROR; } } /* * Create the "::itcl::builtin" namespace for built-in class * commands. Make this an isolated namespace. It is simply * an extra bag of commands imported into each class. */ if (Itcl_CreateNamesp(interp, "::itcl::builtin", (ClientData)NULL, (Itcl_DeleteProc*)NULL, &ns) != TCL_OK) { Tcl_AppendResult(interp, " (cannot initialize itcl built-in commands)", (char*)NULL); return TCL_ERROR; } Itcl_ClearImportNamesp(ns); Tcl_CreateCommand(interp, "::itcl::builtin::chain", Itcl_BiChainCmd, (ClientData)NULL, (Itcl_DeleteProc*)NULL); /* * Create an "info" ensemble in the global namespace, and * install subcommands needed for [incr Tcl]. */ if (Itcl_CreateEnsemble(interp, "::itcl::builtin::info") != TCL_OK) { return TCL_ERROR; } if (Itcl_AddEnsembleOption(interp, "::itcl::builtin::info", "class", 0, 0, (char*)NULL, Itcl_BiInfoClassCmd, (ClientData)NULL, (Tcl_CmdDeleteProc*)NULL) != TCL_OK || Itcl_AddEnsembleOption(interp, "::itcl::builtin::info", "inherit", 0, 0, (char*)NULL, Itcl_BiInfoInheritCmd, (ClientData)NULL, (Tcl_CmdDeleteProc*)NULL) != TCL_OK || Itcl_AddEnsembleOption(interp, "::itcl::builtin::info", "heritage", 0, 0, (char*)NULL, Itcl_BiInfoHeritageCmd, (ClientData)NULL, (Tcl_CmdDeleteProc*)NULL) != TCL_OK || Itcl_AddEnsembleOption(interp, "::itcl::builtin::info", "function", 0, ITCL_VAR_ARGS, "?name? ?-protection? ?-type? ?-name? ?-args? ?-body?", Itcl_BiInfoFunctionCmd, (ClientData)NULL, (Tcl_CmdDeleteProc*)NULL) != TCL_OK || Itcl_AddEnsembleOption(interp, "::itcl::builtin::info", "variable", 0, ITCL_VAR_ARGS, "?name? ?-protection? ?-type? ?-name? ?-init? ?-value? ?-config?", Itcl_BiInfoVariableCmd, (ClientData)NULL, (Tcl_CmdDeleteProc*)NULL) != TCL_OK || Itcl_AddEnsembleOption(interp, "::itcl::builtin::info", "args", 1, 1, "procname", Itcl_BiInfoArgsCmd, (ClientData)NULL, (Tcl_CmdDeleteProc*)NULL) != TCL_OK || Itcl_AddEnsembleOption(interp, "::itcl::builtin::info", "body", 1, 1, "procname", Itcl_BiInfoBodyCmd, (ClientData)NULL, (Tcl_CmdDeleteProc*)NULL) != TCL_OK ) { return TCL_ERROR; } /* * Add an error handler to support all of the usual inquiries * for the "info" command in the global namespace. */ if (Itcl_AddEnsembleOption(interp, "::itcl::builtin::info", "@error", 0, ITCL_VAR_ARGS, (char*)NULL, Itcl_DefaultInfoCmd, (ClientData)NULL, (Tcl_CmdDeleteProc*)NULL) != TCL_OK ) { return TCL_ERROR; } return TCL_OK; } /* * ------------------------------------------------------------------------ * Itcl_InstallBiMethods() * * Invoked when a class is first created, just after the class * definition has been parsed, to add definitions for built-in * methods to the class. If a method already exists in the class * with the same name as the built-in, then the built-in is skipped. * Otherwise, a method definition for the built-in method is added. * * Returns TCL_OK if successful, or TCL_ERROR (along with an error * message in the interpreter) if anything goes wrong. * ------------------------------------------------------------------------ */ int Itcl_InstallBiMethods(interp,cdefn) Tcl_Interp *interp; /* current interpreter */ Itcl_Class *cdefn; /* class definition to be updated */ { int status = TCL_OK; int i; ItclCmdMember *mdefn; /* * Scan through all of the built-in methods and see if * that method already exists in the class. If not, add * it in. */ for (i=0; i < BiMethodListLen; i++) { status = Itcl_FindCmdDefn(interp, cdefn, BiMethodList[i].name, &mdefn); if (status != TCL_OK) { break; } if (!mdefn) { status = Itcl_CreateMethod(interp, cdefn, BiMethodList[i].name, BiMethodList[i].usage, BiMethodList[i].registration); if (status != TCL_OK) { break; } } } return status; } /* * ------------------------------------------------------------------------ * Itcl_BiIsaCmd() * * Invoked whenever the user issues the "isa" method for an object. * Handles the following syntax: * * isa * * Checks to see if the object has the given anywhere * in its heritage. Returns 1 if so, and 0 otherwise. * ------------------------------------------------------------------------ */ /* ARGSUSED */ int Itcl_BiIsaCmd(clientData, interp, argc, argv) ClientData clientData; /* class definition */ Tcl_Interp *interp; /* current interpreter */ int argc; /* number of arguments */ char **argv; /* argument strings */ { Itcl_Namespace classNs; Itcl_Class *cdefn; Itcl_Object *obj; /* * Make sure that this command is being invoked in the proper * context. */ if ((Itcl_GetClassContext(interp, &classNs, &cdefn, &obj) != TCL_OK) || !obj) { Tcl_AppendResult(interp, "improper usage: should be ", "\"object isa className\"", (char*)NULL); return TCL_ERROR; } if (argc != 2) { Tcl_AppendResult(interp, "wrong # args: should be \"", "object ", argv[0], " className\"", (char*)NULL); return TCL_ERROR; } /* * Look for the requested class. If it is not found, then * try to autoload it. If it absolutely cannot be found, * signal an error. */ if (Itcl_FindClass(interp, argv[1], &classNs) != TCL_OK) { return TCL_ERROR; } if (classNs == NULL) { if (Tcl_VarEval(interp, "::auto_load ", argv[1], (char*)NULL) != TCL_OK) { char msg[256]; sprintf(msg, "\n (while attempting to autoload class \"%.200s\")", argv[1]); Tcl_AddErrorInfo(interp, msg); return TCL_ERROR; } Tcl_ResetResult(interp); if (Itcl_FindClass(interp, argv[1], &classNs) != TCL_OK) { return TCL_ERROR; } if (classNs == NULL) { Tcl_AppendResult(interp, "class \"", argv[1], "\" not found in context \"", Itcl_GetNamespPath(Itcl_GetActiveNamesp(interp)), "\"", (char*)NULL); return TCL_ERROR; } } cdefn = (Itcl_Class*)Itcl_GetNamespData(classNs); if (Itcl_ObjectIsa(obj,cdefn)) Tcl_SetResult(interp, "1", TCL_STATIC); else Tcl_SetResult(interp, "0", TCL_STATIC); return TCL_OK; } /* * ------------------------------------------------------------------------ * Itcl_BiConfigureCmd() * * Invoked whenever the user issues the "configure" method for an object. * Handles the following syntax: * * configure ?-