Tcl8.5.5/Tk8.5.5 Documentation

Table of ContentsTcl8.5.5/Tk8.5.5 Documentation..........................................................................................................................1

Tcl/Tk Applications..........................................................................................................................................................1Tcl8.5.5/Tk8.5.5 Documentation > Tcl/Tk Applications.....................................................................................2tclsh.......................................................................................................................................................................5wish.......................................................................................................................................................................9

Tcl Commands..................................................................................................................................................................9Tcl8.5.5/Tk8.5.5 Documentation > Tcl Commands...........................................................................................11Tcl.......................................................................................................................................................................15after.....................................................................................................................................................................18append.................................................................................................................................................................19apply....................................................................................................................................................................21array....................................................................................................................................................................25bgerror.................................................................................................................................................................27binary..................................................................................................................................................................40break....................................................................................................................................................................41catch....................................................................................................................................................................43cd.........................................................................................................................................................................44chan.....................................................................................................................................................................56clock....................................................................................................................................................................72close....................................................................................................................................................................74concat..................................................................................................................................................................76continue...............................................................................................................................................................77dde.......................................................................................................................................................................80dict.......................................................................................................................................................................86encoding..............................................................................................................................................................88eof.......................................................................................................................................................................90error.....................................................................................................................................................................92eval......................................................................................................................................................................94exec...................................................................................................................................................................101exit.....................................................................................................................................................................103expr...................................................................................................................................................................110fblocked.............................................................................................................................................................112fconfigure..........................................................................................................................................................117fcopy.................................................................................................................................................................120file.....................................................................................................................................................................128fileevent.............................................................................................................................................................130filename.............................................................................................................................................................134flush...................................................................................................................................................................135for......................................................................................................................................................................137foreach...............................................................................................................................................................139format................................................................................................................................................................144gets....................................................................................................................................................................146

Tcl8.5.5/Tk8.5.5 Documentation

i

Table of ContentsTcl Commands

glob...................................................................................................................................................................150global.................................................................................................................................................................152history...............................................................................................................................................................155http....................................................................................................................................................................165if........................................................................................................................................................................167incr....................................................................................................................................................................169info....................................................................................................................................................................175interp.................................................................................................................................................................188join....................................................................................................................................................................189lappend..............................................................................................................................................................190lassign...............................................................................................................................................................192library................................................................................................................................................................198lindex.................................................................................................................................................................200linsert.................................................................................................................................................................201list......................................................................................................................................................................203llength...............................................................................................................................................................205load....................................................................................................................................................................208lrange.................................................................................................................................................................210lrepeat................................................................................................................................................................211lreplace..............................................................................................................................................................213lreverse..............................................................................................................................................................214lsearch...............................................................................................................................................................218lset.....................................................................................................................................................................221lsort...................................................................................................................................................................225mathfunc...........................................................................................................................................................230mathop...............................................................................................................................................................236memory.............................................................................................................................................................239msgcat...............................................................................................................................................................245namespace.........................................................................................................................................................259open...................................................................................................................................................................267package.............................................................................................................................................................273packagens..........................................................................................................................................................275pid.....................................................................................................................................................................276pkgMkIndex......................................................................................................................................................280platform.............................................................................................................................................................282platform_shell...................................................................................................................................................284proc...................................................................................................................................................................286puts....................................................................................................................................................................288pwd....................................................................................................................................................................289re_syntax...........................................................................................................................................................302read....................................................................................................................................................................304refchan...............................................................................................................................................................309regexp................................................................................................................................................................313

Tcl8.5.5/Tk8.5.5 Documentation

ii

Table of ContentsTcl Commands

registry..............................................................................................................................................................317regsub................................................................................................................................................................320rename...............................................................................................................................................................321return.................................................................................................................................................................326safe....................................................................................................................................................................332scan...................................................................................................................................................................337seek...................................................................................................................................................................339set......................................................................................................................................................................341socket................................................................................................................................................................345source................................................................................................................................................................347split....................................................................................................................................................................349string.................................................................................................................................................................356subst..................................................................................................................................................................359switch................................................................................................................................................................363tcltest.................................................................................................................................................................382tclvars................................................................................................................................................................389tell.....................................................................................................................................................................391time...................................................................................................................................................................392tm......................................................................................................................................................................397trace...................................................................................................................................................................404unknown............................................................................................................................................................406unload................................................................................................................................................................410unset..................................................................................................................................................................412update................................................................................................................................................................414uplevel...............................................................................................................................................................416upvar.................................................................................................................................................................418variable..............................................................................................................................................................420vwait..................................................................................................................................................................422while..................................................................................................................................................................424

Tk Commands..............................................................................................................................................................424Tcl8.5.5/Tk8.5.5 Documentation > Tk Commands..........................................................................................425bell.....................................................................................................................................................................426bind...................................................................................................................................................................438bindtags.............................................................................................................................................................440bitmap...............................................................................................................................................................443button................................................................................................................................................................448canvas................................................................................................................................................................478checkbutton.......................................................................................................................................................485chooseColor......................................................................................................................................................486chooseDirectory................................................................................................................................................488clipboard...........................................................................................................................................................491colors.................................................................................................................................................................517

Tcl8.5.5/Tk8.5.5 Documentation

iii

Table of ContentsTk Commands

console..............................................................................................................................................................520cursors...............................................................................................................................................................524destroy...............................................................................................................................................................525dialog.................................................................................................................................................................527entry..................................................................................................................................................................538event..................................................................................................................................................................546focus..................................................................................................................................................................549focusNext..........................................................................................................................................................550font....................................................................................................................................................................557frame.................................................................................................................................................................561getOpenFile.......................................................................................................................................................565grab...................................................................................................................................................................568grid....................................................................................................................................................................575image.................................................................................................................................................................578keysyms.............................................................................................................................................................595label...................................................................................................................................................................599labelframe.........................................................................................................................................................604listbox................................................................................................................................................................614loadTk...............................................................................................................................................................616lower.................................................................................................................................................................617menu..................................................................................................................................................................631menubutton.......................................................................................................................................................636message.............................................................................................................................................................640messageBox......................................................................................................................................................642option................................................................................................................................................................644optionMenu.......................................................................................................................................................645options...............................................................................................................................................................653pack...................................................................................................................................................................658palette................................................................................................................................................................660panedwindow....................................................................................................................................................667photo.................................................................................................................................................................675place..................................................................................................................................................................679popup.................................................................................................................................................................680radiobutton........................................................................................................................................................687raise...................................................................................................................................................................688scale...................................................................................................................................................................694scrollbar.............................................................................................................................................................701selection............................................................................................................................................................705send...................................................................................................................................................................708spinbox..............................................................................................................................................................721text.....................................................................................................................................................................756tk.......................................................................................................................................................................759tkerror................................................................................................................................................................760

Tcl8.5.5/Tk8.5.5 Documentation

iv

Table of ContentsTk Commands

tkvars.................................................................................................................................................................762tkwait.................................................................................................................................................................763toplevel..............................................................................................................................................................767ttk_button..........................................................................................................................................................770ttk_checkbutton.................................................................................................................................................773ttk_combobox...................................................................................................................................................777ttk_entry............................................................................................................................................................786ttk_frame...........................................................................................................................................................788ttk_image...........................................................................................................................................................790ttk_intro.............................................................................................................................................................793ttk_label.............................................................................................................................................................796ttk_labelframe...................................................................................................................................................799ttk_menubutton.................................................................................................................................................801ttk_notebook.....................................................................................................................................................806ttk_panedwindow..............................................................................................................................................809ttk_progressbar..................................................................................................................................................812ttk_radiobutton..................................................................................................................................................815ttk_scale............................................................................................................................................................818ttk_scrollbar......................................................................................................................................................822ttk_separator......................................................................................................................................................824ttk_sizegrip........................................................................................................................................................826ttk_style.............................................................................................................................................................829ttk_treeview.......................................................................................................................................................838ttk_widget.........................................................................................................................................................844winfo.................................................................................................................................................................850wm.....................................................................................................................................................................861

Tcl Library....................................................................................................................................................................861Tcl8.5.5/Tk8.5.5 Documentation > Tcl Library...............................................................................................867Access...............................................................................................................................................................869AddErrInfo........................................................................................................................................................874Alloc..................................................................................................................................................................877AllowExc..........................................................................................................................................................878AppInit..............................................................................................................................................................880AssocData.........................................................................................................................................................882Async................................................................................................................................................................885BackgdErr.........................................................................................................................................................887Backslash..........................................................................................................................................................889BoolObj.............................................................................................................................................................891ByteArrObj.......................................................................................................................................................894CallDel..............................................................................................................................................................896ChnlStack..........................................................................................................................................................899CmdCmplt.........................................................................................................................................................900

Tcl8.5.5/Tk8.5.5 Documentation

v

Table of ContentsTcl Library

Concat...............................................................................................................................................................902CrtChannel........................................................................................................................................................919CrtChnlHdlr......................................................................................................................................................921CrtCloseHdlr.....................................................................................................................................................923CrtCommand.....................................................................................................................................................926CrtFileHdlr........................................................................................................................................................928CrtInterp............................................................................................................................................................931CrtMathFnc.......................................................................................................................................................934CrtObjCmd........................................................................................................................................................940CrtSlave.............................................................................................................................................................945CrtTimerHdlr....................................................................................................................................................947CrtTrace............................................................................................................................................................951DString..............................................................................................................................................................954DetachPids........................................................................................................................................................956DictObj..............................................................................................................................................................961DoOneEvent......................................................................................................................................................964DoWhenIdle......................................................................................................................................................966DoubleObj.........................................................................................................................................................968DumpActiveMemory........................................................................................................................................970Encoding...........................................................................................................................................................981Ensemble...........................................................................................................................................................986Environment......................................................................................................................................................987Eval...................................................................................................................................................................991Exit....................................................................................................................................................................994ExprLong..........................................................................................................................................................997ExprLongObj..................................................................................................................................................1000FileSystem.......................................................................................................................................................1027FindExec.........................................................................................................................................................1029GetCwd...........................................................................................................................................................1031GetHostName..................................................................................................................................................1032GetIndex..........................................................................................................................................................1035GetInt..............................................................................................................................................................1037GetOpnFl.........................................................................................................................................................1039GetStdChan.....................................................................................................................................................1041GetTime..........................................................................................................................................................1044GetVersion......................................................................................................................................................1045Hash................................................................................................................................................................1051Init...................................................................................................................................................................1052InitStubs..........................................................................................................................................................1055IntObj..............................................................................................................................................................1059Interp...............................................................................................................................................................1062Limit................................................................................................................................................................1067LinkVar...........................................................................................................................................................1071

Tcl8.5.5/Tk8.5.5 Documentation

vi

Table of ContentsTcl Library

ListObj............................................................................................................................................................1075Namespace......................................................................................................................................................1079Notifier............................................................................................................................................................1090Object..............................................................................................................................................................1096ObjectType......................................................................................................................................................1101OpenFileChnl..................................................................................................................................................1115OpenTcp..........................................................................................................................................................1119Panic................................................................................................................................................................1122ParseCmd........................................................................................................................................................1129PkgRequire......................................................................................................................................................1132Preserve...........................................................................................................................................................1134PrintDbl...........................................................................................................................................................1135RecEvalObj.....................................................................................................................................................1137RecordEval......................................................................................................................................................1139RegConfig.......................................................................................................................................................1142RegExp............................................................................................................................................................1148SaveResult.......................................................................................................................................................1151SetChanErr......................................................................................................................................................1155SetErrno..........................................................................................................................................................1157SetRecLmt.......................................................................................................................................................1158SetResult.........................................................................................................................................................1162SetVar.............................................................................................................................................................1167Signal..............................................................................................................................................................1168Sleep................................................................................................................................................................1169SourceRCFile..................................................................................................................................................1170SplitList...........................................................................................................................................................1174SplitPath..........................................................................................................................................................1176StaticPkg.........................................................................................................................................................1178StdChannels....................................................................................................................................................1181StrMatch..........................................................................................................................................................1183StringObj.........................................................................................................................................................1191SubstObj..........................................................................................................................................................1193TCL_MEM_DEBUG......................................................................................................................................1195Tcl_Main.........................................................................................................................................................1198Thread.............................................................................................................................................................1203ToUpper..........................................................................................................................................................1206TraceCmd........................................................................................................................................................1210TraceVar.........................................................................................................................................................1217Translate..........................................................................................................................................................1219UniCharIsAlpha..............................................................................................................................................1222UpVar..............................................................................................................................................................1224Utf...................................................................................................................................................................1230WrongNumArgs..............................................................................................................................................1232

Tcl8.5.5/Tk8.5.5 Documentation

vii

Table of ContentsTk Library..................................................................................................................................................................1232

Tcl8.5.5/Tk8.5.5 Documentation > Tk Library..............................................................................................12353DBorder.........................................................................................................................................................1241AddOption.......................................................................................................................................................1243BindTable........................................................................................................................................................1246CanvPsY.........................................................................................................................................................1249CanvTkwin......................................................................................................................................................1253CanvTxtInfo....................................................................................................................................................1255Clipboard.........................................................................................................................................................1257ClrSelect..........................................................................................................................................................1258ConfigWidg.....................................................................................................................................................1268ConfigWind.....................................................................................................................................................1272CoordToWin...................................................................................................................................................1273CrtCmHdlr......................................................................................................................................................1275CrtConsoleChan..............................................................................................................................................1276CrtErrHdlr.......................................................................................................................................................1279CrtGenHdlr.....................................................................................................................................................1281CrtImgType.....................................................................................................................................................1287CrtItemType....................................................................................................................................................1298CrtPhImgFmt..................................................................................................................................................1303CrtSelHdlr.......................................................................................................................................................1305CrtWindow......................................................................................................................................................1308DeleteImg........................................................................................................................................................1309DrawFocHlt.....................................................................................................................................................1310EventHndlr......................................................................................................................................................1312FindPhoto........................................................................................................................................................1317FontId..............................................................................................................................................................1320FreeXId...........................................................................................................................................................1321GeomReq........................................................................................................................................................1324GetAnchor.......................................................................................................................................................1326GetBitmap.......................................................................................................................................................1332GetCapStyl......................................................................................................................................................1334GetClrmap.......................................................................................................................................................1336GetColor..........................................................................................................................................................1340GetCursor........................................................................................................................................................1345GetDash...........................................................................................................................................................1347GetFont...........................................................................................................................................................1350GetGC.............................................................................................................................................................1352GetHINSTANCE............................................................................................................................................1353GetHWND......................................................................................................................................................1354GetImage.........................................................................................................................................................1357GetJoinStl........................................................................................................................................................1359GetJustify........................................................................................................................................................1361GetOption........................................................................................................................................................1362

Tcl8.5.5/Tk8.5.5 Documentation

viii

Table of ContentsTk Library

GetPixels.........................................................................................................................................................1365GetPixmap.......................................................................................................................................................1367GetRelief.........................................................................................................................................................1369GetRootCrd.....................................................................................................................................................1370GetScroll.........................................................................................................................................................1372GetSelect.........................................................................................................................................................1374GetUid.............................................................................................................................................................1375GetVRoot........................................................................................................................................................1376GetVisual........................................................................................................................................................1379Grab.................................................................................................................................................................1381HWNDToWindow..........................................................................................................................................1382HandleEvent....................................................................................................................................................1383IdToWindow...................................................................................................................................................1384ImgChanged....................................................................................................................................................1386Inactive............................................................................................................................................................1387InternAtom......................................................................................................................................................1389MainLoop........................................................................................................................................................1390MainWin.........................................................................................................................................................1391MaintGeom.....................................................................................................................................................1393ManageGeom..................................................................................................................................................1395MapWindow...................................................................................................................................................1396MeasureChar...................................................................................................................................................1399MoveToplev....................................................................................................................................................1401Name...............................................................................................................................................................1403NameOfImg....................................................................................................................................................1404OwnSelect.......................................................................................................................................................1405ParseArgv........................................................................................................................................................1411QWinEvent.....................................................................................................................................................1413Restack............................................................................................................................................................1414RestrictEv........................................................................................................................................................1416SetAppName...................................................................................................................................................1418SetCaret...........................................................................................................................................................1419SetClass...........................................................................................................................................................1421SetClassProcs..................................................................................................................................................1423SetGrid............................................................................................................................................................1425SetOptions.......................................................................................................................................................1436SetVisual.........................................................................................................................................................1437StrictMotif.......................................................................................................................................................1438TextLayout......................................................................................................................................................1444TkInitStubs......................................................................................................................................................1446Tk_Init.............................................................................................................................................................1448Tk_Main..........................................................................................................................................................1450WindowId.......................................................................................................................................................1455

Tcl8.5.5/Tk8.5.5 Documentation

ix

Table of ContentsTk Library

ttk_Geometry..................................................................................................................................................1461ttk_Theme.......................................................................................................................................................1462

Tcl/Tk Keywords........................................................................................................................................................1462Tcl8.5.5/Tk8.5.5 Documentation > Tcl/Tk Keywords...................................................................................1463A......................................................................................................................................................................1466B......................................................................................................................................................................1468C......................................................................................................................................................................1472D......................................................................................................................................................................1474E......................................................................................................................................................................1476F......................................................................................................................................................................1478G......................................................................................................................................................................1480H......................................................................................................................................................................1481I.......................................................................................................................................................................1484J.......................................................................................................................................................................1485K......................................................................................................................................................................1486L......................................................................................................................................................................1488M.....................................................................................................................................................................1490N......................................................................................................................................................................1491O......................................................................................................................................................................1493P......................................................................................................................................................................1496Q......................................................................................................................................................................1497R......................................................................................................................................................................1500S......................................................................................................................................................................1504T......................................................................................................................................................................1507U......................................................................................................................................................................1509V......................................................................................................................................................................1510W.....................................................................................................................................................................1512X......................................................................................................................................................................1513Y.......................................................................................................................................................................title

Tcl8.5.5/Tk8.5.5 Documentation

x

Tcl/Tk ApplicationsTcl8.5.5/Tk8.5.5 Documentation > Tcl/Tk Applications

Tcl/Tk Applications | Tcl Commands | Tk Commands | Tcl Library | Tk Library

tclsh wishCopyright 1991-1994 The Regents of the University of California Copyright 1994-1996 Sun Microsystems, IncCopyright 1995-1997 Roger E. Critchlow Jr

1

tclsh

Tcl8.5.5/Tk8.5.5 Documentation > UserCmd > tclsh

Tcl/Tk Applications | Tcl Commands | Tk Commands | Tcl Library | Tk Library

NAME

tclsh - Simple shell containing Tcl interpreterSYNOPSISDESCRIPTIONSCRIPT FILESVARIABLES

argcargvargv0tcl_interactive

PROMPTSSTANDARD CHANNELSSEE ALSOKEYWORDS

NAME

tclsh - Simple shell containing Tcl interpreter

SYNOPSIS

tclsh ?-encoding name? ?fileName arg arg ...?

DESCRIPTION

Tclsh is a shell-like application that reads Tcl commands from its standard input or from a file and evaluates them. Ifinvoked with no arguments then it runs interactively, reading Tcl commands from standard input and printingcommand results and error messages to standard output. It runs until the exit command is invoked or until it reachesend-of-file on its standard input. If there exists a file .tclshrc (or tclshrc.tcl on the Windows platforms) in the homedirectory of the user, interactive tclsh evaluates the file as a Tcl script just before reading the first command fromstandard input.

SCRIPT FILES

If tclsh is invoked with arguments then the first few arguments specify the name of a script file, and, optionally, theencoding of the text data stored in that script file. Any additional arguments are made available to the script asvariables (see below). Instead of reading commands from standard input tclsh will read Tcl commands from thenamed file; tclsh will exit when it reaches the end of the file. The end of the file may be marked either by the physical

Tcl/Tk Applications tclsh

2

end of the medium, or by the character, \032 (\u001a, control-Z). If this character is present in the file, the tclshapplication will read text up to but not including the character. An application that requires this character in the filemay safely encode it as \032, \x1a, or \u001a; or may generate it by use of commands such as format orbinary. There is no automatic evaluation of .tclshrc when the name of a script file is presented on the tclsh commandline, but the script file can always source it if desired.

If you create a Tcl script in a file whose first line is

#!/usr/local/bin/tclsh

then you can invoke the script file directly from your shell if you mark the file as executable. This assumes that tclshhas been installed in the default location in /usr/local/bin; if it is installed somewhere else then you will have tomodify the above line to match. Many UNIX systems do not allow the #! line to exceed about 30 characters in length,so be sure that the tclsh executable can be accessed with a short file name.

An even better approach is to start your script files with the following three lines:

#!/bin/sh# the next line restarts using tclsh \exec tclsh "$0" "$@"

This approach has three advantages over the approach in the previous paragraph. First, the location of the tclsh binarydoes not have to be hard-wired into the script: it can be anywhere in your shell search path. Second, it gets around the30-character file name limit in the previous approach. Third, this approach will work even if tclsh is itself a shellscript (this is done on some systems in order to handle multiple architectures or operating systems: the tclsh scriptselects one of several binaries to run). The three lines cause both sh and tclsh to process the script, but the exec is onlyexecuted by sh. sh processes the script first; it treats the second line as a comment and executes the third line. Theexec statement cause the shell to stop processing and instead to start up tclsh to reprocess the entire script. When tclshstarts up, it treats all three lines as comments, since the backslash at the end of the second line causes the third line tobe treated as part of the comment on the second line.

You should note that it is also common practice to install tclsh with its version number as part of the name. This hasthe advantage of allowing multiple versions of Tcl to exist on the same system at once, but also the disadvantage ofmaking it harder to write scripts that start up uniformly across different versions of Tcl.

VARIABLES

Tclsh sets the following Tcl variables:

argcContains a count of the number of arg arguments (0 if none), not including the name of the script file.

argvContains a Tcl list whose elements are the arg arguments, in order, or an empty string if there are no argarguments.

argv0Contains fileName if it was specified. Otherwise, contains the name by which tclsh was invoked.

Tcl/Tk Applications tclsh

3

tcl_interactiveContains 1 if tclsh is running interactively (no fileName was specified and standard input is a terminal-likedevice), 0 otherwise.

PROMPTS

When tclsh is invoked interactively it normally prompts for each command with % . You can change the prompt bysetting the variables tcl_prompt1 and tcl_prompt2. If variable tcl_prompt1 exists then it must consist of a Tcl scriptto output a prompt; instead of outputting a prompt tclsh will evaluate the script in tcl_prompt1. The variabletcl_prompt2 is used in a similar way when a newline is typed but the current command is not yet complete; iftcl_prompt2 is not set then no prompt is output for incomplete commands.

STANDARD CHANNELS

See Tcl_StandardChannels for more explanations.

SEE ALSO

encoding, fconfigure, tclvars

KEYWORDS

argument, interpreter, prompt, script file, shell

Copyright 1995-1997 Roger E. Critchlow Jr. Copyright 1993 The Regents of the University of California.Copyright 1994-1996 Sun Microsystems, Inc.

Tcl/Tk Applications tclsh

4

wish

Tcl8.5.5/Tk8.5.5 Documentation > UserCmd > wish

Tcl/Tk Applications | Tcl Commands | Tk Commands | Tcl Library | Tk Library

NAME

wish - Simple windowing shellSYNOPSISOPTIONS

-encoding name-colormap new-display display-geometry geometry-name name-sync-use id-visual visual--

DESCRIPTIONOPTION PROCESSINGAPPLICATION NAME AND CLASSVARIABLES

argcargvargv0geometrytcl_interactive

SCRIPT FILESPROMPTSKEYWORDS

NAME

wish - Simple windowing shell

SYNOPSIS

wish ?-encoding name? ?fileName arg arg ...?

OPTIONS

-encoding name

Tcl/Tk Applications wish

5

Specifies the encoding of the text stored in fileName. This option is only recognized prior to the fileNameargument.

-colormap newSpecifies that the window should have a new private colormap instead of using the default colormap for thescreen.

-display displayDisplay (and screen) on which to display window.

-geometry geometryInitial geometry to use for window. If this option is specified, its value is stored in the geometry globalvariable of the application's Tcl interpreter.

-name nameUse name as the title to be displayed in the window, and as the name of the interpreter for send commands.

-syncExecute all X server commands synchronously, so that errors are reported immediately. This will result inmuch slower execution, but it is useful for debugging.

-use idSpecifies that the main window for the application is to be embedded in the window whose identifier is id,instead of being created as an independent toplevel window. Id must be specified in the same way as the valuefor the -use option for toplevel widgets (i.e. it has a form like that returned by the winfo id command).

Note that on some platforms this will only work correctly if id refers to a Tk frame or toplevel thathas its -container option enabled.

-visual visualSpecifies the visual to use for the window. Visual may have any of the forms supported by the Tk_GetVisualprocedure.

--Pass all remaining arguments through to the script's argv variable without interpreting them. This provides amechanism for passing arguments such as -name to a script instead of having wish interpret them.

DESCRIPTION

Wish is a simple program consisting of the Tcl command language, the Tk toolkit, and a main program that readscommands from standard input or from a file. It creates a main window and then processes Tcl commands. If wish isinvoked with arguments, then the first few arguments, ?-encoding name? ?fileName? specify the name of a script file,and, optionally, the encoding of the text data stored in that script file. A value for fileName is recognized if theappropriate argument does not start with -.

If there are no arguments, or the arguments do not specify a fileName, then wish reads Tcl commands interactivelyfrom standard input. It will continue processing commands until all windows have been deleted or until end-of-file isreached on standard input. If there exists a file .wishrc in the home directory of the user, wish evaluates the file as aTcl script just before reading the first command from standard input.

If arguments to wish do specify a fileName, then fileName is treated as the name of a script file. Wish will evaluatethe script in fileName (which presumably creates a user interface), then it will respond to events until all windowshave been deleted. Commands will not be read from standard input. There is no automatic evaluation of .wishrcwhen the name of a script file is presented on the wish command line, but the script file can always source it ifdesired.

Tcl/Tk Applications wish

6

Note that on Windows, the wishversion.exe program varies from the tclshversion.exe program in an additionalimportant way: it does not connect to a standard Windows console and is instead a windowed program. Because ofthis, it additionally provides access to its own console command.

OPTION PROCESSING

Wish automatically processes all of the command-line options described in the OPTIONS summary above. Any othercommand-line arguments besides these are passed through to the application using the argc and argv variablesdescribed later.

APPLICATION NAME AND CLASS

The name of the application, which is used for purposes such as send commands, is taken from the -name option, if itis specified; otherwise it is taken from fileName, if it is specified, or from the command name by which wish wasinvoked. In the last two cases, if the name contains a / character, then only the characters after the last slash are usedas the application name.

The class of the application, which is used for purposes such as specifying options with a RESOURCE_MANAGERproperty or .Xdefaults file, is the same as its name except that the first letter is capitalized.

VARIABLES

Wish sets the following Tcl variables:

argcContains a count of the number of arg arguments (0 if none), not including the options described above.

argvContains a Tcl list whose elements are the arg arguments that follow a -- option or do not match any of theoptions described in OPTIONS above, in order, or an empty string if there are no such arguments.

argv0Contains fileName if it was specified. Otherwise, contains the name by which wish was invoked.

geometryIf the -geometry option is specified, wish copies its value into this variable. If the variable still exists afterfileName has been evaluated, wish uses the value of the variable in a wm geometry command to set the mainwindow's geometry.

tcl_interactiveContains 1 if wish is reading commands interactively (fileName was not specified and standard input is aterminal-like device), 0 otherwise.

SCRIPT FILES

If you create a Tcl script in a file whose first line is

#!/usr/local/bin/wish

Tcl/Tk Applications wish

7

then you can invoke the script file directly from your shell if you mark it as executable. This assumes that wish hasbeen installed in the default location in /usr/local/bin; if it is installed somewhere else then you will have to modify theabove line to match. Many UNIX systems do not allow the #! line to exceed about 30 characters in length, so be surethat the wish executable can be accessed with a short file name.

An even better approach is to start your script files with the following three lines:

#!/bin/sh# the next line restarts using wish \exec wish "$0" "$@"

This approach has three advantages over the approach in the previous paragraph. First, the location of the wish binarydoes not have to be hard-wired into the script: it can be anywhere in your shell search path. Second, it gets around the30-character file name limit in the previous approach. Third, this approach will work even if wish is itself a shellscript (this is done on some systems in order to handle multiple architectures or operating systems: the wish scriptselects one of several binaries to run). The three lines cause both sh and wish to process the script, but the exec is onlyexecuted by sh. sh processes the script first; it treats the second line as a comment and executes the third line. Theexec statement cause the shell to stop processing and instead to start up wish to reprocess the entire script. When wishstarts up, it treats all three lines as comments, since the backslash at the end of the second line causes the third line tobe treated as part of the comment on the second line.

The end of a script file may be marked either by the physical end of the medium, or by the character, \032(\u001a, control-Z). If this character is present in the file, the wish application will read text up to but not includingthe character. An application that requires this character in the file may encode it as \032, \x1a, or \u001a; ormay generate it by use of commands such as format or binary.

PROMPTS

When wish is invoked interactively it normally prompts for each command with % . You can change the prompt bysetting the variables tcl_prompt1 and tcl_prompt2. If variable tcl_prompt1 exists then it must consist of a Tcl scriptto output a prompt; instead of outputting a prompt wish will evaluate the script in tcl_prompt1. The variabletcl_prompt2 is used in a similar way when a newline is typed but the current command is not yet complete; iftcl_prompt2 is not set then no prompt is output for incomplete commands.

KEYWORDS

shell, toolkit

Copyright 1995-1997 Roger E. Critchlow Jr. Copyright 1991-1994 The Regents of the University of California.Copyright 1994-1996 Sun Microsystems, Inc.

Tcl/Tk Applications wish

8

Tcl CommandsTcl8.5.5/Tk8.5.5 Documentation > Tcl Commands

Tcl/Tk Applications | Tcl Commands | Tk Commands | Tcl Library | Tk Library

after error lappend platform tcl_findLibrary

append eval lassign platform::shell tcl_startOfNextWord

apply exec lindex proc tcl_startOfPreviousWord

array exit linsert puts tcl_wordBreakAfter

auto_execok expr list pwd tcl_wordBreakBefore

auto_import fblocked llength re_syntax tcltest

auto_load fconfigure load read tclvars

auto_mkindex fcopy lrange refchan tell

auto_mkindex_old file lrepeat regexp time

auto_qualify fileevent lreplace registry tm

auto_reset filename lreverse regsub trace

bgerror flush lsearch rename unknown

binary for lset return unload

break foreach lsort Safe Base unset

catch format mathfunc scan update

cd gets mathop seek uplevel

chan glob memory set upvar

clock global msgcat socket variable

close history namespace source vwait

concat http open split while

continue if package string

dde incr parray subst

dict info pid switch

encoding interp pkg::create Tcl

eof join pkg_mkIndex tcl_endOfWordCopyright 1990-1994 The Regents of the University of California Copyright 1992-1999 Karl Lehenbauer &Mark Diekhans Copyright 1992-1999 Karl Lehenbauer and Mark Diekhans Copyright 1993-1997 Bell LabsInnovations for Lucent Technologies Copyright 1994-2000 Sun Microsystems, Inc Copyright 1995-1997 RogerE. Critchlow Jr Copyright 1998 Mark Harrison Copyright 1998-2000 Ajuba Solutions Copyright 1998-2000Scriptics Corporation Copyright 2001-2004 ActiveState Corporation Copyright 2001-2005 Kevin B. Kenny Copyright 2001-2006 Donal K. Fellows Copyright 2003 George Petasis Copyright 2003 Simon Geard Copyright 2004-2008 Andreas Kupries Copyright 2006 ActiveState Software Inc Copyright 2006 Miguel

9

Sofer

Tcl Commands Tcl8.5.5/Tk8.5.5 Documentation > Tcl Commands

10

Tcl

Tcl8.5.5/Tk8.5.5 Documentation > TclCmd > Tcl

Tcl/Tk Applications | Tcl Commands | Tk Commands | Tcl Library | Tk Library

NAME

Tcl - Tool Command LanguageSYNOPSISDESCRIPTION

[1] Commands.[2] Evaluation.[3] Words.[4] Double quotes.[5] Argument expansion.[6] Braces.[7] Command substitution.[8] Variable substitution.

$name$name(index)${name}

[9] Backslash substitution.\a\b\f\n\r\t\v\whiteSpace\\\ooo\xhh\uhhhh

[10] Comments.[11] Order of substitution.[12] Substitution and word boundaries.

NAME

Tcl - Tool Command Language

Tcl Commands Tcl

11

SYNOPSIS

Summary of Tcl language syntax.

DESCRIPTION

The following rules define the syntax and semantics of the Tcl language:

[1] Commands.A Tcl script is a string containing one or more commands. Semi-colons and newlines are command separatorsunless quoted as described below. Close brackets are command terminators during command substitution (seebelow) unless quoted.

[2] Evaluation.A command is evaluated in two steps. First, the Tcl interpreter breaks the command into words and performssubstitutions as described below. These substitutions are performed in the same way for all commands. Thefirst word is used to locate a command procedure to carry out the command, then all of the words of thecommand are passed to the command procedure. The command procedure is free to interpret each of its wordsin any way it likes, such as an integer, variable name, list, or Tcl script. Different commands interpret theirwords differently.

[3] Words.Words of a command are separated by white space (except for newlines, which are command separators).

[4] Double quotes.If the first character of a word is double-quote (") then the word is terminated by the next double-quotecharacter. If semi-colons, close brackets, or white space characters (including newlines) appear between thequotes then they are treated as ordinary characters and included in the word. Command substitution, variablesubstitution, and backslash substitution are performed on the characters between the quotes as describedbelow. The double-quotes are not retained as part of the word.

[5] Argument expansion.If a word starts with the string {*} followed by a non-whitespace character, then the leading {*} isremoved and the rest of the word is parsed and substituted as any other word. After substitution, the word isparsed again without substitutions, and its words are added to the command being substituted. For instance,cmd a {*}{b c} d {*}{e f} is equivalent to cmd a b c d e f.

[6] Braces.If the first character of a word is an open brace ({) and rule [5] does not apply, then the word is terminatedby the matching close brace (}). Braces nest within the word: for each additional open brace there must bean additional close brace (however, if an open brace or close brace with