Contents Tcl/Tk Reference Guidetitania.ctie.monash.edu.au/refcards/rfk-0013.pdf · Tcl/Tk Reference...

Tcl/TkR

eferenceG

uide

Notes

Tcl/T

kp

rog

ramd

esign

edan

dcreated

by

Joh

nO

usterh

ou

t <john.o

uste

rhou

t@eng

.sun.co

m>

Referen

ceg

uid

efo

rmatd

esign

edan

dcreated

by

Joh

anV

rom

ans<

jvrom

ans@

squirre

l.nl>

Th

isg

uid

en

amed<

tkref-4

.1.0

.tar.g

z>fo

un

dat

<ftp

://ftp.sla

c.stanfo

rd.e

du/so

ftware

/TkM

ail/>

Tcl/T

kR

eference

Gu

ide

Revisio

n4

.1.0

c

19

89

,19

96

44

Zentralinstitutf

urA

ngewandte

Mathem

atikD

-52425Julich,Tel.(02461)61–6402

Informationszentrum

,Tel.(02461)61–6658R

eferenzkarteK

FA-Z

AM

-RF

K-0

01

32

0.0

3.1

99

7

Tcl/TkR

eferenceG

uidefo

rT

cl7.5/T

k4.1

written

by

Pau

lRain

es <ra

ines@

slac.sta

nfo

rd.e

du

>JeffT

ranter<

Jeff_

Tra

nte

r@M

itel.C

OM

>

Contents

1.

Basic

TclL

ang

uag

eF

eatures:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

22

.T

clSp

ecialVariab

les

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

23

.B

ackslashS

ub

stitutio

ns

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

24

.O

perato

rsan

dM

athF

un

ction

s ::

:

:

:

:

:

:

:

:

:

:

:

:

35

.R

egu

larE

xpressio

ns:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

36

.P

atternG

lob

bin

g

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

47

.C

on

trolS

tatemen

ts::

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

48

.F

ileIn

form

ation

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

59

.T

clInterp

reterIn

form

ation

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

61

0.

Lists

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

71

1.

Arrays

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

71

2.

Strin

gs

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

81

3.

File

Inp

ut/O

utp

ut :

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

91

4.

System

Interactio

n

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

10

15

.C

om

man

dH

istory

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

11

16

.M

ultip

leIn

terpreters

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

12

17

.P

ackages

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

13

18

.O

ther

TclC

om

man

ds

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

13

19

.G

eneralT

kW

idg

etInfo

rmatio

n

:

:

:

:

:

:

:

:

:

:

:

:

:

15

20

.T

kS

pecialV

ariables

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

17

21

.W

idg

etScro

llCo

mm

and

s

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

17

22

.T

he

Canvas

Wid

get

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

18

23

.T

he

En

tryW

idg

et

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

23

24

.T

he

Listb

ox

Wid

get

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

24

25

.T

he

Men

uW

idg

et

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

25

26

.T

he

TextWid

get

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

27

27

.O

ther

Stan

dard

Wid

gets

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

29

28

.Im

ages

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

34

29

.W

ind

owIn

form

ation

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

36

30

.T

he

Win

dow

Man

ager

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

38

31

.G

eom

etryM

anag

emen

t

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

40

32

.B

ind

ing

s:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

41

33

.O

ther

Tk

Co

mm

and

s ::

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

:

42

Tcl/TkR

eferenceG

uide

Conventions

fixed

den

otes

literaltext.

this

mean

svariab

letext,i.e.th

ing

syo

um

ustfillin

.

word

isa

keywo

rd,i.e.a

wo

rdw

itha

specialm

eanin

g.

[...]d

eno

tesan

op

tion

alpart.

1.Basic

TclLanguageFeatures

;o

rnew

line

statemen

tseparato

rn

statemen

tcon

tinu

ation

iflastcharacter

inlin

e

#co

mm

ents

ou

trestoflin

e(iffirstn

on�w

hitesp

acech

aracter)

var

simp

levariab

le

var(in

de

x)asso

ciativearray

variable

var(i,j)

mu

lti-dim

ensio

nalarray

variable

$va

rvariab

lesu

bstitu

tion

(also\$\{va

r\}xyz)

[exp

r1+

2]

com

man

dsu

bstitu

tion

ncha

rb

ackslashsu

bstitu

tion

(seeb

elow)

"hello

$a"

qu

otin

gw

ithsu

bstitu

tion

{hello

$a}

qu

otin

gw

ithn

osu

bstitu

tion(d

eferredsu

bstitu

tion

)

Th

eo

nly

data

type

inT

clisa

string

.How

ever,som

eco

mm

and

sw

illinterp

retarg

um

ents

asn

um

bers/b

oo

leanin

wh

ichcase

the

form

atsare

Integ

er:123

0xff

(hex)

0377

(octal).

Flo

ating

Po

int:

2.1

3.

6e4

7.9

1e+

16

Bo

olean

:tru

efa

lse0

1ye

sno

2.TclSpecialVariables

env

Array

wh

ereeach

elemen

tnam

eis

anenviro

men

tvariable.

erro

rCod

eE

rror

cod

ein

form

ation

from

the

lastTclerro

r.

erro

rInfo

Describ

esth

estack

traceo

fthe

lastTclerro

r.

tcl_lib

rary

Lo

cation

ofstan

dard

Tcllib

raries.

tcl_patch

Leve

lC

urren

tpatch

levelofT

clinterp

reter.

tcl_pla

tform

Array

with

elemen

tsosV

ersio

n,

mach

ine

,pla

tform

,an

dos

.

tcl_pre

cision

Nu

mb

ero

fsign

ificantd

igits

toretain

wh

enco

nverting

floatin

g-p

oin

tnu

mb

ersto

string

s(d

efault6

).

tcl_ve

rsion

Cu

rrentversio

no

fTclin

terpreter.

3.Backslash

Substitutions

naau

dib

lealert(0

x7)

nspa

cesp

ace

nbb

ackspace

(0x8

)

nnew

line

space

nffo

rmfeed

(0xC

)

ndd

do

ctalvalue

(d=0

-7)

nnn

ewlin

e(0

xA)

nxdd

hexad

ecimalvalu

e(d=

0-9

,a-f)

nrcarriag

eretu

rn(0

xD)

ncrep

lace`nc'

with

`c'

nth

orizo

ntaltab

(0x9

)

nn

ab

ackslash

nvverticaltab

(0xB

)

2

Tcl/TkR

eferenceG

uide

optionget

win

do

wn

am

ecla

ssO

btain

so

ptio

nvalu

efo

rwin

do

wu

nd

erna

mean

dcla

ssifpresen

t.

optionreadfile

fileN

am

e[prio

rity]R

eads

op

tion

sfro

mX

defau

lts-stylefile

into

op

tion

datab

aseat

prio

rity.

raisew

ind

ow

[ab

ove

Th

is]P

laceswin

do

wab

ovew

ind

owab

ove

Th

isinstackin

go

rder.

selectionclear

[-disp

layo

fw

ind

ow][-se

lectio

nse

lectio

n]C

learssele

ction(d

efaultP

RIM

AR

Y)

on

win

do

w'sd

isplay.

selectionget

[-disp

layo

fw

ind

ow][-se

lectio

nse

lectio

n][-type

type]

Retrievesse

lectio

nfrom

win

do

w'sd

ispla

yusin

grep

resentatio

ntype.

selectionhandle

[-sele

ction

sel][-typ

etyp

e][-form

at

fmt]

win

cmd

Arran

ges

forcm

dto

be

run

wh

eneverselo

ftype

isow

ned

byw

in.

selectionow

n[-d

ispla

yof

win

do

w][-sele

ction

sele

ction]

Retu

rns

path

nam

eo

fwind

ow

wh

ichow

nsse

lectio

non

win

do

w'sd

isplay.

selectionow

n[-se

lectio

nse

lectio

n][-com

mand

com

ma

nd]w

ind

ow

Cau

seswin

do

wto

beco

me

new

own

ero

fsele

ctionan

darran

ges

for

com

ma

ndto

be

run

wh

enwin

do

wlater

loses

these

lectio

n.

send[-d

ispla

yof

win

do

w][-asyn

c]

inte

rpcm

d[arg

arg

...]E

xecutecm

dw

itha

rgsin

the

Tk

app

licationin

terp

on

win

do

w'sd

isplay.If

-asyn

cis

specified

,thesend

com

man

dw

illreturn

imm

ediately.

tkappnam

e[n

ewN

am

e]S

etthe

interp

reternam

eo

fthe

app

lication

ton

ewN

am

e.

tkwaitvariable

varN

am

eP

ause

pro

gram

un

tilglo

balvariab

levarN

am

eism

od

ified.

tkwaitvisibility

win

do

wP

ause

pro

gram

un

tilwind

ow's

visibility

has

chan

ged

.

tkwaitw

indoww

ind

ow

Pau

sep

rog

ramu

ntilwin

do

wis

destro

yed.

tk_

bisqueS

etdefau

ltcolo

rp

aletteto

old

bisq

ue

schem

e.

tk_

dialogto

pw

titletextb

itma

pd

efa

ultstrin

g[string

...]P

op

su

pd

ialog

usin

gto

plevelw

ind

owtop

ww

itha

butto

nfo

reachstrin

garg

um

ent.R

eturn

sin

dex

ofbu

tton

user

presses,startin

gfro

m0

for

the

leftmo

stbutto

n.T

he

ind

exdefa

ultsp

ecifiesth

ed

efaultbu

ttton

.

tk_

focusNext

win

do

wR

eturn

sth

en

extwin

dow

afterwind

ow

info

cus

ord

er.

tk_

focusPrev

win

do

wR

eturn

sth

ep

reviou

sw

ind

owb

eforewin

do

win

focu

so

rder.

tk_

focusFollow

sMouse

Ch

ang

efo

cus

mo

delo

fapp

lication

sofo

cus

follow

sth

em

ou

sep

oin

ter.

tk_

optionMenu

wva

rNa

me

valu

e[valu

e...]

Creates

op

tion

men

uw

ithn

amewco

nsistin

go

fthe

given

values.T

he

curren

tvalu

eis

stored

ing

lob

alvariableva

rNa

me.R

eturn

sin

ternalm

enu

nam

e.

tk_

popupm

en

ux

y[en

try]P

ostp

op

upm

en

usoth

aten

tryis

po

sition

edatro

otco

ord

sxy.

tk_

setPalette

colo

rS

etthe

defau

ltbackg

rou

nd

colo

ran

dco

mp

ute

oth

erdefau

ltcolo

rs.

tk_

setPalette

na

me

colo

r[na

me

colo

r...]S

etthe

defau

ltcolo

rfo

rth

en

amed

colo

rop

tion

sexp

licitly..

43

Tcl/TkR

eferenceG

uide

Codes:

%%

sing

le%

sign

%w

wid

thfield

%#

lastevent'sse

rialfield

%x

xfield

%a

ab

ovefield

%y

yfield

%b

butto

nn

um

ber

%A

AS

CIIch

aracter%

cco

un

tfield%

Bb

ord

er_

wid

thfield

%d

deta

ilfield%

Ese

nd_

even

tfield%

ffo

cusfield

%K

keysymas

text%

hh

eig

htfield

%N

keysymas

decim

al%

kkeyco

defield

%R

roo

twin

dow

%m

mo

defield

%S

sub_

win

do

wid

entifier

%o

ove

rride_

red

irectfield

%T

type

field%

pp

lace

field%

Ww

ind

owp

athn

ame

%s

statefield

%X

x_ro

otfield

%t

time

field%

Yy_

roo

tfield

33.Other

TkC

omm

ands

bell[-d

ispla

yof

win

do

w]R

ing

the

Xb

ellonw

ind

ow's

disp

lay.

clipboardclear

[-disp

layo

fw

ind

ow]

Claim

own

ership

ofclip

bo

ardo

nwin

do

w'sd

isplay,clearin

gits

con

tents.

clipboardappend

[-disp

layo

fw

in][-form

at

fmt][-typ

etyp

e]d

ata

Ap

pen

dda

tato

clipb

oard

onw

in'sd

isplay.

destroy[w

ind

ow

win

do

w...]

Destro

yth

eg

ivenw

ind

ows

and

their

descen

den

ts.

focus[-fo

rce]

win

do

wS

etsth

ein

pu

tfocu

sfo

rwind

ow's

disp

laytow

ind

ow.T

he

-force

op

tion

cause

the

focu

sto

be

setevenifan

oth

erap

plicatio

nh

asit.

focus[-d

ispla

yof

win

do

w]R

eturn

sn

ame

offo

cus

win

dow

onwin

do

w'sd

isplay.

focus-la

stfor

win

do

wR

eturn

sth

ew

ind

oww

hich

mo

strecently

had

focu

san

dis

ad

escend

ento

fw

ind

ow's

top

level.

grabcurrent

[win

do

w]R

eturn

sn

ame

ofcu

rrentg

rabw

ind

owo

nw

ind

ow's

disp

lay.Ifwin

do

wis

om

itted,retu

rns

listofallw

ind

ows

grab

bed

by

app

lication

.

grabrelease

win

do

wR

eleasesg

rabo

nwind

ow.

grab[set][-g

lobal

]w

ind

ow

Sets

ag

rabo

nwin

do

ww

hich

willb

elo

calun

less -glo

bal

specified

.

grabstatus

win

do

wR

eturn

s none

,lo

cal

,org

lobal

tod

escribe

grab

stateo

fwind

ow.

lower

win

do

w[b

elo

wT

his]

Placesw

ind

ow

below

win

dow

belo

wT

hisin

stacking

ord

er.

optionadd

pa

ttern

valu

e[prio

rity]A

dd

so

ptio

nw

ithpa

tternva

lueatp

riority

(0-1

00

)to

datab

ase.

optionclearC

learso

ptio

nd

atabase

and

reload

sfro

mu

ser'sX

defau

lts.

42

Tcl/TkR

eferenceG

uide

4.Operators

andM

athFunctions

Th

eexpr

com

man

dreco

gn

izesth

efo

llowin

go

perato

rs,ind

ecreasing

ord

ero

fp

receden

ce:

-!

un

arym

inu

s,bitw

iseN

OT,lo

gicalN

OT

*/

%m

ultip

ly,divid

e,remain

der

+-

add

,sub

tract<

<>

>b

itwise

shiftleft,b

itwise

shiftrig

ht

<>

<=

>=

bo

olean

com

pariso

ns

==

!=b

oo

leaneq

uals,n

oteq

uals

&b

itwise

AN

D

^

bitw

iseexclu

siveO

R|

bitw

isein

clusive

OR

&&

log

icalAN

D||

log

icalOR

x?

y:

zif

x!=

0,th

eny

,elsez

Allo

perato

rssu

pp

ortin

tegers.A

llsup

po

rtfloatin

gp

oin

texcept

,%

,<<

,>>

,&,

^

,an

d|

.Bo

olean

op

erators

canalso

be

used

for

string

op

erand

s,inw

hich

casestrin

gco

mp

arison

willb

eu

sed.T

his

willo

ccur

ifanyo

fthe

op

erand

sare

no

tvalidn

um

bers.T

he &

&,||,an

d?:

op

erators

have

“lazyevalu

ation

”,asin

C.

Th

eexpr

com

man

dreco

gn

izesth

efo

llowin

gm

athfu

nctio

ns:

abs

cos

hyp

ot

sinaco

sco

shin

tsin

hasin

double

log

sqrt

ata

nexp

log10

tan

ata

n2

floor

pow

tanh

ceil

fmod

round

5.Regular

Expressions

regex|

regex

match

either

expressio

n

regex*

match

zeroo

rm

ore

ofreg

ex

regex+

match

on

eo

rm

ore

ofreg

ex

regex?

match

zeroo

ro

ne

ofreg

ex

.any

sing

lech

aracterexcep

tnew

line

^

match

beg

inn

ing

ofstrin

g

$m

atchen

do

fstring

ncm

atchch

aracterc

cm

atchch

aracterc

[abc]

match

setofch

aracters

[

^

abc]

match

characters

no

tinset

[a-z]m

atchran

ge

ofch

aracters

[

^

a-z]m

atchch

aractersn

otin

rang

e

()

gro

up

expressio

ns

3

Tcl/TkR

eferenceG

uide

6.Pattern

Globbing

?m

atchany

sing

lech

aracter

*m

atchzero

or

mo

rech

aracters

[abc]

match

setofch

aracters

[a-z]m

atchran

ge

ofch

aracters

ncm

atchch

aracterc

{a,b

,...}m

atchany

ofstrin

gs

a,b,etc.

ho

me

directo

ry(fo

r globco

mm

and

)

use

rm

atchuse

r'sh

om

ed

irectory

(forglob

com

man

d)

Note:fo

rth

eglob

com

man

d,a

“.”atth

eb

egin

nin

go

fafile's

nam

eo

rju

stafter“/”

mu

stbe

match

edexp

licitlyan

dall“/”

characters

mu

stbe

match

edexp

licitly.

7.ControlS

tatements

breakA

bo

rtinn

ermo

stcon

tainin

glo

op

com

man

d.

caseO

bso

lete,seeswitch

.

continueSkip

toth

en

extiteration

ofin

nerm

ostco

ntain

ing

loo

pco

mm

and

.

exit[

retu

rnC

od

e]Term

inate

the

pro

cess,return

ing

retu

rnC

od

e(anin

tegerw

hich

defau

ltsto

0)

toth

esystem

asth

eexitstatu

s.

forsta

rttestn

extbo

dy

Lo

op

ing

com

man

dw

heresta

rt,next,an

dbo

dyare

Tclco

mm

and

string

san

dtestis

anexp

ression

string

tob

ep

assedto

exprco

mm

and

.

foreachva

rna

me

listbo

dy

Th

eT

clcom

man

dstrin

gbod

yisevalu

atedfo

reach

itemin

the

string

listw

here

the

variableva

rna

meis

settoth

eitem

'svalu

e.

foreachva

rlist1list1

[varlist2

list2...]b

od

yS

ame

asabove,exceptdurin

geach

iteration

ofthe

loop,eachvariable

inva

rlistNis

settoth

ecu

rrentvalu

efro

mlistN.

ifexp

r1[

then]

bo

dy1[

elseifexp

r2[

then]

bo

dy2...][[

else]

bo

dyN

]Ifexp

ression

stringexp

r1evaluates

true,T

clcom

man

dstrin

gb

od

y1isevalu

ated.O

therw

iseifexp

r2is

true,b

od

y2isevalu

ated,an

dso

on

.Ifn

on

eo

fthe

expressio

ns

evaluate

totru

eth

enb

od

yNis

executed

.

return[-code

cod

e][-errorinfoin

fo][-errorcodeco

de][strin

g]R

eturn

imm

ediately

from

curren

tpro

cedu

rew

ithstrin

gas

return

value.

switch

[op

tion

s]string

pa

ttern

1b

od

y1[p

atte

rn2

bo

dy2...]

Th

estrin

garg

um

entis

match

edag

ainsteach

ofth

ep

atte

rnargu

men

tsin

ord

er.As

soo

nas

itfind

sa

pattern

thatm

atches

string,itevalu

atesth

eco

rrespo

nd

ing

Tclco

mm

and

stringbo

dy.Ifn

om

atchis

fou

nd

and

the

lastp

atternis

the

keywo

rd defa

ult

,its

com

man

dstrin

gis

evaluated

.

while

testb

od

yE

valutes

the

Tclco

mm

and

stringbo

dyas

lon

gas

expressio

nstrin

gtestevalu

atesto

true.

4

Tcl/TkR

eferenceG

uide

gridinfo

slave

Retu

rns

listdescrib

ing

con

figu

ration

stateo

fsla

ve.

gridlocation

ma

ster

xy

Retu

rns

colu

mn

and

rowco

ntain

ing

screenu

nits

xy

inm

aste

r.Ifx

yis

ou

tside

grid

,-1is

return

ed.

gridpropagate

ma

ster[b

oo

lea

n]S

et/getw

heth

erma

stertries

toresize

itsan

cestor

win

dow

sto

fitgrid

.

gridrow

configurem

aste

rro

w[-m

insize

size][-weig

ht

floa

t]S

et/getm

inim

um

rowsize

and

relativerow

weig

ht.

gridsize

ma

ster

Retu

rns

sizeo

fgrid

(inco

lum

ns

then

rows)

for

ma

ster.

gridslaves

ma

ster[-ro

wro

w][-co

lum

nco

lum

n]W

ithn

oo

ptio

ns,a

listofallslaves

inma

steris

return

ed.O

therw

ise,return

sa

listofslaves

insp

ecifiedrow

and

/orco

lum

n.

32.Bindings

bindta

gRetu

rns

listofallseq

uen

cesfo

rw

hich

ab

ind

ing

sexists

for

tag.

bindta

g<

mo

difie

r-mo

difie

r-type-d

etail>

Retu

rns

the

scriptb

ou

nd

toth

eg

ivenseq

uen

cefo

rta

g.

bindta

g<

mo

difie

r-mo

difie

r-type-d

etail>scrip

tB

ind

sscrip

ttoth

eg

ivenseq

uen

cefo

rtag

bindta

g<

mo

difie

r-mo

difie

r-type-d

etail>+

script

Ap

pen

dsscrip

ttoth

ecu

rrentb

ind

ing

so

fsequ

ence

for

tag.

bindtagsw

ind

ow

[tag

List]S

etsth

ecu

rrentp

receden

ceo

rder

oftag

sfo

rw

ind

ow

tota

gList.

Modifiers:

Any

Trip

leB

utto

n1

,B1

Mo

d3

,M3

Co

ntro

lB

utto

n1

,B1

Meta,M

Mo

d4

,M4

Sh

iftB

utto

n1

,B1

Mo

d1

,M1

Mo

d5

,M5

Lo

ckB

utto

n1

,B1

Mo

d2

,M2

Alt

Do

ub

leB

utto

n1

,B1

Types:

Bu

tton

Press,B

utto

nE

xpo

seL

eaveB

utto

nR

eleaseF

ocu

sInM

apC

irculate

Fo

cusO

ut

Pro

perty

Co

lorm

apG

ravityR

eparen

tC

on

figu

reK

eyPress,K

eyU

nm

apD

estroy

KeyR

eleaseV

isibility

En

terM

otio

n

Details:

for

butto

ns,a

nu

mb

er1

-5fo

rkeys,a

keysym(/u

sr/inclu

de/X

11/keysym

def)

Tags:in

ternalw

ind

ow(ap

plies

toju

stthatw

ind

ow)

top

levelwin

dow

(app

liesto

allitsin

ternalw

ind

ows)

win

dow

classn

ame

(app

liesto

allwid

gets

inclass)

all

(app

liesto

allwin

dow

s)

41

Tcl/Tk Reference Guide

31. Geometry Management

The pack Command

pack [configure ] slave[slave ...] [options]Details how slave windows should be managed.

-aftersibling -in master -padypixels-anchoranchor -ipadxpixels -fill none|x|y|both-beforesibling -ipadypixels -sidetop|bottom|left|right-expandboolean -padxpixels

pack forget slave[slave ...]Unmanages the given slave windows.

pack info slaveReturns list containing current pack configuration of windowslave.

pack propagate master[boolean]Enables or disables propogation for the windowmaster.

pack slaves masterReturns lists of slaves in the windowmaster.

The place Command

place [configure ] window option value[option value ...]Details how given windows should be managed.

-anchoranchor -relheightsize -x location-heightsize -relwidthsize -y location-in master -relx location -bordermodeinside|outside|ignore-width size -rely location

place forget windowUnmanageswindow.

place info windowReturns list containing current place configuration ofwindow.

place slaves windowReturns lists of slaves in the windowmaster.

The grid Command

grid [configure ] slave[slave...] [option value ...]

-columnn -ipadyamount -row n-columnspann -padxamount -rowspann-in other -padyamount -sticky [n][s ][e][w]-ipadxamount

grid bbox master column rowReturns bounding box in pixels of space occupied bycolumn row.

grid columnconfigure master column[-minsize size] [ -weight float]Set/get minimum column size and relative column weight.

grid forget slave[slave...]Removes (and unmaps) each slave from grid of its master.

40


8. File Information

file atime fileNameTime fileNamewas last accessed as seconds since Jan. 1, 1970.

file dirname fileNameReturns all characters infileNameup to but not including last slash.

file executable fileNameReturns 1 iffileNameis executable by user, 0 otherwise.

file exists fileNameReturns 1 iffileNameexists (and user can read its directory), 0 otherwise.

file extension fileNameReturns all characters infileNameafter and including the last dot.

file isdirectory fileNameReturns 1 iffileNameis a directory, 0 otherwise.

file isfile fileNameReturns 1 iffileNameis a regular file, 0 otherwise.

file join name[name...]Joins file names using the correct path separator for the current platform.

file lstat fileName varNameSame asfile stat except uses the lstat kernel call.

file mtime fileNameTime fileNamewas last modified as seconds since Jan. 1, 1970.

file owned fileNameReturns 1 iffileNameowned by the current user, 0 otherwise.

file pathtype fileNameReturns one ofabsolute , relative , volumerelative .

file readable fileNameReturns 1 iffileNameis readable by current user, 0 otherwise.

file readlink fileNameReturns value of symbolic link given byfileName.

file rootname fileNameReturns all the characters infileNameup to but not including last dot.

file size fileNameReturns size offileNamein bytes.

file split fileNameReturns list whose elements are the path components offileName.

file stat fileName varNamePlace results of stat kernel call onfileNamein variablevarNameas an arraywith elementsatime , ctime , dev , gid , ino , mode, mtime , nlink ,size , type , anduid .

file tail fileNameReturn all characters infileNameafter last slash.

file type fileNameReturns string giving type offileName. Possible values arefile ,directory , characterSpecial , blockSpecial , fifo , link , orsocket .

file writable fileNameReturns 1 iffileNameis writable by current user, 0 otherwise.

5

Tcl/TkR

eferenceG

uide

9.TclInterpreterInform

ation

infoargs

pro

cNa

me

Retu

rns

listdescrib

ing

ino

rder

the

nam

eso

fargu

men

tsto

pro

cNa

me.

infobody

pro

cNa

me

Retu

rns

the

bo

dy

ofp

roced

urepro

cNa

me.

infocm

dcountR

eturn

sth

eto

talnu

mb

ero

fcom

man

ds

thath

aveb

eeninvo

ked.

infocom

mands

[pa

ttern]

Retu

rns

listofT

clcom

man

ds

match

ing

glo

bp

attern

(defau

lt *).

infocom

pleteco

mm

an

dR

eturn

s1

ifcom

ma

ndis

aco

mp

leteT

clcom

man

d,0

oth

erwise.C

om

plete

means

havin

gn

ounclo

sedquotes,b

races,brackets

or

arrayelem

entnames

infodefault

pro

cNa

me

arg

varN

am

eR

eturn

s1

ifpro

cedu

reprocN

am

ehas

ad

efaultfo

rarg

um

entarg

and

places

the

value

invariab

levarN

am

e.Retu

rns

0ifth

ereis

no

defau

lt.

infoexists

varN

am

eR

eturn

s1

ifthe

variableva

rNa

meexists

inth

ecu

rrentco

ntext,0

oth

ewise.

infoglobals

[pa

ttern]

Retu

rns

listofg

lob

alvariables

match

ing

glo

bp

atte

rn(defau

lt*).

infohostnam

eR

eturn

sn

ame

ofco

mp

uter

on

wh

ichin

terpreterw

asinvo

ked.

infolevel

Retu

rns

the

stacklevelo

fthe

invokin

gp

roced

ure.

infolevel

nu

mb

er

Retu

rns

nam

ean

darg

um

ents

ofp

roced

ure

invoked

atstacklevel

nu

mb

er.

infolibrary

Retu

rns

nam

eo

flibrary

directo

ryw

here

stand

ardT

clscripts

aresto

red.

infoloaded

[inte

rp]R

eturn

slistd

escribin

gp

ackages

load

edin

toin

terp.

infolocals

[pa

ttern]

Retu

rns

listoflo

calvariables

match

ing

glo

bp

atte

rn(defau

lt *).

infonam

eofexecutableR

eturn

sfu

llpath

nam

eo

fbin

aryfro

mw

hich

the

app

lication

was

invoked

.

infopatchlevel

Retu

rns

curren

tpatch

levelfor

Tcl.

infoprocs

[pa

ttern]

Retu

rns

listofT

clpro

cedu

resm

atchin

gg

lob

pa

ttern(d

efault *

).Differs

from

infocom

mands

inth

atbuilt-in

sare

exclud

ed.

infoscript

Retu

rns

nam

eo

fTclscrip

tcurren

tlyb

eing

evaluated

.

infosharedlibextension

Retu

rns

extensio

nu

sedb

yp

latform

for

shared

ob

jects.

infotclversion

Retu

rns

version

nu

mb

ero

fTclinm

ajo

r.min

orfo

rm.

infovars

[pa

ttern]

Retu

rns

listofcu

rrently-visib

levariab

lesm

atchin

gg

lob

pa

ttern(d

efault*

).

6

Tcl/TkR

eferenceG

uide

wm

focusmodel

win

do

w[a

ctive|p

assive

]S

pecifies

the

focu

sm

od

elforwin

do

w.

wm

frame

win

do

wR

eturn

sth

eX

win

dow

iden

tifierfor

the

ou

termo

stdeco

rativefram

eco

ntain

ingw

ind

ow.If

win

do

wh

asn

on

e,return

sX

ido

fwind

ow

itself.

wm

geometry

win

do

w[n

ewG

eo

metry]

Ch

ang

esg

eom

etryo

fwind

ow

ton

ewG

eo

metry.

wm

gridw

ind

ow

[ba

seW

idth

ba

seH

eig

htw

idth

Inc

heig

htIn

c]

Ind

icatesth

atwin

do

wis

tob

em

anag

edas

ag

ridd

edw

ind

oww

ithth

esp

ecifiedrelatio

nb

etween

grid

and

pixelu

nits.

wm

groupw

ind

ow

[pa

thN

am

e]G

ivesp

athn

ame

for

leader

ofg

rou

pto

wh

ichw

ind

ow

belo

ng

s.

wm

iconbitmap

win

do

w[b

itma

p]S

pecifies

ab

itmap

tou

seas

icon

imag

ew

hen

win

do

wis

icon

ified.

wm

iconifyw

ind

ow

Arran

ge

forw

ind

ow

tob

eico

nfied

.

wm

iconmask

win

do

w[b

itma

p]S

pecifies

ab

itmap

tou

seto

mask

icon

imag

ew

hen

win

do

wis

icon

ified.

wm

iconname

win

do

w[n

ewN

am

e]S

pecifies

nam

eto

use

asa

labelfo

rw

ind

ow's

icon

.

wm

iconpositionw

ind

ow

[xy]

Sp

ecifiesp

ositio

no

nro

otw

ind

owto

placewin

do

w'sico

n.

wm

iconwindow

win

do

w[p

ath

Na

me]

Sets

path

nam

eo

fwin

dow

tou

seas

the

icon

wh

enw

ind

ow

isico

nified

.

wm

maxsize

win

do

w[w

idth

heig

ht]

Sp

ecifiesm

aximu

msizew

ind

ow

may

be

resizedto

ineach

directio

n.

wm

minsize

win

do

w[w

idth

heig

ht]

Sp

ecifiesm

inim

um

sizewin

do

wm

ayb

eresized

toin

eachd

irection

.

wm

overrideredirectw

ind

ow

[bo

ole

an]

Seto

ru

nsetth

eoverrid

e-redirectflag

of

win

do

wco

mm

on

lyu

sedb

yw

ind

owm

anag

erto

determ

ine

wh

ether

win

dow

sho

uld

deco

rativefram

e.

wm

positionfromw

ind

ow

[pro

gra

m|u

ser

]In

dicate

from

wh

om

thew

ind

ow's

curren

tpo

sition

was

requ

ested.

wm

protocolw

ind

ow

[na

me][co

mm

an

d]S

pecify

aT

clcom

man

dto

be

invoked

for

messag

eso

fpro

toco

ln

am

e.

wm

resizablew

ind

ow

[wid

thB

oo

lea

nh

eig

htB

oo

lea

n]S

pecifies

wh

etherwin

do

w'sw

idth

and

/orh

eigh

tisresizab

le.

wm

sizefromw

ind

ow

[pro

gra

m|u

ser

]In

dicate

from

wh

om

thew

ind

ow's

curren

tsizew

asreq

uested

.

wm

statew

ind

ow

Retu

rns

curren

tstateo

fwind

ow:n

orm

al

,ico

nic

,o

rwith

dra

wn

.

wm

titlew

ind

ow

[string]

Settitle

forw

ind

ow's

deco

rativefram

etostrin

g.

wm

transientw

ind

ow

[ma

ster]

Info

rms

win

dow

man

ager

thatwin

do

wis

atran

siento

fthe

win

dowm

aste

r.

wm

withdraw

win

do

wA

rrang

esfo

rwin

do

wto

be

with

draw

nfro

mth

escreen

.

39

Tcl/TkR

eferenceG

uide

winfo

screenheightw

ind

ow

Retu

rns

the

heig

htin

pixels

ofwin

do

w'sscreen

.

winfo

screenmm

heightw

ind

ow

Retu

rns

the

heig

htin

millim

eterso

fwind

ow's

screen.

winfo

screenmm

width

win

do

wR

eturn

sth

ew

idth

inm

illimeters

ofwin

do

w'sscreen

.

winfo

screenvisualw

ind

ow

Retu

rns

the

visualclass

ofwin

do

w'sscreen

.Mayb

eo

ne

of:d

irectcolo

r,g

rayscale,pseu

do

colo

r,staticcolo

r,staticgray,o

rtru

ecolo

r.

winfo

screenwidth

win

do

wR

eturn

sth

ew

idth

inp

ixelso

fwind

ow's

screen.

winfo

toplevelw

ind

ow

Retu

rns

the

path

nam

eo

fthe

top

-levelwin

dow

con

tainin

gw

ind

ow.

winfo

visualw

ind

ow

Retu

rns

the

visualclass

ofwin

do

w(see w

infoscreenvisual

).

winfo

visualsavailablew

ind

ow

Retu

rns

alistw

ho

seelem

ents

describ

eth

evisu

alsavailab

lefo

rw

ind

ow's

screenin

clud

ing

classan

dd

epth

..

winfo

vrootheightw

ind

ow

Retu

rns

the

heig

hto

fthe

virtualro

otw

ind

owasso

ciatedw

ithw

ind

ow.

winfo

vrootwidth

win

do

wR

eturn

sth

ew

idth

ofth

evirtu

alroo

twin

dow

associated

with

win

do

w.

winfo

vrootxw

ind

ow

Retu

rns

the

x-offseto

fthe

virtualro

otw

ind

owasso

ciatedw

ithw

ind

ow.

winfo

vrootyw

ind

ow

Retu

rns

the

y-offseto

fthe

virtualro

otw

ind

owasso

ciatedw

ithw

ind

ow.

winfo

width

win

do

wR

eturn

swin

do

w'sw

idth

inp

ixels.

winfo

xw

ind

ow

Retu

rns

x-coo

rdin

ate,inwin

do

w'sp

arent,o

fthe

up

per-leftco

rner

of

win

do

w.

winfo

yw

ind

ow

Retu

rns

y-coo

rdin

ate,inwin

do

w'sp

arent,o

fthe

up

per-leftco

rner

of

win

do

w.

30.TheW

indowM

anager

wm

aspectw

ind

ow

[min

Nu

mer

min

Den

om

ma

xNu

mer

ma

xDen

om

]In

form

win

dow

man

ager

ofd

esiredasp

ectratioran

ge

for

win

do

w.

wm

clientw

ind

ow

[na

me]

Sto

rena

mein

win

do

w'sW

M_

CLIE

NT

_M

AC

HIN

Ep

rop

erty.Info

rms

win

dow

man

ager

ofclien

tmach

ine

on

wh

ichth

eap

plicatio

nis

run

nin

g.

wm

colormapw

indows

win

do

w[w

ind

ow

List]S

torew

ind

ow

Listinw

ind

ow's

WM

_C

OLO

RM

AP

_W

IND

OW

Sp

rop

ertyw

hich

iden

tifiesth

ein

ternalw

ind

ows

with

inwind

ow

with

private

colo

rmap

s.

wm

comm

andw

ind

ow

[valu

e]S

toreva

lue

inw

ind

ow's

WM

_C

OM

MA

ND

pro

perty.In

form

sw

ind

owm

anag

ero

fcom

man

du

sedto

invoke

the

app

lication

.

wm

deiconifyw

ind

ow

Arran

ge

forw

ind

ow

tob

em

app

edo

nth

escreen

.

38

Tcl/TkR

eferenceG

uide

10.Lists

concat[a

rga

rg...]

Retu

rns

con

catenatio

no

feachlista

rgas

asin

gle

list.

joinlist[jo

inS

tring]

Retu

rns

string

createdb

yjo

inin

gallelem

ents

of

listwith

join

Strin

g.

lappendva

rNa

me[va

lue

valu

e...]A

pp

end

seachva

lue

toth

een

do

fthe

liststored

invarN

am

e.

lindexlistin

dex

Retu

rns

value

ofelem

entatin

dexin

list.

linsertlistin

dex

ele

men

t[ele

men

t...]R

eturn

sn

ewlistfo

rmed

by

insertin

gg

ivenn

ewelem

ents

atin

dexin

list.

list[a

rga

rg...]

Retu

rns

new

listform

edb

yu

sing

eacha

rgas

anelem

ent.

llengthlist

Retu

rns

nu

mb

ero

felemen

tsinlist.

lrangelistfirstla

stR

eturn

sn

ewlistfro

mslice

oflistatin

dicesfirstth

rou

ghla

stinclu

sive.

lreplacelistfirstla

st[valu

eva

lue...]

Retu

rns

new

listform

edb

yrep

lacing

elemen

tsfirstth

rou

ghla

stinlistw

ithg

ivenvalu

es.

lsearch[m

od

e]listp

atte

rnR

eturn

sin

dex

offirstelem

entinlistth

atmatch

espa

ttern(-1

for

no

match

).M

od

em

ayb

e -exa

ct,-g

lob

(defau

lt),or-re

gexp

.

lsort[sw

itches]

listR

eturn

sn

ewlistfo

rmed

by

sortin

glistaccord

ing

toswitch

es.T

hese

are

-ascii

string

com

parsio

n(d

efault)

-inte

ger

integ

erco

mp

arison

-real

floatin

g-p

oin

tcom

parisio

n

-incre

asin

gso

rtinin

creasing

ord

er(d

efault)

-decre

asin

gso

rtind

ecreasing

ord

er

-com

mand

cmd

Use

com

ma

ndw

hich

takestw

oarg

um

ents

and

return

san

integ

erless

than

,equ

alto,o

rg

reaterth

anzero

.

splitstrin

g[sp

litCh

ars]

Retu

rns

alistfo

rmed

by

splittin

gstring

ateachch

aracterinsp

litCh

ars.

Note:listin

dices

startat0an

dth

ew

ord en

dm

ayb

eu

sedto

reference

the

lastelem

entin

the

list.

11.Arrays

arrayanym

orea

rrayN

am

ese

arch

IdR

eturn

s1

ifanymo

reelem

ents

areleftto

be

pro

cessedin

arraysearch

sea

rchIdo

na

rrayN

am

e,0o

therw

ise.

arraydonesearch

arra

yNa

me

sea

rchId

Termin

atesth

earray

searchsearch

Idon

arra

yNa

me.

arrayexists

arra

yNa

me

Retu

rns

1ifa

rrayN

am

eisan

arrayvariab

le,0o

therw

ise.

7

Tcl/TkR

eferenceG

uide

arrayget

arra

yNa

me

Retu

rns

alistw

here

eacho

dd

elemen

tisan

elemen

tnam

ean

dth

efo

llowin

geven

elemen

titsco

rrespo

nd

ing

value.

arraynam

esa

rrayN

am

e[pa

ttern]

Retu

rns

listofallelem

entn

ames

inarrayN

am

ethatm

atchg

lobp

atte

rn.

arraynextelem

enta

rrayN

am

ese

arch

IdR

eturn

sn

ame

ofn

extelemen

tinarrayN

am

efor

the

searchsea

rchId.

arrayset

arra

yNa

me

listS

etsvalu

eso

felemen

tsinarra

yNa

mefo

rlistin

arrayget

form

at.

arraysize

arra

yNa

me

Retu

rnn

um

ber

ofelem

ents

inarrayN

am

e.

arraystartsearch

arra

yNa

me

Retu

rns

asearch

idto

use

for

anelem

ent-b

y-elemen

tsearcho

fa

rrayN

am

e.

parraya

rrayN

am

e[pa

ttern]

Prin

ttostan

dard

ou

tpu

tthe

nam

esan

dvalu

eso

fallelemen

tnam

esin

arra

yNa

meth

atmatch

glo

bpa

ttern.

12.Strings

appendva

rNa

me[va

lue

valu

e...]A

pp

end

seach

ofth

eg

ivenvalu

esto

the

string

stored

inva

rNa

me.

format

form

atS

tring[a

rga

rg...]

Retu

rns

afo

rmated

string

gen

eratedin

the

AN

SIC

sprintfm

ann

er.

regexp[sw

itches]

expstrin

g[ma

tchV

ar][su

bM

atch

Va

r...]R

eturn

s1

ifthe

regu

larexp

ressionexp

match

esp

artor

allofstrin

g,0

oth

erwise.Ifsp

ecified,m

atch

Va

rwillb

esetto

allthe

characters

inth

em

atchan

dth

efo

llowin

gsub

Ma

tchV

ar's

willb

esetto

match

edp

arenth

esizedsu

bexp

ression

s.Th

e -noca

sesw

itchcan

be

specified

toig

no

recase

inm

atchin

g.T

he-in

dice

ssw

itchcan

be

specified

soth

atm

atch

Va

rand

sub

Ma

tchV

arw

illbe

settoth

estartan

den

din

gin

dices

instrin

go

ftheir

corresp

on

din

gm

atch.

regsub[sw

itches]

expstrin

gsu

bS

pec

varN

am

eR

eplaces

the

firstpo

rtion

ofstrin

gth

atmatch

esth

ereg

ular

expressio

nexp

with

sub

Sp

ecan

dp

lacesresu

ltsinva

rNa

me.R

eturn

sco

un

tofn

um

ber

of

replacem

ents

mad

e.Th

e -noca

sesw

itchcan

be

specified

toig

no

recase

inm

atchin

g.T

he-a

llsw

itchw

illcause

allmatch

esto

be

sub

stituted

for.

scanstrin

gfo

rma

tString

varN

am

e[varN

am

e...]E

xtractsvalu

esin

tog

ivenvariab

lesu

sing

AN

SICsscanfb

ehavio

r.

stringcom

parestrin

g1

string

2R

eturn

s-1

,0,o

r1

,dep

end

ing

on

wh

ether

string

1is

lexicog

raph

icallyless

than

,equ

alto,o

rg

reaterth

anstring

2.

stringfirst

string

1strin

g2

Retu

rnin

dex

instring

2o

ffirstoccu

rance

ofstrin

g1

(-1ifn

otfo

un

d).

stringindex

string

cha

rInd

exR

eturn

sth

echa

rInd

ex'thch

aracterinstrin

g.

stringlast

string

1strin

g2

Retu

rnin

dex

instring

2o

flastoccu

rance

ofstrin

g1

(-1ifn

otfo

un

d).

stringlength

string

Retu

rns

the

nu

mb

ero

fcharacters

instrin

g.

8

Tcl/TkR

eferenceG

uide

winfo

geometry

win

do

wR

eturn

sth

ep

ixelgeo

metry

forwin

do

w,inth

efo

rmw

idthxh

eig

ht+

x+y.

winfo

heightw

ind

ow

Retu

rns

heig

hto

fwin

do

win

pixels.

winfo

idw

ind

ow

Retu

rns

ah

exadecim

alstring

ind

icating

the

Xid

entifier

for

win

do

w.

winfo

interps[-d

ispla

yof

win

do

w]R

eturn

sa

listofallT

clinterp

retersreg

isteredo

nw

ind

ow's

disp

lay.

winfo

ismapped

win

do

wR

eturn

s1

ifwin

do

wis

curren

tlym

app

ed,0

oth

erwise.

winfo

manager

win

do

wR

eturn

sth

en

ame

ofth

eg

eom

etrym

anag

ercu

rrently

respo

nsib

lefo

rw

ind

ow.

winfo

name

win

do

wR

eturn

swin

do

w'sn

ame

with

inits

paren

t,aso

pp

osed

toits

fullp

athn

ame.

winfo

parentw

ind

ow

Retu

rns

the

path

nam

eo

fw

ind

ow's

paren

t.

winfo

pathname

[-disp

layo

fw

ind

ow]

idR

eturn

sth

ep

athn

ame

ofth

ew

ind

oww

ho

seX

iden

tifieris

ido

nw

ind

ow's

disp

lay.

winfo

pointerxw

ind

ow

Retu

rns

mo

use

po

inter's

xco

ord

inate

on

win

do

w'sscreen

.

winfo

pointerxyw

ind

ow

Retu

rns

mo

use

po

inter's

xan

dy

coo

rdin

ateso

nw

ind

ow's

screen.

winfo

pointeryw

ind

ow

Retu

rns

mo

use

po

inter's

yco

ord

inate

on

win

do

w'sscreen

.

winfo

pixelsw

ind

ow

nu

mb

er

Retu

rns

the

nu

mb

ero

fpixels

inwind

ow

corresp

on

din

gto

the

distan

ceg

ivenb

yn

um

ber,ro

un

ded

ton

earestinteg

er.

winfo

reqheightw

ind

ow

Retu

rns

ad

ecimalstrin

gg

ivingwin

do

w'sreq

uested

heig

ht,in

pixels.

winfo

reqwidth

win

do

wR

eturn

sa

decim

alstring

givin

gwind

ow's

requ

estedw

idth

,inp

ixels.

winfo

rgbw

ind

ow

colo

rR

eturn

sa

listofth

eth

reeR

GB

values

thatco

rrespo

nd

toco

lorin

win

do

w.

winfo

rootxw

ind

ow

Retu

rns

the

x-coo

rdin

ate,inth

ero

otw

ind

owo

fthe

screen,o

fthe

up

per-left

corn

ero

fwin

do

w(in

clud

ing

sits

bo

rder).

winfo

rootyw

ind

ow

Retu

rns

the

y-coo

rdin

ate,inth

ero

otw

ind

owo

fthe

screen,o

fthe

up

per-left

corn

ero

fwin

do

w(in

clud

ing

sits

bo

rder).

winfo

serverw

ind

ow

Retu

rns

serverin

form

ation

onwin

do

w'sd

isplay.

winfo

screenw

ind

ow

Retu

rns

the

nam

eo

fthe

screenasso

ciatedw

ithw

ind

ow,in

the

form

disp

layN

am

e.screen

Ind

ex.

winfo

screencellsw

ind

ow

Retu

rns

the

nu

mb

ero

fcellsin

the

defau

ltcolo

rm

apfo

rw

ind

ow's

screen.

winfo

screendepthw

ind

ow

Retu

rns

the

dep

th(b

itsp

erp

ixel)o

fw

ind

ow's

screen.

37

Tcl/TkR

eferenceG

uide

ima

geN

am

egetx

yR

eturn

sR

GB

value

ofp

ixelatcoo

rdsxy

aslisto

fthree

integ

ers.

ima

geN

am

eputd

ata

[-tox1

y1x2

y2]S

etsp

ixelsvalu

esfo

rth

ereg

ionx1

y1x2

y2for

2-D

arrayda

ta.

ima

geN

am

e readfile

Na

me[o

ptio

nva

lue

...]R

eads

imag

ed

atafro

mfilefile

Na

mein

toim

age

usin

gg

iveno

ptio

ns.

-form

at

form

at-n

am

eS

pecifies

imag

efo

rmato

ffile.

-from

x1y1

x2y2

Sp

ecifiesa

rectang

ular

regio

no

fthe

imag

efile

toco

py

from

.

-shrin

kW

illclipim

age

soco

pied

regio

nis

inb

otto

m-rig

htco

rner.

-tox

yS

pecifies

coo

rds

ofth

eto

p-leftco

rner

inim

age

toco

py

into

.

ima

geN

am

ereditherR

edith

erth

eim

age.

ima

geN

am

e write

fileN

am

e[op

tion

valu

e...]

Writes

imag

ed

atafro

mim

age

into

filefileN

am

e.

-form

at

form

at-n

am

eS

pecifies

imag

efo

rmatfo

rth

efile.

-from

x1y1

x2y2

Sp

ecifiesa

rectang

ular

regio

no

fthe

imag

eto

cop

yfro

m.

29.Window

Information

winfo

allmapped

win

do

wR

eturn

s1

ifwin

do

wan

dallits

ancesto

rsare

map

ped

,0o

therw

ise.

winfo

atom[-d

ispla

yof

win

do

w]n

am

eR

eturn

sin

teger

iden

tifierfo

rato

mg

ivenb

ynam

eon

win

do

w'sd

isplay.

winfo

atomnam

e[-d

ispla

yof

win

do

w]id

Retu

rns

textualn

ame

ofato

mg

ivenb

yin

teger

ido

nw

ind

ow's

disp

lay.

winfo

cellsw

ind

ow

Retu

rns

nu

mb

ero

fcellsin

the

colo

rmap

for

win

do

w.

winfo

childrenw

ind

ow

Retu

rns

listcon

tainin

gp

athn

ames

ofallth

ech

ildren

of

win

do

w.

winfo

classw

ind

ow

Retu

rns

the

classn

ame

of

win

do

w.

winfo

colormapfull

win

do

wR

eturn

1ifth

eco

lorm

apfo

rwin

do

wis

full,0

oth

erwise.

winfo

containing[-d

ispla

yof

win

do

w]ro

otX

roo

tYR

eturn

sp

athn

ame

ofw

ind

owco

ntain

ing

the

po

int

roo

tXro

otY

on

win

do

w'sd

isplay..

winfo

depthw

ind

ow

Retu

rns

the

dep

th(b

itsp

erp

ixel)o

fw

ind

ow.

winfo

existsw

ind

ow

Retu

rns

1ifw

ind

ow

exists,0ifitd

oesn

't.

winfo

fpixelsw

ind

ow

nu

mb

er

Retu

rns

floatin

g-p

oin

tvalue

givin

gth

en

um

ber

ofp

ixeslinw

ind

ow

corresp

on

din

gto

the

distan

ceg

ivenb

yn

um

ber.

36

Tcl/TkR

eferenceG

uide

stringm

atchp

atte

rnstrin

gR

eturn

s1

ifglo

bpa

tternm

atchesstrin

g,0o

therw

ise.

stringrange

string

firstlast

Retu

rns

characters

fromstrin

gatin

dicesfirstth

rou

ghla

stinclu

sive.

stringtolow

erstrin

gR

eturn

sn

ewstrin

gfo

rmed

by

convertin

gallch

arsin

string

tolow

ercase.

stringtoupper

string

Retu

rns

new

string

form

edb

yco

nverting

allchars

instrin

gto

up

per

case.

stringtrim

string

[cha

rs]R

eturn

sn

ewstrin

gfo

rmed

by

removin

gfro

mstring

anylead

ing

or

trailing

characters

presen

tinth

esetch

ars(d

efaults

tow

hitesp

ace).

stringtrim

leftstrin

g[ch

ars]

Sam

easstring

trimfo

rlead

ing

characters

on

ly.

stringtrim

rightstrin

g[ch

ars]

Sam

eas string

trimfo

rtrailin

gch

aracterso

nly.

stringw

ordendstrin

gin

dex

Retu

rns

ind

exo

fcharacter

justafter

laston

ein

wo

rdat

ind

exinstrin

g.

stringw

ordstartstrin

gin

dex

Retu

rns

ind

exo

ffirstcharacter

ofw

ord

atin

dexin

string.

subst[-n

ob

ackslashes][-n

oco

mm

and

s][-novariab

les]strin

gR

eturn

sresu

ltofb

ackslash,co

mm

and

,and

variable

sub

stitution

so

nstrin

g.E

achm

ayb

etu

rned

offb

ysw

itch.

13.FileInput/O

utput

closefile

IdC

lose

the

op

enfile

chan

nelfile

Id.

eoffile

IdR

eturn

s1

ifanen

d-o

f-fileh

aso

ccurred

on

fileId,0

oth

erwise.

fblockedfile

IdR

eturn

s1

iflastreadfro

mfileId

exhau

stedallavailab

lein

pu

t.

fconfigurefile

Id[o

ptio

n[va

lue]]

Sets

and

gets

op

tion

sfo

rI/O

chan

nel

fileId.Op

tion

sare:

-blo

cking

bo

ole

an

Wh

ether

I/Ocan

blo

ckp

rocess.

-buffe

ring

full|lin

e|n

one

How

tobu

ffero

utp

ut.

-buffe

rsizeb

yteS

izeS

izeo

fbuffer.

-eofch

ar

cha

r|{in

Ch

ar

ou

tCh

ar}

Sets

character

toserve

asen

d-o

f-filem

arker.

-transla

tion

mo

de|{

inM

od

eo

utM

od

e}S

etsh

owto

translate

end

-of-lin

em

arkers.M

od

esarea

uto

,bin

ary

,cr

,crlf,

andlf

.

Fo

rso

cketchan

nels

(read-o

nly

setting

s):

-sockn

am

eR

eturn

sth

reeelem

entlistw

ithad

dress,h

ostn

ame

and

po

rtnu

mb

er.

-peern

am

eF

or

clientan

daccep

tedso

ckets,three

elemen

tlistofp

eerso

cket.

fileeventfile

Idre

adable

|writa

ble

[script]

Execu

tescriptw

hen

chan

nelfile

Idb

ecom

esread

able/w

ritable.

9


flush fileIdFlushes any output that has been buffered forfileId.

gets fileId [varName]Read next line from channelfileId, discarding newline character. Placescharacters of line invarNameif given, otherwise returns them.

open fileName[access] [perms]Opensfilenameand returns its channel id. If a new file is created, itspermission are set to the conjuction ofpermsand the process umask. Theaccessmay be

r Read only. File must exist.

r+ Read and write. File must exist.

w Write only. Truncate if exists.

w+ Read and write. Truncate if exists.

a Write only. File must exist. Access position at end.

a+ Read and write. Access position at end.

puts [-nonewline ] [fileId] stringWrite string tofileId (defaultstdout ) optionally omitting newline char.

read [-nonewline ] fileIdRead all remaining bytes fromfileId, optionally discarding last character if itis a newline.

read fileId numBytesReadnumBytesbytes fromfileId.

seek fileId offset[origin]Change current access position onfileId to offsetbytes fromorigin whichmay bestart , current , or end .

socket [option...] host portOpen a client-side TCP socket to serverhostonport. Options are:

-myaddr addr Set network address of client (if multiple available).

-myport port Set connection port of client (if different from server).

-async Make connection asynchronous.

socket -server command[-myaddr addr] portOpen server TCP socket onport invokingcommandon connect.

tell fileIdReturn current access position in fileId.

14. System Interaction

cd [dirName]Change working directory todirName.

clock clicksReturns hi-res system-dependent integer time value.

clock format clockVal[-format string] [ -gmt boolean]Convert integerclockValto human-readable format defined bystring.

clock scan dateString[-base clockVal] [ -gmt boolean]ConvertdateStringto an integer clock value. IfdateStringcontains a timeonly, the date ofclockValis used.

clock secondsReturn current date and time as system-dependent integer value.

10


image width nameReturns pixel width of imagename.

When an image is created, Tk creates a new command with the name of the image.For all image types, this command supports thecget andconfigure methods in thesame manner as widgets for changing and querying configuration options.

The bitmap Image Type

-background colorSet background color for bitmap.

-data stringSpecify contents of bitmap in X11 bitmap format.

-file fileNameGives name of file whose contents define the bitmap in X11 bitmap format.

-foreground colorSet foreground color for bitmap.

-maskdata stringSpecify contents of mask in X11 bitmap format.

-maskfile fileNameGives name of file whose contents define the mask in X11 bitmap format.

The photo Image Type

-data stringSpecify contents of image in a supported format.

-format formatNameSpecify format for data specified with the-data or -file options. Instandard Tk4.0, only the GIF/PGM/PPM formats are supported.

-file fileNameGives name of file whose contents define the image in supported format.

-height numberSpecifies pixel height of the image.

-palette paletteSpecSet the resolution of the color cube to be allocated for image.

-width numberSpecifies pixel width of the image.

imageNameblankBlanks the image so has no data and is completely transparent.

imageNamecopy sourceImage[option value ...]Copy a region fromsourceImageto imageNameusing given options.

-from x1 y1 x2 y2Specifies rectangular region of source image to be copied.

-to x1 y1 x2 y2Specifies rectangular region of target image to be affected.

-shrinkWill clip target image so copied region is in bottom-right corner.

-zoom x yMagnifies source region byx y in respective direction.

-subsample x yReduces source image by using only everyx yth pixel.

35


-width widthNarrow dimension of scrollbar (not including border).

Elements: arrow1, trough1, slider, trough2, arrow2

scrollbaractivate [element]Displayelementwith active attributes.

scrollbardelta deltaX deltaYReturns fractional position change for slider movement ofdeltaX deltaY.

scrollbar fraction x yReturns a real number between 0 and 1 indicating where the point given bypixel coordsx y lies in the trough area of the scrollbar.

scrollbargetReturns current scrollbar settings as the list{ first last} .

scrollbar identify x yReturns name of element under pixel coordsx y.

scrollbarset first lastDescribes current view of associated widget wherefirst lastare thepercentage distance from widget's beginning of the start and end of the view.

Toplevel

-borderwidth -highlightbackground -relief-cursor -highlightcolor -takefocus-height -highlightthickness -width

-background colorSame as standard but my be empty to preserve colormap space.

-class stringClass name for the window to be used by option database.

-colormap colormapColor map to use for window. May be the wordnew, pathname of othertoplevel, or empty for the default colormap of screen.

-screen screenScreen on which to place the window.

-visual visualSpecifies visual to use for window.

28. Images

image create type[name] [options value ...]Creates new image oftypewith optionsand returnsname.

image delete nameDeletes the imagename.

image height nameReturns pixel height of imagename.

image namesReturns a list of the names of all existing images.

image type nameReturns the type of imagename.

image typesReturns a list of valid image types.

34


exec [-keepnew ] arg [arg ...]Execute subprocess using eacharg as word for a shell pipeline and returnresults written to standard out, optionally retaining the final newline char.The following constructs can be used to control I/O flow.

| pipe (stdout)

|& pipe (stdout and stderr)

<fileName stdin from file

<@ fileId stdin from open file

<<value pass value to stdin

>fileName stdout to file

2>fileName stderr to file

>& fileName stdout and stderr to file

>>fileName append stdout to file

2>>fileName append stderr to file

>>& fileName stdout and stderr to file

>@ fileId stdout to open file

2>@ fileId stderr to open file

>&@ fileId stdout and stderr to open file

& run in background

glob [-nocomplain ] pattern[pattern...]Returns list of all files in current directory that match any of the givencsh-style glob patterns, optionally suppressing error on no match.

pid [fileId]Return process id of process pipelinefileId if given, otherwise return processid of interpreter process.

pwd Returns the current working directory.

15. Command History

history add command[exec ]Addscommandto history list, optionally executing it.

history change newValue[event]Replaces value ofevent(default current) in history withnewValue.

history event [event]Returns value ofevent(default -1) in history.

history info [count]Returns event number and contents of the lastcountevents.

history keep [count]Set number of events to retain in history tocount.

history nextidReturns number for next event to be recorded in history.

history redo [event]Re-executesevent(default -1).

history substitute old new[event]Re-executesevent(default -1) replacing any occurance of stringold withnewin event' s value.

history words selector[event]Returns theselector' th word in value ofeventif selectoris a number or the

11


last word ifselectoris $. Otherwise,selectoris treated as a glob pattern, andwords that match it are returned.

16. Multiple Interpreters

interp alias srcPath srcCmdReturns list whose elements are thetargetCmdandargsassociated with thealiassrcCmdin interpretersrcPath.

interp alias srcPath srcCmdDeletes the aliassrcCmdin interpretersrcPath.

interp alias srcPath srcCmd targetPath targetCmd[arg ...]Creates an aliassrcCmdin interpretersrcPathwhich when invoked will runtargetCmdandargs in the interpretertargetPath.

interp aliases [path]Returns list of all aliases defined in interpreterpath.

interp create [-safe ] [–] [ path]Creates a slave interpreter (optionally safe) namedpath.

interp delete path[path...]Deletes the interpreterpathand all its slave interpreters.

interp eval path arg[arg ...]Evalutes concatenation ofargs as command in interpreterpath.

interp exists pathReturns 1 if interpreterpathexists, 0 otherwise.

interp issafe [path]Returns 1 if interpreterpathis safe, 0 otherwise.

interp share srcPath fileId destPathCauses I/O channelfileId to be shared between interpreterssrcPathanddestPath.

interp slaves [path]Returns list of names of all slave interpreters of interpreterpath.

interp target path aliasReturns Tcl list describing target interpreter ofalias in interpreterpath.

interp transfer srcPath fileId destPathMoves I/O channelfileId from interpretersrcPathto destPath.

slavealiasesReturns list of all aliases defined in interpreterslave.

slavealias srcCmdReturns list whose elements are thetargetCmdandargsassociated with thealiassrcCmdin interpreterslave.

slavealias srcCmdDeletes aliassrcCmdin interpreterslave.

slavealias srcCmd targetCmd[arg ...]Creates an aliassrcCmdin interpreterslavethat consists of runningtargetCmdandargs in its master.

slaveeval arg [arg ...]Evalutes concatenation ofargs as command in interpreterslave.

slaveissafeReturns 1 if interpreterslaveis safe, 0 otherwise.

12


-digits integerAn integer specifying how many significant digits should be retained.

-from numberA real value corresponding to left or top end of the scale.

-label stringA string to display as label for the scale.

-length sizeSpecifies the height (width) for vertical (horizontal) scales.

-resolution numberReal value to which scale's value will be rounded to an even multiple of.

-showvalue booleanWhether or not scale's current value should be displayed in side label.

-sliderlength sizeSize of the slider, measured along the slider's long dimension.

-sliderrelief reliefSpecify the relief used to display the slider.

-tickinterval numberA real value to specify the spacing between numerical tick marks displayed.

-to numberA real value corresponding to the right or bottom end of the scale.

-variable variableName of a global variable to link to the scale.

-width widthNarrow dimension of scale (not including border).

scalecoords [value]Returns x and y coordinates of point correspoinding tovalue.

scaleget [x y]If x y is given, returns scale value at that coordiante postion. Otherwise,scale's current value is returned.

scaleidentify x yReturns string indicating part of scale at postionx y. Maybe one ofslider, trough1, trough2 or empty.

scaleset valueChanges the current value of scale tovalue.

Scrollbar

-activebackground -highlightcolor -repeatdelay-background -highlightthickness -repeatinterval-borderwidth -jump -takefocus-cursor -orient -troughcolor-highlightbackground -relief

-activerelief numberRelief to use when displaying the element that is active.

-command tclCommandPrefixPrefix of a Tcl command to invoke to change the view in the widgetassociated with the scrollbar.

-elementborderwidth widthWidth of borders around internal elements (arrows and slider).

33


-aspect integerRatio of text width to text height times 100 to use to display text.

Radiobutton

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

-indicatoron booleanWhether or not the indicator should be drawn.

-selectcolor colorColor used to fill in indicator when selected.

-selectimage imageImage displayed in indicator when selected.

-value valueValue given to variable specified with-variable option when theradiobutton is selected.

-variable variableVariable to associate with radiobutton.

radiobuttondeselectDeselect the radiobutton.

radiobuttonflashAlternate radiobutton between active and normal colors.

radiobuttoninvokeToggle the selection state of the radiobutton and invoke the Tcl commandspecified with-command, if any.

radiobuttonselectSelect the radiobutton.

Scale

-activebackground -highlightbackground -repeatdelay-background -highlightcolor -repeatinterval-borderwidth -highlightthickness -state-cursor -orient -takefocus-foreground -relief -troughcolor-font

-bigincrement numberA real value to use for large increments of the scale.

-command tclCommandSpecified a TCL command to invoke when scale's value is changed. Thescale's value will be appended as an additional argument.

32


17. Packages

package forget packageRemove all info aboutpackagefrom interpreter.

package ifneeded package version[script]Tells interpreter that ifpackage versionis needed, runningscriptwillprovide it.

package namesReturns list of all packages in the interpreter that are currently provided orhave anifneeded script available.

package provide package[version]Tells interpreter thatpackage versionsis now provided. Withoutversion, theprovided version ofpackageis returned.

package require [-exact ] package[version]Tells interpreter thatpackagemust be provided. Only packages withversions equal to or later thanversion(if provided) are acceptable. If-exact is specified, the exact version specified must be provided.

package unknown [command]Specifies a last resort Tcl command to provide a package.

package vcompare version1 version2Returns -1 ifversion1is earlier thanversion2, 0 if equal, and 1 if later.

package versions packageReturns list of all versions numbers ofpackagewith an ifneeded script.

package vsatisfies version1 version2Returns 1 ifversion2scripts will work unchanged underversion1.

18. Other Tcl Commands

after ms[arg1 arg2 arg3 ...]Arrange for command (concat ofargs) to be run inmsmilliseconds. With noargs, program will sleep formsmilliseconds.

after cancel id| arg1 arg2 ...Cancel previousafter command either by command or the id returned.

after idle [arg1 arg2 arg3 ...]Arrange for command (concat ofargs) to be run later when Tk is idle.

after info [id]Returns information on event handlerid. With no id, returns a list of allexisting event handler ids.

auto _execok execFileReturns 1 if an executable file by the nameexecFileexists in user's PATH.

auto _load cmdAttempts to load definition forcmdby searching$auto _path and$env(TCLLIBPATH) for a tclIndex file which will inform the interpreterwhere it can findcmd' s definition.

auto _mkindex directory pattern[pattern...]Generate a tclIndex file from all files indirectorythat match glob patterns.

auto _resetDestroys cached information used byauto _execok andauto _load .

bgerror messageUser defined handler for background Tcl errors. Default exists for Tk.

13


catch script [varName]Evaluatescriptstoring results intovarName. If there is an error inevaluation, a non-zero error code is returned and an error message stored invarName.

error message[info] [code]Interrupt command interpretation with an error described inmessage. GlobalvariableserrorInfo anderrorCode will be set toinfo andcode.

eval arg [arg ...]Returns result of evaluating the concatenation ofargs' s as a Tcl command.

expr arg [arg ...]Returns result of evaluating the concatenation ofarg' s as an operatorexpression. SeeOperatorsfor more info.

global varName[varName...]Declares givenvarName' s as global variables.

incr varName[increment]Increment the integer value stored invarNameby increment(default 1).

load file [pkgName[interp]]Load binary code forpkgNamefrom file (dynamic lib) intointerp.

proc name args bodyCreate a new Tcl procedure or replace existing one.

rename oldName newNameRename commandoldNameso it is now callednewName. If newNameis theempty string, command is deleted.

set varName[value]Storevaluein varNameif given. Returns the current value ofvarName.

source fileNameRead filefileNameand evaluate its contents as a Tclscript.

time script [count]Call interpretercount(default 1) times to evaluatescript. Returns string ofthe form “503 microseconds per iteration ”.

trace variable varName ops commandArrange forcommandto be executed whenevervarNameis accessed in oneof the ways specified withops. Possbile values arer for read,w for written,u for unset, and any combination of the three.

trace vdelete varName ops commandRemove any previous trace specified with the given arguments.

trace vinfo varNameReturns list describing each trace onvarName.

unknown cmdName[arg arg ...]Called when the Tcl interpreter encounters an undefined command name.

unset varName[varName...]Removes the given variables and arrays from scope.

update [idletasks ]Handle pending events. Ifidletasks is specified, only those operationsnormally deferred until idle state are processed.

uplevel [level] arg [arg ...]Evaluates concatenation ofarg' s in the variable context indicated bylevel,an integer that gives the distance up the calling stack. Iflevel is preceded by“#”, then it gives the distance down the calling stack from toplevel.

14


Frame

-borderwidth -highlightbackground -relief-cursor -highlightcolor -takefocus-height -highlightthickness -width

-background colorSame as standard expect it may be the empty string to preserve colormap.

-class nameClass name to use in querying the option database and for bindings.

-colormap colormapColormap to use for the window if different from parent.

-visual visualVisual info to use for the window if different from parent.

Label

-anchor -height -pady-background -highlightbackground -relief-bitmap -highlightcolor -takefocus-borderwidth -highlightthickness -text-cursor -image -textvariable-font -justify -underline-foreground -padx -width

-wraplength

Menubutton

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

-indicatoron booleanIf true then a small indicator will be displayed on the buttons's right side andthe default menu bindings will treat this as an option menubutton.

-menu pathNamePathname of menu widget to post when button is invoked.

Message

-anchor -highlightbackground -relief-background -highlightcolor -takefocus-borderwidth -highlightthickness -text-cursor -justify -textvariable-font -padx -width-foreground -pady

31


-anchor -height -state-background -highlightbackground -takefocus-bitmap -highlightcolor -text-borderwidth -highlightthickness -textvariable-command -image -underline-cursor -justify -width-disabledforeground-padx -wraplength

buttonflashAlternate checkbutton between active and normal colors.

buttoninvokeToggle the selection state of the checkbutton and invoke the Tcl commandspecified with-command, if any.

Checkbutton

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

-indicatoron booleanWhether or not the indicator should be drawn.

-offvalue valueValue given to variable specified with-variable option when thecheckbutton is deselected.

-onvalue valueValue given to variable specified with-variable option when thecheckbutton is selected.

-selectcolor colorColor used to fill in indicator when selected.

-selectimage imageImage displayed in indicator when selected.

-variable variableVariable to associate with checkbutton.

checkbuttondeselectDeselect the checkbutton.

checkbuttonflashAlternate checkbutton between active and normal colors.

checkbuttoninvokeToggle the selection state of the checkbutton and invoke the Tcl commandspecified with-command, if any.

checkbuttonselectSelect the checkbutton.

checkbuttontoggleToggle the selection state of the checkbutton.

30


upvar [level] otherVar myVar[otherVar myVar...]MakesmyVarin local scope equivalent tootherVarat contextlevelso theyshare the same storage space.

vwait varNamePause program until global variablevarNameis modified.

19. General Tk Widget Information

All widget are created with

widget pathname[ option1 value1[ option2... ] ]

wherewidgetis the Tcl command corresponding to the class of widget desired (eg.button ) andpathnameis a string which will be used to identify the newly createdwidget. In general, a widget name is the concatenation of its parent's namefollowed by a period (unless the parent is the root window “. ”) and a stringcontaining no periods (eg..mainframe.btnframe.btn1 ).

Widget configuration options may be passed in the creation command. Optionsbegin with a “- ” and are always followed by a value string. After creation, optionsmay be changed using theconfigure widget command

pathnameconfigure option1 value1[ option2... ]

and queried using thecget command

pathnamecget option

Some of the widget options which multiple widgets support are described here forbrevity. For options that take screen units, values are in pixels unless an optionalone letter suffix modifier is present —c (cm), i (inch),m(mm), orp (points).

-activebackground colorBackground color of widget when it is active.

-activeborderwidth widthWidth in screen units of widget border when it is active.

-activeforeground colorForeground color of widget when it is active.

-anchor anchorPosHow information is positioned inside widget. ValidanchorPosvalues aren,ne, e, se, s, sw, w, nw, andcenter .

-background colorBackground color of widget in normal state (Abbrev:-bg ).

-bitmap bitmapBitmap to display in the widget (error, gray12, gray50,gray25, hourglass, info, questhead, question,warning, @ filename).

-borderwidth widthWidth in screen units of widget border in normal state (Abbrev:-bd ).

-command tclCommandTcl command to run when widget is invoked.

-cursor cursorCursor to display when mouse pointer is in widget.

-disabledforeground colorForeground color of widget when it is disabled.

-exportselection booleanWhether or not a selection in the widget should also be the X selection.

15


-font fontFont to use when drawing text inside the widget.

-foreground colorForeground color of widget in normal state (Abbrev:-fg ).

-geometry widthxheightGeometry for the widget's window. The units forwidthandheightdependon the particular widget (usually in characters when widget has text).

-height width| textCharsHeight of widget. Units depend on widget.

-highlightbackground colorColor of the rectangle drawn around the widget when it does not have theinput focus.

-highlightcolor colorColor of the rectangle drawn around the widget when it has the input focus.

-highlightthickness widthWidth in screen units of highlight rectangle drawn around widget when ithas the input focus.

-image imageImage to display in the widget (see Images).

-insertbackground colorColor to use as background in the area covered by the insertion cursor.

-insertborderwidth widthWidth in screen units of border to draw around the insertion cursor.

-insertofftime millisecondsTime the insertion cursor should remain “off” in each blink cycle.

-insertontime millisecondsTime the insertion cursor should remain “on” in each blink cycle.

-insertwidth widthWidth in screen units of the insertion cursor.

-jump booleanWhether to notify scrollbars and scales connected to the widget to delayupdates until mouse button is released.

-justify left|center|rightHow multiple lines line up witheach other.

-orient horizontal|verticalWhich orientation widget should use in layout.

-padx widthExtra space in screen units to request for the widget in X-direction.

-pady heightExtra space in screen units to request for the widget in Y-direction.

-relief flat|groove|raised|ridge|sunken3-D effect desired for the widget's border.

-repeatdelay millisecondsTime a button or key must be held down before it begins to auto-repeat.

-repeatinterval millisecondsTime between auto-repeats once action has begun.

-selectbackground colorBackground color to use when displaying selected items.

-selectborderwidth widthWidth in screen units of border to draw around selected items.

16


textsearch [switches] pattern index[stopIndex]Returns index of first character matchingpatternin text rangeindextostopIndex. Switches:-forwards, -backwards, -exact, -regexp,

-count var, -nocase

textsee indexAdjust the view in window so character atindexis completely visible.

text tag add tagName index1[index2]Apply tagtagNameto range (index2defaults toindex1+ 1 char ).

text tag bind tagName[sequence[script]]Arrange forscript to be run whenever eventsequenceoccurs for a characterwith tagtagName.

text tag cget tagName optionReturn current value ofoptionfor tagtagName.

text tag configure tagName[option[value[option value...]]]Modifies tag-specific options for the tagtagName.

text tag delete tagName[tagName...]Delete all tag information for given tags.

text tag lower tagName[belowThis]Change priority of tagtagNameso it is just below tagbelowThis.

text tag names [index]Returns a list of the names of all tags associated with character atindex. Ifindexis not given, returns list of all tags defined in widget.

text tag nextrange tagName index1[index2]Searches character rangeindex1to index2(defaultend ) for the first regiontagged withtagName. Returns character range of region found.

text tag prevrange tagName index1[index2]Like nextrange but searchs backwards fromindex1to index2(default 1.0).

text tag raise tagName[aboveThis]Change priority of tagtagNameso it is just above tagaboveThis.

text tag ranges tagNameReturns a list describing all character ranges tagged withtagName.

text tag remove tagName index1[index2]Remove tagtagNamefor all characters in rangeindex1to index2.

textwindow cget index optionReturn current value ofoptionfor embedded window atindex.

textwindow configure index[option[value[option value...]]]Modifies embedded window-specific options for the window atindex.

textwindow create index[option value...]Create a new embedded window at positionindexwith specified options.

textwindow namesReturns list of names of all windows embedded in widget.

textxview | yview argsSee Widget Scroll Commands above.

27. Other Standard Widgets

Button

-activebackground -font -pady-activeforeground -foreground -relief

29


Text Embedded Window Options

-align top|center|bottom|baselineWhere window is displayed on the line.

-create scriptScript to create and return window pathname if no-window option isgiven.

-padx widthExtra space in screen units to leave on the left and right side of window.

-pady heightExtra space in screen units to leave on the top and bottom of window.

-stretch booleanWhether window should be stretched vertically to fill line.

-window pathNameName of window to display

Text Widget Commands

textbbox indexReturns a list{ x y width height} bounding character atindex.

textcompare index1 op index2Compares indicesindex1andindex2according to relational operaterop.

textdelete index1[index2]Delete range of characters (index2defaults toindex1+ 1 char ).

textdlineinfo indexReturns a list{ x y width height baseline} describing the screen area takenby display line atindex.

textdump [switches] index1[index2]Returns detailed info on text widget contents in rangeindex1to index2.Switches include-all , -mark , -tag , -text , -window for specifyingtype of info returned. The switch-command commmandexists to invoke aprocedure on each element type in the range.

textget index1[index2]Returns string of characters in range (index2defaults toindex1+ 1 char ).

text index indexReturns positionindexin line.charnotation.

text insert index[string [tagList string tagList...]]Insertstring into text atindexapplying tags fromtagList.

textmark gravity markName[left|right ]Returns (or sets) which adjacent character a mark is attached to.

textmark namesReturns a list of the names of all marks currently set.

textmark next | previous indexReturn name of next/previous mark at or after/beforeindex.

textmark set markName indexSet markmarkNameto position just before character atindex.

textmark unset markName[markName...]Remove each mark specified so they are no longer usuable as indices.

textscan argsSee Widget Scroll Commands above.

28


-selectforeground colorForeground color to use when displaying selected items.

-setgrid booleanWhether this widget controls the resizing grid for its toplevel window.

-state normal|disabled (|active for button-type widgets)Current state of widget.

-takefocus focusTypeIf 0 or 1, signals that the widget should never or always take the focus. Ifempty, Tk decides. Otherwise, evalutes argument as script with widget nameappended as argument. Returned value must be0, 1 or empty.

-text stringText to be displayed inside the widget.

-textvariable variableVariable which containes a text string to be displayed inside the widget.

-troughcolor colorColor to use for the rectangular trough areas in widget.

-underline indexInteger index of a character to underline in the widget.

-width width| textCharsWidth of widget. Units depend on widget.

-wraplength lengthMaximum line length in screen units for word-wrapping.

-xscrollcommand cmdPrefixPrefix for a command used to communicate with horizontal scrollbars.

-yscrollcommand cmdPrefixPrefix for a command used to communicate with vertical scrollbars.

20. Tk Special Variables

tk_libraryDirectory containing library of standard Tk scripts.

tk_patchLevelInteger specifying current patch level for Tk.

tkPrivArray containing information private to standard Tk scripts.

tk_strictMotifWhen non-zero, Tk tries to adhere to Motif look-and-feel as closely aspossible.

tk_versionCurrent version of Tk inmajor.minor form.

21. Widget Scroll Commands

The Canvas, Listbox and Text widgets support the following scrolling commands.The Entry widget supports thexview command and thescan command with theycoordinate dropped.

widgetscan mark x yRecordsx andy as widget's current view anchor.

17


widgetscan dragto x yShift the view by 10 times the difference between the coordinatesx andyand the current view anchor coordinates.

widgetxviewReturn a two element list specifying the fraction of the horizontal span of thewidget at the left and right edges of the window.

widgetxview moveto fractionAdjust the view in the window so thatfractionof the total width of thewidget is off-screen to the left.

widgetxview scroll numberunits|pagesShift the view bynumberone-tenth's (unit ) or nine-tenth's (pages ) thewindow's width in the horizontal direction.

widgetyviewReturn a two element list specifying the fraction of the vertical span of thewidget at the top and bottom edges of the window.

widgetyview moveto fractionAdjust the view in the window so thatfractionof the total height of thewidget is off-screen to the top.

widgetyview scroll numberunits|pagesShift the view bynumberone-tenth's (unit ) or nine-tenth's (pages ) thewindow's height in the vertical direction.

The Text Widget also supports the following:

textyview [-pickplace ] indexChanges view of widget's window to make character atindexvisible. If-pickplace is specified,indexwill appear at the top of the window.

The Entry (xview only) and Listbox Widget also supports the following:

listboxxview indexAdjusts view so that character positionindexis at left edge.

listboxyview indexAdjusts view so that element atindexis at top of window.

22. The Canvas Widget

Canvas Options

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

-closeenough floatHow close the mouse cursor must be to an item before it is considered to be“inside” the item.

-confine booleanWhether it is allowable to set the canvas's view outside the scroll region.

18


26. The Text Widget

Text Widget Options

-background -highlightthickness -selectbackground-borderwidth -insertbackground -selectborderwidth-cursor -insertborderwidth -selectforeground-exportselection -insertofftime -setgrid-font -insertontime -state-foreground -insertwidth -takefocus-height -padx -width-highlightbackground-pady -xscrollcommand-highlightcolor -relief -yscrollcommand

-spacing1 size Space in screen units above paragraphs.

-spacing2 size Space in screen units between paragraph lines.

-spacing3 size Space in screen units below paragraphs.

-tabs tabListSet of tab stops as a list of screen distances giving their positions. Each stopmay be followed by one ofleft , right , center , or numeric .

-wrap none|char|word How to wrap lines.

Text Indices

Syntax: base[modifier... ]

Base: line.char, @x,y, end , mark, tag.first , tag.last , pathName

Modifier: � countchars , � countlines , linestart , lineend ,wordstart , wordend

Ranges: Ranges include all characters from the start index upto but notincluding the character at the stop index.

Text Tag Options

-background -justify -spacing2-borderwidth -relief -spacing3-font -spacing1 -wrap-foreground

-bgstipple bitmap Stipple pattern for background.

-fgstipple bitmap Stipple pattern for foreground.

-lmargin1 size Left margin of first line of a paragraph.

-lmargin2 size Left margin of wrapped lines of a paragraph.

-offset size Offset of baseline from normal baseline.

-overstrike boolean Whether to overstrike text.

-rmargin size Right margin of all lines.

-tabs tabList Set of tab stops (see-tabs above).

-underline boolean Whether to underline text.

27


menuentryconfigure index[option value...]Set option values for entry atindex.

menuindex indexReturns the numerical index corresponding toindex.

menuinsert index type[option value...]Same asadd but inserts new entry just before entry atindex.

menuinvoke indexInvoke the action of the menu entry atindex.

menupost x yDisplay menu on screen at root-window coordinates given byx y.

menupostcascade indexPost submenu associated with cascade entry atindex.

menutype indexReturns type of menu entry atindex.

menuunpostUnmap window so it is no longer displayed.

menuypostion indexReturns the y-coordinate within the menu window of the topmost pixel inthe entry specified byindex.

Menu Entry Options

The following options work for all cascade, checkbutton, command, andradiobutton entries unless otherwise specified.

-activebackground -bitmap -image-activeforeground -font -state-background -foreground -underline

-accelerator stringSpecifies string to display at right side of menu entry.

-command tclCommandTCL command to execute entry is invoked.

-indicatoron booleanWhether indictor for checkbutton or radiobutton entry should be displayed.

-label stringTextual string to display on left side of menu entry.

-menu pathNamePathname to a menu to post when cascade entry is active.

-offvalue valueValue to store in checkbutton entry's associated variable when deselected.

-onvalue valueValue to store in checkbutton entry's associated variable when selected.

-selectcolor colorColor for indicator in checkbutton and radiobutton entries.

-selectimage imageImage to draw in indicator for checkbutton and radiobutton entries.

-value valueValue to store in radiobutton entry's associated variable when selected.

-variable varaibleName of global variable to set when checkbutton or radiobutton is selected.

26


-scrollregion cornersList of four coordinates describing the left, top, right, and bottom of arectangular scrolling region.

-xscrollincrement distanceSpecifies the increment for horizontal scrolling in screen units.

-yscrollincrement distanceSpecifies the increment for vertical scrolling in screen units.

Coordinate examples: 5 (pixel), 2.2i (inch), 4.1c (cm), 3m (mm), 21p (pts)

Larger y-coordinates refer to points lower on the screen.

Larger x-coordinates refer to points farther to the right.

Character positions:charIndex, end , insert , sel.first , sel.last , @x,y

Canvas Commands

canvasaddtag tag searchSpec[arg arg ...]Add tag to the list of tags associated with each item that satisfysearchSpec.See Canvas Search Specs below.

canvasbbox tagOrId [tagOrId ...]Returns a list with four elements giving an approximate bounding box for allthe items named by the tagOrId arguments.

canvasbind tagOrId [sequence[command]]Associatescommandto be invoked on events specified withsequencewiththe items given bytagOrId.

canvascanvasx screenx[gridspacing]Returns the canvas x-coordinate that is displayed at screen x-coordinatescreenxpossibly rounding to nearest multiple ofgridspacingunits.

canvascanvasy screeny[gridspacing]Returns the canvas x-coordinate that is displayed at screen y-coordinatescreenypossibly rounding to nearest multiple ofgridspacingunits.

canvascoords tagOrId [x0 y0...]Query or modify the coordinates that define an item.

canvascreate type x y[x y ...] [option value...]Create a new item of typetypeat specified coordinates and with list options.

canvasdchars tagOrId first[last]For items given bytagOrId, delete the characters in the range given byfirstandlast (defaults tofirst), inclusive.

canvasdelete [tagOrId ...]Delete each of the items given by eachtagOrId.

canvasdtag tagOrId [tagToDelete]Remove tagtagToDeletefrom the taglist of items given bytagOrId.

canvasfind searchSpec[arg arg ...]Returns a list of the items that satisfy the specificationsearchSpec. SeeCanvas Search Specs below.

canvasfocus tagOrIdSet the focus to the first textual item given bytagOrId.

canvasgettags tagOrIdReturn a list of the tags associated with the first item given bytagOrId.

19


canvasicursor tagOrId indexSet the insertion cursor for the item(s) given bytagOrId to just beforethecharacter positionindex.

canvasindex tagOrId indexReturns a decimal string giving the numerical index withintagOrIdcorresponding to character positionindex.

canvasinsert tagOrId beforeThis stringInsertstring just before character positionbeforeThisin items given bytagOrId that support textual insertion.

canvasitemcget tagOrId optionReturns the valueoptionfor the item given bytagOrId.

canvasitemconfigure tagOrId [option value...]Modifies item-specific options for the items given bytagOrId.

canvaslower tagOrId [belowThis]Move the items given bytagOrIdto a new position in the display list justbefore the first item given bybelowThis.

canvasmove tagOrId xAmount yAmountMove the items given bytagOrId in the canvas coordinate space by addingxAmountandyAmountto each items x and y coordinates, respectively.

canvaspostscript [option value...]Generate a Encapsulated Postscript representation for part or all of thecanvas. See Canvas Postscript Options below.

canvasraise tagOrId [aboveThis]Move the items given bytagOrIdto a new position in the display list justafter the first item given byaboveThis.

canvasscale tagOrId xOrigin yOrigin xScale yScaleRescale items given bytagOrId in canvas coordinate space to change thedistance fromxOrigin,yOrigin by a factor ofxScale,yScalerespectively.

canvasscan argsSee Widget Scroll Commands above.

canvasselect adjust tagOrId indexAdjust nearest end of current selection intagOrId to be atindexand set theother end to be the new selection anchor.

canvasselect clearClear the selection if it is in the widget.

canvasselect from tagOrId indexSet the selection anchor intagOrId to just before the character atindex.

canvasselect itemReturn id of the selected item. Returns a empty string if there is none.

canvasselect to tagOrId indexSet the selection to extend betweenindexand anchor point intagOrId.

canvastype tagOrIdReturns the type of the first item given bytagOrId.

canvasxview | yview argsSee Widget Scroll Commands above.

Canvas Search Specifications

above tagOrIdSelects the item just after the one given bytagOrId in the display list.

20


listboxselection anchor indexSet the selection anchor to element atindex.

listboxselection clear first [last]Deselect elements betweenfirst andlast inclusive.

listboxselection includes indexReturns 1 if element atindexis selected, 0 otherwise.

listboxselection set first [last]Add all elements betweenfirst andlast inclusive to selection.

listboxsee indexAdjust the view in window so element atindexis completely visible.

listboxsizeReturns number of elements in listbox.

listboxxview | yview argsSee Widget Scroll Commands above.

25. The Menu Widget

Menu Widget Options

-activebackground -borderwidth -font-activeborderwidth -cursor -foreground-activeforeground -disabledforeground -relief-background

-postcommand tclCommandSpecify Tcl command to invoke immediately before the menu is posted.

-selectcolor colorSpecifies indicator color for checkbutton and radiobutton entries.

-tearoff booleanWhether to include a tear-off entry at top of menu.

-tearoffcommand tclCmdSpecifies command to be run when menu is torn off. The name of the menuand the new torn-off window will be appended on invocation.

-transient booleanWhether menu should be displayed as transient or not.

Entry Types: cascade, checkbutton, command, radiobutton,separator

Menu Indices: number, active, last, none, @ y-coord, matchPattern

Menu Widget Commands

menuactivate indexChange state of entry atindexto be sole active entry in menu.

menuadd type[option value...]Add new entry of typetypeto bottom of menu. See below for options.

menudelete index1[index2]Delete all entries betweenindex1andindex2inclusive.

menuentrycget index optionReturn current value ofoptionfor entry atindex.

25


entryselection adjust indexAdjust nearest end of current selection to be atindexand set the other end tothe anchor point.

entryselection clearClear the selection if currenly in the widget.

entryselection from indexSet the anchor point to be atindex.

entryselection presentReturns 1 is any characters are selected, 0 otherwise.

entryselection range start endSelect the characters fromstart through character just beforeend.

entryselection to indexSet the selection to extend betweenindexand anchor point.

24. The Listbox Widget

Listbox Widget Options

-background -height -selectborderwidth-borderwidth -highlightbackground-selectforeground-cursor -highlightcolor -setGrid-exportselection -highlightthickness -takefocus-font -relief -width-foreground -selectbackground -xscrollcommand

-yscrollcommand

-selectMode single|browse|multiple|extended

Listbox Indices: number(starts at 0),active , anchor , end , @x,y

Listbox Widget Commands

listboxactivate indexSets the active element toindex.

listboxbbox indexReturns a list{ x y width height} bounding element atindex.

listboxcurselectionReturns list of indices of all elements currently selected.

listboxdelete index1[index2]Delete range of elements fromindex1to index2(defaults toindex1).

listboxget index1[index2]Return as a list contents of elements fromindex1to index2.

listboxindex indexReturns positionindexin numbernotation.

listboxinsert index[element...]Insert specified elements just before element atindex.

listboxnearest yReturn index of element nearest toy-coordinate.

listboxscan argsSee Widget Scroll Commands above.

24


all Selects all the items in the canvas.

below tagOrIdSelects the item just before the one given bytagOrId in the display list.

closest x y [halo] [start]Select the topmost, closest item to @x,y that is belowstart in the display list.Any item closer thanhalo to the point is considered to overlap it.

enclosed x1 y1 x2 y2Selects all the items completely enclosed withinx1 y1 x2 y2.

overlapping x1 y1 x2 y2Selects all the items that overlap or are enclosed withinx1 y1 x2 y2.

withtag tagOrIdSelects all the items given bytagOrId.

Canvas Item Types

canvascreate arc x1 y1 x2 y2[option value...]

-fill color -stipple bitmap -width outlineWidth-outline color -tags tagList

-extent degreesSize of the angular range occupied by arc.

-outlinestipple bitmapBitmap stipple to use to draw arc's outline.

-start degreesStarting angle measured from 3-o' clock position.

-style pieslice|chord|arcHow to “complete” the region of the arc.

canvascreate bitmap x y [option value...]

-anchor anchorPos -bitmap bitmap -tags tagslist-background color -foreground color

canvascreate image x y [option value...]

-anchor anchorPos -image image -tags tagslist

canvascreate line x1 y1 ... xN yN[option value...]

-fill color -stipple bitmap -width outlineWidth-smooth boolean -tags tagList

-arrow none|first|last|bothSpecify on which ends of the line to draw arrows.

-arrowshape shapeThree element list which describes shape of arrow.

-capstyle butt|projecting|roundHow to draw caps at endpoints of the line. Default isbutt .

-joinstyle bevel|miter|roundHow joints are to be drawn at vetices. Default ismiter .

-splinesteps numberDegree of smoothness desired for curves.

21


canvascreate oval x1 y1 x2 y2[option value...]


canvascreate polygon x1 y1 ... xN yN[option value...]

-fill color -smooth boolean -tags tagList-outline color -stipple bitmap -width outlineWidth

-splinesteps numberDegree of smoothness desired for curved perimeter.

canvascreate rectangle x1 y1 x2 y2[option value...]


canvascreate text x y [option value...]

-anchor anchorPos -font font -tags tagList-fill color -stipple bitmap -text string

-justify left|right|centerHow to justify text within its bounding region.

-width lineLengthMaximum line length for the text. If zero, break only onnn.

canvascreate window x y [option value...]

-anchor anchorPos -tags tagList

-height height Height in screen units to assign item's window.

-width width Width in screen utnis to assign item's window.

-window pathName Window to associate with item.

Canvas Postscript Options

-colormap varNameSpecifies a color mapping to use wherevarNameis an array variable whoseelements specify Postscript code to set a particular color value.

-colormode color|grey|monoSpecifies how to output color information.

-file fileNameSpecifies the name of the file in which to write the Postscript. If notspecified, the Postscript is returned as the result of the command.

-fontmap varNameSpecifies a font mapping to use wherevarNameis an array variable whoseelements specify the Postscript font and size to use as a two element list.

-height sizeSpecifies the height of the area of the canvas to print. Defaults to the heightof the canvas window

-pageanchor anchorSpecifies which point of the printed area should be appear over thepositioning point on the page. Defaults tocenter .

-pageheight sizeSpecifies that the Postscript should be scaled in both x and y so that theprinted area issizehigh on the Postscript page.

22


-pagewidth sizeSpecifies that the Postscript should be scaled in both x and y so that theprinted area issizewide on the Postscript page.

-pagex positionSet the x-coordinate of the positioning point on the page toposition.

-pagey positionSet the y-coordinate of the positioning point on the page toposition.

-rotate booleanWhether the printed area is to be rotated 90 degrees. (“landscape”).

-width sizeSpecifies the width of the area of the canvas to print. Defaults to the width ofthe canvas window

-x positionSet the x-coordinate of the left edge of canvas area to print.

-y positionSet the y-coordinate of the top edge of canvas area to print.

23. The Entry Widget

Entry Widget Options

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

-justify -width

-show booleanWhether to show actual character or “*” in entry.

Entry Indices: number, anchor, end, insert, sel.first,sel.last, @x-coord

Entry Widget Commands

entrybbox indexReturns bounding box of character given byindex.

entrydelete first [last]Delete characters fromfirst through character just beforelast.

entrygetReturns the entry's string.

entry icursor indexDisplay insertion cursor just before character atindex.

entry index indexReturns the numerical index corresponding toindex.

entry insert index stringInsertstring just before character atindex.

entryscan option argsSee Widget Scroll Commands above.

23

Contents Tcl/Tk Reference Guidetitania.ctie.monash.edu.au/refcards/rfk-0013.pdf · Tcl/Tk Reference...

Documents

Transcript of Contents Tcl/Tk Reference Guidetitania.ctie.monash.edu.au/refcards/rfk-0013.pdf · Tcl/Tk Reference...