Perl / Tk Reference Guide - Netzmafia

whooploafSoftware and s/w Development

Dec 13, 2013 (3 years and 7 months ago)

95 views

Perl/TkReferenceGuide
Notes
Perl/TkReferenceGuideRevision402.003.0
c

1989,1997
44
Perl/TkReferenceGuide
forPerl/Tk402.003-Perl5.004/Tk402.003
Perlprogramdesignedandcreatedby
LarryWall
<larry@wall.org>
Tkdesignedandcreatedby
JohnOusterhout
<John.Ousterhout@Eng.Sun.COM>
Perl/Tkdesignedandcreatedby
NickIng-Simmons
<nick@ni-s.u-net.com>
Referenceguideformatdesignedandcreatedby
JohanVromans
<jvromans@squirrel.nl>
Referenceguidecontentswrittenby
PaulRaines
<raines@slac.stanford.edu>
JeffTranter
<Jeff_Tranter@Mitel.COM>
SteveLidie
<Stephen.O.Lidie@Lehigh.EDU>
Contents
1.GeneralPerl/TkWidgetInformation
￿￿￿￿￿￿￿￿￿￿￿
2
2.Perl/TkSpecialVariables
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
5
3.WidgetScrollCommands
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
5
4.TheCanvasWidget
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
6
5.TheEntryWidget
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
11
6.TheListboxWidget
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
12
7.TheMenuWidget
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
13
8.TheTextWidget
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
15
9.OtherStandardWidgets
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
18
10.Perl/TkWidgets
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
23
11.Images
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
32
12.WindowInformation
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
34
13.TheWindowManager
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
36
14.GeometryManagement
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
38
15.Bindings
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
39
16.OtherPerl/TkCommands
￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿
40
Rev.402.003.0
Perl/TkReferenceGuide
Conventions
fixed
denotesliteraltext.
thismeansvariabletext,i.e.thingsyoumustfillin.
word
isakeyword,i.e.awordwithaspecialmeaning.
?...?denotesanoptionalpart.
1.GeneralPerl/TkWidgetInformation
AllPerl/Tkprogramsmusthavea
useTk
statement.TousespecialPerl/Tk
widgetslike
Dialog
a
useTk::Dialog
statementisrequired.
Allwidgetsarecreatedwith
$widget
=$
parent
->widgetClass(?-option1
=>
value1,...?);
wherewidgetClassisthenameoftheclassofwidgetdesired(eg.
Button)and
parentisaPerl/Tkwidgetreferenceofthenewwidget’sparent.ThePerlobject
referenceisstoredin
$widget,whichbecomesachildof
$parent,creatingthe
widgethierarchy.
AllwidgetcreationcommandscanhavetheoptionalName
=>
resourceName
parametertoassociatearesourcedatabasenamewiththewidget.
EveryPerl/Tkprogramrequiresamainwindow,thetopmostwidgetinthe
hierarchy,createdwith
$mw
=
MainWindow
->new
;
Thefollowingcommandcreatesanewbuttonwidget
$bandusesthe
grid
geometrymanagertomapit:
$b
=$
mw->Button(-text
=>
”HelloWorld”)
->grid;
Widgetconfigurationoptionsmaybepassedinthecreationmethod.Optionsbegin
witha“
-”andarealwaysfollowedbyavalue,usuallyanintegerorstring,
sometimesaPerlscalar,array,hashorcodereference.Aftercreation,optionsmay
bechangedusingthe
configure
widgetcommand
$widget
->configure(-option1
=>
value1,...);
andqueriedusingthe
cget
command
$widget
->cget
(-option);
ThelaststatementinaPerl/Tkprogramcalls
MainLoop
toinitiateevent
processing.
Perl/TkCallbacksAcallbackisascalar,eitheracodereferenceoramethodnameasastring.Either
ofthesestylescantakeparametersbypassinganarrayreference,withthefirst
elementthecodereferenceormethodname,andsubsequentelementssubroutine
parameters.
\&subroutine[\&subroutine?,args?]
sub
{...}
[sub
{
...}
?,args?]
’methodName’[’methodName’?,args?]
Notethat
bind
callbacksareimplicitlypassedtheboundwidgetreferenceasthe
firstargumentoftheparameterlist.RefertothesectionBindingsforrelated
information.
2
Perl/TkReferenceGuide
Notes
Perl/TkReferenceGuideRevision402.003.0
c

1989,1997
43
Perl/TkReferenceGuide
$widget
->selectionGet(?-selection
=>
selection??,-type
=>
type?);
Retrievesselectionfrom
$widget’sdisplayusingrepresentationtype.
$widget->selectionHandle(?-selection
=>
sel??,-type
=>
type??,-format
=>
fmt?,win
=>
callback);
Arrangesforcallbacktoberunwheneverseloftypeisownedbywin.
$widget
->selectionOwner(?-selection
=>
selection?);
Returnspathnameof
$widgetwhichownsselectionon
$widget’sdisplay.
$widget->selectionOwn(?-selection
=>
selection??,-command
=>
callback?);
Causes
$widgettobecomenewownerofselectionandarrangesfor
commandtoberunwhen
$widgetlaterlosestheselection.
$widget
->send(?-async?interp
=>
callback);
ExecutecallbackintheTkapplicationinterpon
$widget’sdisplay.If
-async
isspecified,the
$widget->send
commandwillreturn
immediately.
ToreceivecommandsfromaforeignapplicationdefineasubroutineTk::Receive($widget,commandString).Runwithtaintchecksonand
untaintthereceiveddata.
$widget
->setPalette
(color);
Setthedefaultbackgroundcolorandcomputeotherdefaultcolors.
$widget
->setPalette
(name
=>
color?,name
=>
color...?);
Setthedefaultcolorforthenamedcoloroptionsexplicitly.
$widget
->waitVariable
(varRef);
PauseprogramuntilglobalvariablevarRefismodified.
$widget
->waitVisibility;
Pauseprogramuntil
$widget’svisibilityhaschanged.
$widget
->waitWindow
;
Pauseprogramuntil
$widgetisdestroyed.
42
Perl/TkReferenceGuide
CommonWidgetOptionsSomeofthewidgetoptionscommontoseveralwidgetsaredescribedherefor
brevity.-activebackground=>
color
Backgroundcolorofwidgetwhenitisactive.
-activeborderwidth=>
width
Widthinscreenunitsofwidgetborderwhenitisactive.
-activeforeground=>
color
Foregroundcolorofwidgetwhenitisactive.
-anchor=>
anchorPos
Howinformationispositionedinsidewidget.ValidanchorPosvaluesare
n,
ne,e,se,s,sw,w,nw,
and
center.
-background=>
color
Backgroundcolorofwidgetinnormalstate(Abbrev:
-bg).
-bitmap=>
bitmap
Bitmaptodisplayinthewidget(error,gray12,gray50,
gray25,hourglass,info,questhead,question,
warning,@pathName).
-borderwidth=>
width
Widthinscreenunitsofwidgetborderinnormalstate(Abbrev:
-bd).
-class=>
className
AssignanewclassNametoawidget.
-command=>
callback
APerl/TkcallbackdescribingthePerlcodetorunwhenwidgetisinvoked.
-cursor=>
[bitmap,mask,foreground,background]
Anarrayreferencedescribingthecursortodisplaywhenmousepointerisin
widget.
-disabledforeground=>
color
Foregroundcolorofwidgetwhenitisdisabled.
-exportselection=>
boolean
WhetherornotaselectioninthewidgetshouldalsobetheXselection.
-font=>
font
Fonttousewhendrawingtextinsidethewidget.
-foreground=>
color
Foregroundcolorofwidgetinnormalstate(Abbrev:
-fg).
-geometry=>
widthxheight
Geometryforthewidget’swindow.Theunitsforwidthandheightdepend
ontheparticularwidget(usuallyincharacterswhenwidgethastext).
-height=>
height|textChars
Heightofwidget.Unitsdependonwidget.
-highlightbackground=>
color
Coloroftherectangledrawnaroundthewidgetwhenitdoesnothavethe
inputfocus.
-highlightcolor=>
color
Coloroftherectangledrawnaroundthewidgetwhenithastheinputfocus.
-highlightthickness=>
width
Widthinscreenunitsofhighlightrectangledrawnaroundwidgetwhenit
hastheinputfocus.
3
Perl/TkReferenceGuide
-image=>
image
Imagetodisplayinthewidget(seeImages).
-insertbackground=>
color
Colortouseasbackgroundintheareacoveredbytheinsertioncursor.
-insertborderwidth=>
width
Widthinscreenunitsofbordertodrawaroundtheinsertioncursor.
-insertofftime=>
milliseconds
Timetheinsertioncursorshouldremain“off”ineachblinkcycle.
-insertontime=>
milliseconds
Timetheinsertioncursorshouldremain“on”ineachblinkcycle.
-insertwidth=>
width
Widthinscreenunitsoftheinsertioncursor.
-jump=>
boolean
Whethertonotifyscrollbarsandscalesconnectedtothewidgettodelay
updatesuntilmousebuttonisreleased.
-justify=>left|center|right
Howmultiplelineslineupwitheachother.
-menuitems=>
[[type,label?,-option
=>
value?]]
Alistoflistofmenuitemtypes,like
Button,withthetextlabelandoptional
parameters.menuitemscanbenested.
-orient=>horizontal|vertical
Whichorientationwidgetshoulduseinlayout.
-padx=>
width
ExtraexternalspaceinscreenunitstorequestforthewidgetinX-direction.
Use-ipadxtherequestadditionalinternalhorizontalspace.
-pady=>
height
ExtraexternalspaceinscreenunitstorequestforthewidgetinY-direction.
Use-ipadytorequestadditionalinternalverticalspace.
-relief=>flat|groove|raised|ridge|sunken
3-Deffectdesiredforthewidget’sborder.
-repeatdelay=>
milliseconds
Timeabuttonorkeymustbehelddownbeforeitbeginstoauto-repeat.
-repeatinterval=>
milliseconds
Timebetweenauto-repeatsonceactionhasbegun.
-selectbackground=>
color
Backgroundcolortousewhendisplayingselecteditems.
-selectborderwidth=>
width
Widthinscreenunitsofbordertodrawaroundselecteditems.
-selectforeground=>
color
Foregroundcolortousewhendisplayingselecteditems.
-setgrid=>
boolean
Whetherthiswidgetcontrolstheresizinggridforitstoplevelwindow.
-size=>
size
Asizeinscreenunits.Valuesareinpixelsunlessanoptionaloneletter
suffixmodifierispresent—
c
(cm),
i
(inch),
m
(mm),or
p
(points).
-state=>normal|disabled
(|active
forbutton-typewidgets)
Currentstateofwidget.
-takefocus=>
focusType
If
0
or
1,signalsthatthewidgetshouldneveroralwaystakethefocus.If
4
Perl/TkReferenceGuide
$widget
->clipboardClear
;
Claimownershipofclipboardon
$widget’sdisplay,clearingitscontents.
$widget
->destroy
;
Destroythegivenwindowanditsdescendents.
Exists($widget);
Returns1ifthereexistsawindowfor
$widget,”(false)ifnosuchwindow
exists.
$widget
->focus
;
Setfocuswindowto
$widget.
$widget
->focusCurrent
;
Returnsfocuswindowon
$widget’sdisplay.
$widget
->focusFollowsMouse
;
Changefocusmodelofapplicationsofocusfollowsthemousepointer.
$widget
->focusForce
;
Setstheinputfocusfor
$widget’sdisplayto
$widgetevenifanother
applicationhasit.
$widget
->focusLast
;
Returnsthewindowwhichmostrecentlyhadfocusandisadescendentof$widget’stoplevel.
$widget
->focusNext
;
Returnsthenextwindowafter
$widgetinfocusorder.
$widget
->focusPrev
;
Returnsthepreviouswindowbefore
$widgetinfocusorder.
$widget
->grabCurrent;
Returnsnameofcurrentgrabwindowon
$widget’sdisplay.If
$widgetis
omitted,returnslistofallwindowsgrabbedbytheapplication.
$widget
->grabRelease;
Releasesgrabon
$widget.
$widget
->grab;
Setsalocalgrabon
$widget.
$widget
->grabGlobal;
Setsaglobalgrab.
$widget
->grabStatus;
Returns
none,
local,or
global
todescribegrabstateof
$widget.
$widget
->lower
(?belowThis?);
Places
$widgetbelowwindowbelowThisinstackingorder.
$widget
->optionAdd
(pattern
=>
value?,priority?);
Addsoptionwithpatternvalueatpriority(0-100)todatabase.
$widget
->optionClear
Clearsoptiondatabaseandreloadsfromuser’sXdefaults.
$widget
->optionGet(name,class);
Obtainsoptionvaluefor
$widgetundernameandclassifpresent.
$widget
->optionReadfile(pathName?,priority?);
ReadsoptionsfromXdefaults-stylefileintooptiondatabaseatpriority.
$widget
->Popup
(menu,x,y?,entry?);
Postpopupmenusothatentryispositionedatrootcoordsxy.
$widget
->raise(?aboveThis?);
Places
$widgetabovewindowaboveThisinstackingorder.
$widget
->selectionClear(?-selection
=>
selection?);
Clearsselection(defaultPRIMARY)on
$widget’sdisplay.
41
Perl/TkReferenceGuide
ConfigureKeyPress,KeyUnmap
DestroyKeyReleaseVisibility
EnterMotion
Details:forbuttons,anumber1-5
forkeys,akeysym(/usr/include/X11/keysymdef.h)
Tags:widgetinstance(appliestojustthatwindow)
toplevelwindow(appliestoallitsinternalwindows)
classname(appliestoallwidgetsinclass)’all’
(appliestoallwindows)
Codes:passtoXEventstructure(seebelow)
%
single
%
signwwidthfield
#lastevent’sserialfieldxxfield
aabovefieldyyfield
bbuttonnumberAASCIIcharacter
ccountfieldBborder
_widthfield
ddetailfieldEsend_eventfield
ffocusfieldKkeysymastext
hheightfieldNkeysymasdecimal
kkeycodefieldRrootwindow
mmodefieldSsub_windowidentifier
ooverride
_
redirectfieldTtypefield
pplacefieldWwindowpathname
sstatefieldXx_rootfield
ttimefieldYy_rootfield
$widget
->break;
Exitcallbackandshortcircuit
bindtags
search.
$eventStructure=
$widget->XEvent;
FetchtheX11eventstructure,theninvokethe
$
eventStructuremethodand
passoneofthepreceedingCodestofetchthecorrespondingX-Eventfield
informationfor
$widget.
$eventStructure=
$Tk::event
;
AbindingcanlocalizetheX11eventstructurewith
$Tk::event
ratherthan
calling
XEvent.
$eventField=
Ev(Code);
Bindingcallbackscanbenestedusingthe
Ev(...)
”constructor”.
Ev(...)
insertscallbackobjectsintotheargumentlist.WhenPerl/Tkpreparesthe
argumentlistforthecallbackitisabouttocallitspotsthesespecialobjects
andrecursivelyappliesthecallbackprocesstothem.
16.OtherPerl/TkCommands
$widget
->appname(?newName?);
SettheinterpreternameoftheapplicationtonewName.
$widget
->bell;
RingtheXbellon
$widget’sdisplay.
$widget
->bisque;
Setdefaultcolorpalettetooldbisquescheme.
$widget
->clipboardAppend
(?-format
=>
fmt??,-type
=>
type?,data);
Appenddatatoclipboardonwidget’sdisplay.
40
Perl/TkReferenceGuide
empty,Tkdecides.Otherwise,evalutesargumentasscriptwithwidgetname
appendedasargument.Returnedvaluemustbe
0,
1
orempty.
-text=>
string
Texttobedisplayedinsidethewidget.
-textvariable=>
varRef
AreferencetoaPerlscalarvariablewhichcontainsatextstringtobe
displayedinsidethewidget,orwhichismodifiedbythewidget.
-troughcolor=>
color
Colortousefortherectangulartroughareasinwidget.
-underline=>
index
Integerindexofacharactertounderlineinthewidget.
-width=>
width|textChars
Widthofwidget.Unitsdependonwidget.
-wraplength=>
length
Maximumlinelengthinscreenunitsforword-wrapping.
-xscrollcommand=>
cmdPrefix
Prefixforacommandusedtocommunicatewithhorizontalscrollbars.
-yscrollcommand=>
cmdPrefix
Prefixforacommandusedtocommunicatewithverticalscrollbars.
2.Perl/TkSpecialVariables
$Tk::library
DirectorycontaininglibraryofTkmodules,widgetsandscripts.
$Tk::patchLevel
IntegerspecifyingcurrentpatchlevelforTcl/Tk.
$Tk::strictMotif
Whennon-zero,TktriestoadheretoMotiflook-and-feelascloselyas
possible.
$Tk::version
CurrentversionofTcl/TkthatPerl/Tkisbasedon,inmajor.minorform.
$Tk::VERSION
CurrentversionofPerl/Tk.
3.WidgetScrollCommands
TheCanvas,ListboxandTextwidgetssupportthefollowingscrollingcommands.
TheEntrywidgetsupportsthe
xview
commandandthe
scan
commandwiththey
coordinatedropped.
RefertothesectionPerl/TkWidgetsandlearnhowPerl/Tkgreatlysimplifies
managingscrollbars.$widget
->scanMark(x,y);
Recordsxandyaswidget’scurrentviewanchor.
$widget
->scanDragto
(x,y);
Shifttheviewby10timesthedifferencebetweenthecoordinatesxandy
andthecurrentviewanchorcoordinates.
$widget
->xview
;
Returnatwoelementlistspecifyingthefractionofthehorizontalspanofthe
widgetattheleftandrightedgesofthewindow.
5
Perl/TkReferenceGuide
$widget
->xviewMoveto
(fraction);
Adjusttheviewinthewindowsothatfractionofthetotalwidthofthe
widgetisoff-screentotheleft.
$widget
->xviewScroll
(number
=>units|pages
);
Shifttheviewbynumberone-tenth’s(
unit)ornine-tenth’s(
pages)the
window’swidthinthehorizontaldirection.
$widget
->yview
;
Returnatwoelementlistspecifyingthefractionoftheverticalspanofthe
widgetatthetopandbottomedgesofthewindow.
$widget
->yviewMoveto
(fraction);
Adjusttheviewinthewindowsothatfractionofthetotalheightofthe
widgetisoff-screentothetop.
$widget
->yviewScroll
(number
=>units|pages
);
Shifttheviewbynumberone-tenth’s(
unit)ornine-tenth’s(
pages)the
window’sheightintheverticaldirection.
TheTextWidgetalsosupportsthefollowing:$text
->yview
(?-pickplace,?index);
Changesviewofwidget’swindowtomakecharacteratindexvisible.If
-pickplace
isspecified,indexwillappearatthetopofthewindow.
TheEntry(
xview
only)andListboxwidgetalsosupportsthefollowing:
$listbox->xview
(index);
Adjustsviewsothatcharacterpositionindexisatleftedge.
$listbox->yview
(index);
Adjustsviewsothatelementatindexisattopofwindow.
4.TheCanvasWidget
CanvasOptions-background-insertbackground-selectborderwidth
-borderwidth-insertborderwidth-selectforeground
-cursor-insertofftime-takefocus
-height-insertontime-width
-highlightbackground-insertwidth-xscrollcommand
-highlightcolor-relief-yscrollcommand
-highlightthickness-selectbackground
-closeenough=>
float
Howclosethemousecursormustbetoanitembeforeitisconsideredtobe
“inside”theitem.
-confine=>
boolean
Whetheritisallowabletosetthecanvas’sviewoutsidethescrollregion.
-scrollregion=>
[corners]
Listreferenceoffourcoordinatesdescribingtheleft,top,right,andbottom
ofarectangularscrollingregion.
-xscrollincrement=>
distance
Specifiestheincrementforhorizontalscrollinginscreenunits.
-yscrollincrement=>
distance
Specifiestheincrementforverticalscrollinginscreenunits.
6
Perl/TkReferenceGuide
$slave->gridForget
;
Removes(andunmaps)
$slavefromgridofitsmaster.
$slave->gridInfo
;
Returnslistdescribingconfigurationstateof
$slave.
$master->gridLocation(x,y);
Returnscolumnandrowcontainingscreenunitsxyin
$master.Ifx,yis
outsidegrid,-1isreturned.
$master->gridPropagate
(?boolean?);
Set/getwhether
$mastertriestoresizeitsancestorwindowstofitgrid.
$master->gridRowconfigure
(row?,
-minsize=>
size??,
-weight=>
int?);
Set/getminimumrowsizeandrelativerowweight.
$master->gridSize
;
Returnssizeofgrid(incolumnsthenrows)for
$master.
$master->gridSlaves
(?-row
=>
row??,-column
=>
column?);
Withnooptions,alistofallslavesin
$masterisreturned.Otherwise,
returnsalistofslavesinspecifiedrowand/orcolumn.
15.Bindings
Notethat
bind
callbacksareimplicitlypassedtheboundwidgetreferenceasthe
firstargumentoftheparameterlist.$widget
->bind;
Returnslistofalleventdescriptorsforwhichabindingexistsfor
$widget.
$widget
->bind(tag);
Returnslistofalleventdescriptorsforwhichabindingexistsfortag.
$widget
->bind(<modifier-modifier-type-detail
>
);
Returnsthecallbackboundtothegiveneventdescriptorfor
$widget.
$widget
->bind(tag,
<modifier-modifier-type-detail
>
);
Returnsthecallbackboundtothegiveneventdescriptorfortag.
$widget
->bind(<modifier-modifier-type-detail
>=>
callback);
Bindscallbacktothegivensequencefor
$widget
$widget
->bind(tag,
<modifier-modifier-type-detail
>=>
callback);
Bindscallbacktothegivensequencefortag
$widget
=>bindtags
(?tagList?);
Setsthecurrentprecedenceorderoftagsfor
$widgettotagList.Bydefaulta
Perl/Tkwidget’staglistis(class,instance,toplevel,’all’).Notethatthis
orderingdiffersfromthatofTcl/Tk’s(instance,class,toplevel,’all’).
Modifiers:
AnyTripleButton5,B5Mod3,M3
ControlButton1,B1Meta,MMod4,M4
ShiftButton2,B2Mod1,M1Mod5,M5
LockButton3,B3Mod2,M2Alt
DoubleButton4,B4
Types:
ButtonPress,ButtonExposeLeave
ButtonReleaseFocusInMap
CirculateFocusOutProperty
ColormapGravityReparent
39
Perl/TkReferenceGuide
14.GeometryManagement
ThepackCommand$widget
->pack
(?-options?);
Detailshowslavewindow
$widgetshouldbemanaged.
-after
=>
sibling-in
=>
master-pady
=>
pixels
-anchor
=>
anchor-ipadx
=>
pixels-fill
=>none|x|y|both
-before
=>
sibling-ipady
=>
pixels-side
=>top|bottom|left|right
-expand
=>
boolean-padx
=>
pixels
$widget
->packForget
;
Unmanagesthegivenslave.
$widget
->packInfo
;
Returnslistcontainingcurrentpackconfiguration.
$master->packPropagate
(?boolean?);
Enablesordisablespropogationforthewindow
$master.
$master->packSlaves
;
Returnslistsofslavesinthewindow
$master.
TheplaceCommand$widget
->place(-option
=>
value?,-option
=>
value...?);
Detailshow
$widgetshouldbemanaged.
-anchor
=>
anchor-relheight
=>
size-x
=>
location
-height
=>
size-relwidth
=>
size-y
=>
location
-in
=>
master-relx
=>
location-bordermode
=>inside|outside|ignore
-width
=>
size-rely
=>
location
$widget
->placeForget
;
Unmanages
$widget.
$widget
->placeInfo
;
Returnslistcontainingcurrentplaceconfigurationof
$widget.
$master->placeSlaves
;
Returnslistsofslavesinthewindow
$master.
ThegridCommand$widget
->grid(?-option
=>
value...?);
-column
=>
n-ipady
=>
amount-row
=>
n
-columnspan
=>
n-padx
=>
amount-rowspan
=>
n
-in
=>
other-pady
=>
amount-sticky
=>
?n|s|e|w|ns|ew
?
-ipadx
=>
amount
$master->gridBbox
(column,row);
Returnsanapproximateboundingboxinpixelsofspaceoccupiedby
column,row.
$master->gridColumnconfigure(column?,
-minsize=>
size??,
-weight
=>
int?);
Set/getminimumcolumnsizeandrelativecolumnweight.
38
Perl/TkReferenceGuide
Coordinateexamples:5(pixel),2.2i(inch),4.1c(cm),3m(mm),21p(pts)
Largery-coordinatesrefertopointsloweronthescreen.
Largerx-coordinatesrefertopointsfarthertotheright.
Characterpositions:’charIndex’,
’end’,’insert’,’sel.first’,
’sel.last’,’
@x,y’
CanvasCommands$canvas
->addtag
(tag,searchSpec?,arg,arg...?);
AddtagtothelistoftagsassociatedwitheachitemthatsatisfysearchSpec.
SeeCanvasSearchSpecsbelow.
$canvas
->bbox
(tagOrId?,tagOrId...?);
Returnsalist(x1,y1,x2,y2)givinganapproximateboundingboxforall
theitemsnamedbythetagOrIdarguments.
$canvas
->bind(tagOrId?,sequence
=>
callback?);
Associatescallbacktobeinvokedoneventsspecifiedwithsequencewith
theitemsgivenbytagOrId.
$canvas
->canvasx
(screenx?,gridspacing?);
Returnsthecanvasx-coordinatethatisdisplayedatscreenx-coordinate
screenxpossiblyroundingtonearestmultipleofgridspacingunits.
$canvas
->canvasy
(screeny?,gridspacing?);
Returnsthecanvasx-coordinatethatisdisplayedatscreeny-coordinate
screenypossiblyroundingtonearestmultipleofgridspacingunits.
$canvas
->coords
(tagOrId?,x0,y0...?);
Queryormodifythecoordinatesthatdefineanitem.
$canvas
->createType(x,y?,x,y...??,-option=>value...?);
CreateanewitemoftypeTypeatspecifiedcoordinatesandwithlistoptions.
CurrentlyTypemaybe:
ArcBitmapImageLineOvalPolygonRectangle
TextWindow
.
$canvas
->dchars
(tagOrId,first?,last?);
ForitemsgivenbytagOrId,deletethecharactersintherangegivenbyfirst
andlast(defaultstofirst),inclusive.
$canvas
->delete(?tagOrId...?);
DeleteeachoftheitemsgivenbyeachtagOrId.
$canvas
->dtag
(tagOrId?,tagToDelete?);
RemovetagtagToDeletefromthetaglistofitemsgivenbytagOrId.
$canvas
->find(searchSpec?,arg,arg...?);
ReturnsalistoftheitemsthatsatisfythespecificationsearchSpec.See
CanvasSearchSpecsbelow.
$canvas
->focus
(tagOrId);
SetthefocustothefirsttextualitemgivenbytagOrId.
$canvas
->gettags
(tagOrId);
ReturnalistofthetagsassociatedwiththefirstitemgivenbytagOrId.
$canvas
->icursor
(tagOrId,index);
Settheinsertioncursorfortheitem(s)givenbytagOrIdtojustbefore
thecharacterpositionindex.
$canvas
->index
(tagOrId,index);
ReturnsadecimalstringgivingthenumericalindexwithintagOrId
correspondingtocharacterpositionindex.
7
Perl/TkReferenceGuide
$canvas
->insert
(tagOrId,beforeThis,string);
InsertstringjustbeforecharacterpositionbeforeThisinitemsgivenby
tagOrIdthatsupporttextualinsertion.
$canvas
->itemcget
(tagOrId,-option);
Returnsthevalue-optionfortheitemgivenbytagOrId.
$canvas
->itemconfigure(tagOrId?,-option
=>
value...?
Modifiesitem-specificoptionsfortheitemsgivenbytagOrId.
$canvas
->lower
(tagOrId?,belowThis?);
MovetheitemsgivenbytagOrIdtoanewpositioninthedisplaylistjust
beforethefirstitemgivenbybelowThis.
$canvas
->move
(tagOrId,xAmount,yAmount);
MovetheitemsgivenbytagOrIdinthecanvascoordinatespacebyadding
xAmountandyAmounttoeachitemsxandycoordinates,respectively.
$canvas
->postscript(?-option
=>
value...?);
GenerateanEncapsulatedPostscriptrepresentationforpartorallofthe
canvas.SeeCanvasPostscriptOptionsbelow.
$canvas
->raise(tagOrId?,aboveThis?);
MovetheitemsgivenbytagOrIdtoanewpositioninthedisplaylistjust
afterthefirstitemgivenbyaboveThis.
$canvas
->scale(tagOrId,xOrigin,yOrigin,xScale,yScale);
RescaleitemsgivenbytagOrIdincanvascoordinatespacetochangethe
distancefromxOrigin,yOriginbyafactorofxScale,yScalerespectively.
$canvas
->scan(args);
SeeWidgetScrollCommandsabove.
$canvas
->selectAdjust(tagOrId,index);
AdjustnearestendofcurrentselectionintagOrIdtobeatindexandsetthe
otherendtobethenewselectionanchor.
$canvas
->selectClear;
Cleartheselectionifitisinthewidget.
$canvas
->selectFrom
(tagOrId,index);
SettheselectionanchorintagOrIdtojustbeforethecharacteratindex.
$canvas
->selectItem;
Returnidoftheselecteditem.Returnsaemptystringifthereisnone.
$canvas
->selectTo
(tagOrId,index);
SettheselectiontoextendbetweenindexandanchorpointintagOrId.
$canvas
->type(tagOrId);
ReturnsthetypeofthefirstitemgivenbytagOrId.
$canvas
->xview
|
yview
(args);
SeeWidgetScrollCommandsabove.
CanvasSearchSpecificationsabove
=>
tagOrId
SelectstheitemjustaftertheonegivenbytagOrIdinthedisplaylist.
all
Selectsalltheitemsinthecanvas.
below
=>
tagOrId
SelectstheitemjustbeforetheonegivenbytagOrIdinthedisplaylist.
closest
=>
x,y?,halo??,start?
Selectthetopmost,closestitemto@x,ythatisbelowstartinthedisplaylist.
Anyitemcloserthanhalotothepointisconsideredtooverlapit.
8
Perl/TkReferenceGuide
$mw->frame;
ReturnstheXwindowidentifierfortheoutermostdecorativeframe
containing
$mw.If
$mwhasnone,returnsXidof
$mwitself.
$mw->geometry
(?newGeometry?);
Changesgeometryof
$mwtonewGeometry.
$mw->grid(?baseWidth,baseHeight,widthInc,heightInc?);
Indicatesthat
$mwistobemanagedasagriddedwindowwiththespecified
relationbetweengridandpixelunits.
$mw->group
(?pathName?);
Givespathnameforleaderofgrouptowhich
$mwbelongs.
$mw->iconbitmap(?bitmap?);
Specifiesabitmaptouseasiconimagewhen
$mwisiconified.
$mw->iconify;
Arrangefor
$mwtobeiconfied.
$mw->iconmask(?bitmap?);
Specifiesabitmaptousetomaskiconimagewhen
$mwisiconified.
$mw->iconname(?newName?);
Specifiesnametouseasalabelfor
$mw’sicon.
$mw->iconposition(?x,y?);
Specifiespositiononrootwindowtoplace
$mw’sicon.
$mw->iconwindow
(?pathName?);
Setspathnameofwindowtouseastheiconwhen
$mwisiconified.
$mw->maxsize
(?width,height?);
Specifiesmaximumsize
$mwmayberesizedtoineachdirection.
$mw->minsize
(?width,height?);
Specifiesminimumsize
$mwmayberesizedtoineachdirection.
$mw->overrideredirect
(?boolean?);
Setorunsettheoverride-redirectflagof
$mwcommonlyusedbywindow
managertodeterminewhetherwindowshoulddecorativeframe.
$mw->positionfrom
(?’program’|’user’
?);
Indicatefromwhomthe
$mw’scurrentpositionwasrequested.
$mw->protocol
(?name??,callback?);
SpecifyaPerlcallbacktobeinvokedformessagesofprotocolname.
$mw->resizable
(?widthBoolean,heightBoolean?);
Specifieswhether
$mw’swidthand/orheightisresizable.
$mw->sizefrom
(?program|user
?);
Indicatefromwhomthe
$mw’scurrentsizewasrequested.
$mw->state;
Returnscurrentstateof
$mw:
normal,
iconic,or
withdrawn.
$mw->title(?string?);
Settitlefor
$mw’sdecorativeframetostring.
$mw->transient(?master?);
Informswindowmanagerthat
$mwisatransientofthewindowmaster.
$mw->withdraw
;
Arrangesfor
$mwtobewithdrawnfromthescreen.
37
Perl/TkReferenceGuide
$widget
->screenvisual
;
Returnsthevisualclassof
$widget’sscreen.Maybeoneof:’directcolor’,
’grayscale’,’pseudocolor’,’staticcolor’,’staticgray’,or’truecolor’.
$widget
->screenwidth;
Returnsthewidthinpixelsof
$
widget’sscreen.
$widget
->toplevel
;
Returnsthepathnameofthetoplevelwindowcontaining
$widget.
$widget
->visual;
Returnsthevisualclassof
$widget(see
$widget
->screenvisual
).
$widget
->visualsavailable
;
Returnsalistwhoseelementsdescribethevisualsavailablefor
$widget’s
screenincludingclassanddepth..
$widget
->vrootheight
;
Returnstheheightofthevirtualrootwindowassociatedwith
$widget.
$widget
->vrootwidth
;
Returnsthewidthofthevirtualrootwindowassociatedwith
$widget.
$widget
->vrootx
;
Returnsthex-offsetofthevirtualrootwindowassociatedwith
$widget.
$widget
->vrooty
;
Returnsthey-offsetofthevirtualrootwindowassociatedwith
$widget.
$widget
->width;
Returns
$widget’swidthinpixels.
$widget
->x;
Returnsx-coordinate,in
$widget’sparent,oftheupper-leftcornerof
$widget.
$widget
->y;
Returnsy-coordinate,in
$widget’sparent,oftheupper-leftcornerof
$widget.
13.TheWindowManager
Manyofthefollowingmethodshaveoneormoreoptionalargumentswhich,when
specified,setsomething,butwhenmissing,getsomething.Thewidgetistypically
aMainWindoworaToplevel.$mw->aspect(?minNumer,minDenom,maxNumer,maxDenom?);
Informwindowmanagerofdesiredaspectratiorangefor
$mw.
$mw->client
(?name?);
Storenamein
$mw’sWM_CLIENT_MACHINEproperty.Informs
windowmanagerofclientmachineonwhichtheapplicationisrunning.
$mw->colormapwindows
(?windowList?);
StorewindowListin
$mw’sWM_COLORMAP_
WINDOWSproperty
whichidentifiestheinternalwindowswithin
$mwwithprivatecolormaps.
$mw->command(?value?);
Storevaluein
$mw’sWM_COMMANDproperty.Informswindow
managerofcommandusedtoinvoketheapplication.
$mw->deiconify;
Arrangefor
$mwtobemappedonthescreen.
$mw->focusmodel
(?’active’|’passive’
?);
Specifiesthefocusmodelfor
$mw.
36
Perl/TkReferenceGuide
enclosed
=>
x1,y1,x2,y2
Selectsalltheitemscompletelyenclosedwithinx1,y1,x2,y2.
overlapping
=>
x1,y1,x2,y2
Selectsalltheitemsthatoverlaporareenclosedwithinx1,y1,x2,y2.
withtag
=>
tagOrId
SelectsalltheitemsgivenbytagOrId.
CanvasItemTypes$canvas
->createArc
(x1,y1,x2,y2?,-option=
>
value...?);
-fill=>
color
-stipple=>
bitmap
-width=>
outlineWidth
-outline=>
color
-tags=>
tagList
-extent=>
degrees
Sizeoftheangularrangeoccupiedbyarc.
-outlinestipple=>
bitmap
Bitmapstippletousetodrawarc’soutline.
-start=>
degrees
Startinganglemeasuredfrom3-o’clockposition.
-style=>pieslice|chord|arc
Howto“complete”theregionofthearc.
$canvas
->createBitmap(x,y?,-option=
>
value...?);
-anchor=>
anchorPos
-bitmap=>
bitmap
-tags=>
tagList
-background
color
-foreground
color
$canvas
->createImage
(x,y?,-option=
>
value...?);
-anchor=>
anchorPos
-image=>
image
-tags=>
tagList?
$canvas
->createLine(x1,y1,...xN,yN?,-option=
>
value...?);
-fill=>
color
-stipple=>
bitmap
-width=>
outlineWidth
-smooth=>
boolean
-tags=>
tagList
-arrow=>none|first|last|both
Specifyonwhichendsofthelinetodrawarrows.
-arrowshape=>
shape
Threeelementlistwhichdescribesshapeofarrow.
-capstyle=>butt|projecting|round
Howtodrawcapsatendpointsoftheline.Defaultis
butt.
-joinstyle=>bevel|miter|round
Howjointsaretobedrawnatvetices.Defaultis
miter.
-splinesteps=>
number
Degreeofsmoothnessdesiredforcurves.
$canvas
->createOval
(x1,y1,x2,y2?,-option=
>
value...?);
-fill=>
color
-stipple=>
bitmap
-width=>
outlineWidth
-outline=>
color
-tags=>
tagList
$canvas
->createPolygon
(x1,y1,...xN,yN?,-option=
>
value...?);
-fill=>
color
-smooth=>
boolean
-tags=>
tagList
-outline=>
color
-stipple=>
bitmap
-width=>
outlineWidth
9
Perl/TkReferenceGuide
-splinesteps=>
number
Degreeofsmoothnessdesiredforcurvedperimeter.
$canvas
->createRectangle(x1,y1,x2,y2?,-option=
>
value...?);
-fill=>
color
-stipple=>
bitmap
-width=>
outlineWidth
-outline=>
color
-tags=>
tagList
$canvas
->createText
(x,y?,-option=
>
value...?);
-anchor=>
anchorPos
-font=>
font
-tags=>
tagList
-fill=>
color
-stipple=>
bitmap-text=>
string
-justify=>left|right|center
Howtojustifytextwithinitsboundingregion.
-width=>
lineLength
Maximumlinelengthforthetext.Ifzero,breakonlyon
n
n.
$canvas
->createWindow
(x,y?,-option=
>
value...?);
-anchor=>
anchorPos
-tags=>
tagList
-height=>
heightHeightinscreenunitstoassignitem’swindow.
-width=>
widthWidthinscreenutnistoassignitem’swindow.
-window=>
pathName
Windowtoassociatewithitem.
CanvasPostscriptOptions$canvas
->postscript(?-option
=>
value...?);
-colormap=>
varRef
SpecifiesacolormappingtousewherevarRefisanarrayvariablewhose
elementsspecifyPostscriptcodetosetaparticularcolorvalue.
-colormode=>color|grey|mono
Specifieshowtooutputcolorinformation.
-file=>
pathName
SpecifiesthenameofthefileinwhichtowritethePostscript.Ifnot
specified,thePostscriptisreturnedastheresultofthecommand.
-fontmap=>
varRef
SpecifiesafontmappingtousewherevarRefisanarrayvariablewhose
elementsspecifythePostscriptfontandsizetouseasatwoelementlist.
-height=>
size
Specifiestheheightoftheareaofthecanvastoprint.Defaultstotheheight
ofthecanvaswindow
-pageanchor=>
anchor
Specifieswhichpointoftheprintedareashouldbeappearoverthe
positioningpointonthepage.Defaultsto
center.
-pageheight=>
size
SpecifiesthatthePostscriptshouldbescaledinbothxandysothatthe
printedareaissizehighonthePostscriptpage.
-pagewidth=>
size
SpecifiesthatthePostscriptshouldbescaledinbothxandysothatthe
printedareaissizewideonthePostscriptpage.
-pagex=>
position
Setthex-coordinateofthepositioningpointonthepagetoposition.
10
Perl/TkReferenceGuide
$widget
->MainWindow
;
Returnsareferencetothedisplay’s
MainWindow
.
$widget
->manager
;
Returnsthenameofthegeometrymanagercurrentlyresponsiblefor$widget.
$widget
->name;
Returns
$widget’snamewithinitsparent,asopposedtoitsfullpathname.
$widget
->parent;
Returnsthepathnameof
$widget’sparent.
$widget
->pathname(id);
ReturnsthepathnameofthewindowwhoseXidentifierisidon
$widget’s
display.
$widget
->pixels
(number);
Returnsthenumberofpixelsin
$widgetcorrespondingtothedistancegiven
bynumber,roundedtothenearestinteger.
$widget
->pointerx;
Returnsmousepointer’sxcoordinateon
$widget’sscreen.
$widget
->pointerxy;
Returnsmousepointer’sxandycoordinateson
$widget’sscreen.
$widget
->pointery
;
Returnsmousepointer’sycoordinateon
$widget’sscreen.
$widget
->reqheight;
Returnsadecimalstringgiving
$
widget’srequestedheight,inpixels.
$widget
->reqwidth;
Returnsadecimalstringgiving
$
widget’srequestedwidth,inpixels.
$widget
->rgb
(color);
ReturnsalistofthethreeRGBvaluesthatcorrespondtocolorin
$widget.
$widget
->rootx
;
Returnsthex-coordinate,intherootwindowofthescreen,oftheupper-left
cornerof
$widget(includingitsborder).
$widget
->rooty
;
Returnsthey-coordinate,intherootwindowofthescreen,oftheupper-left
cornerof
$widget(includingitsborder).
$widget
->server
;
Returnsserverinformationon
$
widget’sdisplay.
$widget
->screen;
Returnsthenameofthescreenassociatedwith
$widget,intheform
displayName.screenIndex.
$widget
->screencells;
Returnsthenumberofcellsinthedefaultcolormapfor
$widget’sscreen.
$widget
->screendepth;
Returnsthedepth(bitsperpixel)of
$widget’sscreen.
$widget
->screenheight;
Returnstheheightinpixelsof
$widget’sscreen.
$widget
->screenmmheight;
Returnstheheightinmillimetersof
$widget’sscreen.
$widget
->screenmmwidth;
Returnsthewidthinmillimetersof
$widget’sscreen.
35
Perl/TkReferenceGuide
-from=>
x,1y1,x2,y2
Specifiesarectangularregionoftheimagefiletocopyfrom.
-shrink
Willclipimagesocopiedregionisinbottom-rightcorner.
-to=>
x,y
Specifiescoordsofthetop-leftcornerinimagetocopyinto.
$image
->redither;
Redithertheimage.
$image
->write(pathName?,-option
=>
value...?);
WritesimagedatafromimageintofilepathName.
-format=>
format-name
Specifiesimageformatforthefile.
-from=>
x1,y1,x2,y2
Specifiesarectangularregionoftheimagetocopyfrom.
12.WindowInformation
$widget
->allmapped;
Returns1if
$widgetandallitsancestorsaremapped,0otherwise.
$widget
->atom(name);
Returnsintegeridentifierforatomgivenbynameon
$widget’sdisplay.
$widget
->atomname(id);
Returnstextualnameofatomgivenbyintegeridon
$widget’sdisplay.
$widget
->cells;
Returnsnumberofcellsinthecolormapfor
$widget.
$widget
->children
;
Returnslistcontainingpathnamesofallthechildrenof
$widget.
$widget
->class
;
Returnstheclassnameof
$widget.
$widget
->colormapfull;
Return1ifthecolormapfor
$widgetisfull,0otherwise.
$widget
->containing(rootX,rootY);
ReturnspathnameofwindowcontainingthepointrootXrootYon
$widget’s
display.
$widget
->depth;
Returnsthedepth(bitsperpixel)of
$widget.
$widget
->fpixels
(number);
Returnsfloating-pointvaluegivingthenumberofpixeslin
$widget
correspondingtothedistancegivenbynumber.
$widget
->geometry
;
Returnsthepixelgeometryfor
$widget,intheformwidthxheight+x+y.
$widget
->height;
Returnsheightof
$widgetinpixels.
$widget
->id;
ReturnsahexadecimalstringindicatingtheXidentifierfor
$widget.
$widget
->interps;
ReturnsalistofallPerlinterpretersregisteredon
$widget’sdisplay.
$widget
->ismapped;
Returns1if
$widgetiscurrentlymapped,0otherwise.
34
Perl/TkReferenceGuide
-pagey=>
position
Setthey-coordinateofthepositioningpointonthepagetoposition.
-rotate=>
boolean
Whethertheprintedareaistoberotated90degrees.(“landscape”).
-width=>
size
Specifiesthewidthoftheareaofthecanvastoprint.Defaultstothewidthof
thecanvaswindow
-x=>
position
Setthex-coordinateoftheleftedgeofcanvasareatoprint.
-y=>
position
Setthey-coordinateofthetopedgeofcanvasareatoprint.
5.TheEntryWidget
EntryWidgetOptions-background-highlightcolor-relief
-borderwidth-highlightthickness-selectbackground
-cursor-insertbackground-selectborderwidth
-exportselection-insertborderwidth-selectforeground
-font-insertofftime-state
-foreground-insertontime-takefocus
-highlightbackground-insertwidth-textvariable
-justify-width
-show
boolean
Whethertoshowactualcharacteror“*”inentry.
EntryIndices:number(startsat0),
’anchor’,’end’,’insert’,
’sel.first’,’sel.last’
,’@x’
EntryWidgetCommands$entry->bbox
(index);
Returnsalist(x,y,width,height)givinganapproximateboundingboxof
charactergivenbyindex.
$entry->delete(first?,last?);
Deletecharactersfromfirstthroughcharacterjustbeforelast.
$entry->get
;
Returnsthe
$entry’sstring.
$entry->icursor
(index);
Displayinsertioncursorjustbeforecharacteratindex.
$entry->index
(index);
Returnsthenumericalindexcorrespondingtoindex.
$entry->insert
(index,string);
Insertstringjustbeforecharacteratindex.
$entry->scan(-option,args);
SeeWidgetScrollCommandsabove.
$entry->selectionAdjust(index);
Adjustnearestendofcurrentselectiontobeatindexandsettheotherendto
theanchorpoint.
11
Perl/TkReferenceGuide
$entry->selectionClear;
Cleartheselectionifcurrenlyinthewidget.
$entry->selectionFrom
(index);
Settheanchorpointtobeatindex.
$entry->selectionPresent;
Returns1isanycharactersareselected,0otherwise.
$entry->selectionRange
(start,end);
Selectthecharactersfromstartthroughcharacterjustbeforeend.
$entry->selectionTo
(index);
Settheselectiontoextendbetweenindexandanchorpoint.
6.TheListboxWidget
ListboxWidgetOptions-background-height-selectborderwidth
-borderwidth-highlightbackground-selectforeground
-cursor-highlightcolor-setGrid
-exportselection-highlightthickness-takefocus
-font-relief-width
-foreground-selectbackground-xscrollcommand
-yscrollcommand
-selectModesingle|browse|multiple|extendedListboxIndices:number(startsat0),
’active’,’anchor’,’end’
,
’@x,y’
ListboxWidgetCommands$listbox->activate
(index);
Setstheactiveelementtoindex.
$listbox->bbox
(index);
Returnsalist(x,y,width,height)givinganapproximateboundingboxof
charactergivenbyindex.
$listbox->curselection
;
Returnslistofindicesofallelementscurrentlyselected.
$listbox->delete(index1?,index2?);
Deleterangeofelementsfromindex1toindex2(defaultstoindex1).
$listbox->get
(index1?,index2?);
Returnasalistcontentsofelementsfromindex1toindex2.
$listbox->index
(index);
Returnspositionindexinnumbernotation.
$listbox->insert
(index?,element...?);
Insertspecifiedelementsjustbeforeelementatindex.
$listbox->nearest(y);
Returnindexofelementnearesttoy-coordinate.
$listbox->scan(args);
SeeWidgetScrollCommandsabove.
12
Perl/TkReferenceGuide
TheBitmapimagemethod-background=>
color
Setbackgroundcolorforbitmap.
-data=>
string
SpecifycontentsofbitmapinX11bitmapformat.
-file=>
pathName
GivesnameoffilewhosecontentsdefinethebitmapinX11bitmapformat.
-foreground=>
color
Setforegroundcolorforbitmap.
-maskdata=>
string
SpecifycontentsofmaskinX11bitmapformat.
-maskfile=>
pathName
GivesnameoffilewhosecontentsdefinethemaskinX11bitmapformat.
ThePhotoimagemethod-data=>
string
Specifycontentsofimageinasupportedformat.
-format=>
formatName
Specifyformatfordataspecifiedwiththe
-data
or
-file
options.
-file=>
pathName
Givesnameoffilewhosecontentsdefinetheimageinsupportedformat.
-height=>
number
Specifiespixelheightoftheimage.
-palette=>
paletteSpec
Settheresolutionofthecolorcubetobeallocatedforimage.
-width=>
number
Specifiespixelwidthoftheimage.
$image
->blank
;
Blankstheimagesoithasnodataandiscompletelytransparent.
$image
->copy
(sourceImage?,-option
=>
value...?);
CopyaregionfromsourceImageto
$imageusinggivenoptions.
-from=>
x1,y1,x2,y2
Specifiesrectangularregionofsourceimagetobecopied.
-to=>
x1,y1,x2,y2
Specifiesrectangularregionoftargetimagetobeaffected.
-shrink
Willcliptargetimagesocopiedregionisinbottom-rightcorner.
-zoom=>
x,y
Magnifiessourceregionbyxyinrespectivedirection.
-subsample=>
x,y
Reducessourceimagebyusingonlyeveryxythpixel.
$image
->get
(x,y);
ReturnsRGBvalueofpixelatcoordsxyaslistofthreeintegers.
$image
->put(data?-to=>
x1,y1,x2,y2?);
Setspixelsvaluesfortheregionx1y1x2y2for2-Darraydata.
$image
->read(pathName?,-option
=>
value...?);
ReadsimagedatafromfilepathNameinto
$imageusinggivenoptions.
-format=>
format-name
Specifiesimageformatoffile.
33
Perl/TkReferenceGuide
-file=>
pathName
PathnameoffilewithembeddedPODdirectives.
-scrollbars=>
scrollSpec
Scrollbarspecifications.
ScrolledPerl/Tkincludesthespecialconstructor
Scrolled
whichcreatesawidgetwith
attachedscrollbars,aslongasthewidgetclasssupportsthex/yscrollcommand(s),
as
Canvas
,
Entry
,
Listbox
and
Text
do.Scrollbarscanberequired,ormight
springintoexistanceonlywhenneeded.
$scrolled
=$
parent
->Scrolled
(widgetClass...);
Youmayspecifiyoption/valuepairswhicharepassedtothewidgetClass
constructor.-scrollbars=>
scrollbarSpecs
Thestringsnsewspecifiytop,botton,leftorrightscrollbars,respectively.
Thestringswcreatestwoscrollbars,ontheleftandbottomofthewidget.
Thestringomeansoptionalandrrequired,so’rwos’meansrequiredon
’west’(vertical),optionalon’south’(horizontal).
11.Images
Imagesarecreatedusingthe
DefineBitmap,
Bitmap
and
Photo
methods,
describedbelow.Bitmapshaveapixeldepthof2bits,whereasPhotoscanbefull
color24bitGIF89,XPM,XBMorBMPobjects.$widget
->DefineBitmap(bitmapName,bitColumns,bitRows,bitVector);
DefineabitmapnamedbitmapNamedirectlyinPerlcode.Thefirst
bitColumnsbitspackedinbitVectorarerowone.
Hereareimagemanipulationmethodscommontotheremainingtwoimagetypes:$image
->delete;
Deletestheimage.
$image
->height;
Returnspixelheightofimage.
$image
->imageNames
;
Returnsalistofthenamesofallexistingimages.
$image
->type;
Returnsthetypeofimage.
$image
->imageTypes
;
Returnsalistofvalidimagetypes.
$image
->width;
Returnspixelwidthofimage.
Whenanimageiscreatedviathe
DefineBitmap,
Bitmap
or
Photo
method,
Tkcreatesanimageobjectreferencetothetheimage.Forallimagetypes,this
objectsupportsthe
cget
and
configure
methodsinthesamemanneraswidgetsfor
changingandqueryingconfigurationoptions.Ofcourse,imageconfiguration
commandscanstillbepassedtothecreationmethod:$image
=$
mw->Photo(-file
=>
’/home/bug/photo.gif’);
32
Perl/TkReferenceGuide
$listbox->selectionAnchor
(index);
Settheselectionanchortoelementatindex.
$listbox->selectionClear(first?,last?);
Deselectelementsbetweenfirstandlastinclusive.
$listbox->selectionIncludes
(index);
Returns1ifelementatindexisselected,0otherwise.
$listbox->selectionSet(first?,last?);
Addallelementsbetweenfirstandlastinclusivetoselection.
$listbox->see(index);
Adjusttheviewinwindowsoelementatindexiscompletelyvisible.
$listbox->size
Returnsnumberofelementsinlistbox.
$listbox->xview
|yview
(args);
SeeWidgetScrollCommandsabove.
7.TheMenuWidget
MenuWidgetOptions-activebackground-borderwidth-font
-activeborderwidth-cursor-foreground
-activeforeground-disabledforeground-relief
-background
-postcommand=>
callback
SpecifyPerlcommandtoinvokeimmediatelybeforethemenuisposted.
-selectcolor=>
color
Specifiesindicatorcolorforcheckbuttonandradiobuttonentries.
-tearoff=>
boolean
Whethertoincludeatear-offentryattopofmenu.
-tearoffcommand=>
callback
Specifiescommandtoberunwhenmenuistornoff.Thenameofthemenu
andthenewtorn-offwindowwillbeappendedoninvocation.
-transient=>
boolean
Whethermenushouldbedisplayedastransientornot.
EntryTypes:cascade,checkbutton,command,radiobutton,
separator
MenuIndices:number(startsat0,normallythetearoffitem),
’active’,
’last’,’none’
,’
@y’,’matchPattern’
MenuWidgetCommands$menu->activate
(index);
Changestateofentryatindextobesoleactiveentryinmenu.
$menu->add
(type?,-option
=>
value...?);
Addnewentryoftypetypetobottomofmenu.Seebelowforoptions.
$menu->delete(index1?,index2?);
Deleteallentriesbetweenindex1andindex2inclusive.
$menu->entrycget
(index,-option);
Returncurrentvalueof-optionforentryatindex.
13
Perl/TkReferenceGuide
$menu->entryconfigure
(index?,-option
=>value...?);
Setoptionvaluesforentryatindex.
$menu->index
(index);
Returnsthenumericalindexcorrespondingtoindex.
$menu->insert
(index,type?,-option
=>
value...?);
Sameas
add
butinsertsnewentryjustbeforeentryatindex.
$menu->invoke
(index);
Invoketheactionofthemenuentryatindex.
$menu->post(x,y);
Displaymenuonscreenatroot-windowcoordinatesgivenbyx,y.
$menu->postcascade(index);
Postsubmenuassociatedwithcascadeentryatindex.
$menu->type(index);
Returnstypeofmenuentryatindex.
$menu->unpost;
Unmapwindowsoitisnolongerdisplayed.
$menu->ypostion(index);
Returnsthey-coordinatewithinthemenuwindowofthetopmostpixelin
theentryspecifiedbyindex.
MenuEntryOptionsThefollowingoptionsworkforallcascade,checkbutton,command,and
radiobuttonentriesunlessotherwisespecified.-activebackground-bitmap-image
-activeforeground-font-state
-background-foreground-underline
-accelerator=>
string
Specifiesstringtodisplayatrightsideofmenuentry.
-command=>
callback
Perlcommandtoexecuteentryisinvoked.
-indicatoron=>
boolean
Whetherindictorforcheckbuttonorradiobuttonentryshouldbedisplayed.
-label=>
string
Textualstringtodisplayonleftsideofmenuentry.
-menu=>
pathName
Pathnametoamenutopostwhencascadeentryisactive.
-offvalue=>
value
Valuetostoreincheckbuttonentry’sassociatedvariablewhendeselected.
-onvalue=>
value
Valuetostoreincheckbuttonentry’sassociatedvariablewhenselected.
-selectcolor=>
color
Colorforindicatorincheckbuttonandradiobuttonentries.
-selectimage=>
image
Imagetodrawinindicatorforcheckbuttonandradiobuttonentries.
-value=>
value
Valuetostoreinradiobuttonentry’sassociatedvariablewhenselected.
-variable=>
varRef
Nameofglobalvariabletosetwhencheckbuttonorradiobuttonisselected.
14
Perl/TkReferenceGuide
-justify=>let|right|center
Whentherearemultiplelinesoftextdisplayedinatab,thisoption
determinesthejustificationofthelines.
-createcmd=>
callback
Thecallbackinvokedthefirsttimethepageisshownonthescreen.
-raisecmd=>
callback
Thecallbackinvokedwheneverthispageisraisedbytheuser.
-state=>normal|disabled
Specifieswhetherthispagecanberaisedbytheuser.
-underline=>
integer
Specifiestheintegerindexofacharactertounderlineinthetab.
-wraplength=>
integer
Thisoptionspecifiesthemaximumlinelengthofthelabelstringonthistab.
$note->delete(page);
Deletesthepageidentifiedbypage.
$note->pagecget
(page,-option);
Returnsthecurrentvalueoftheconfigurationoptiongivenby-optioninthe
pagegivenbypage.Optionsmayhaveanyofthevaluesacceptedinthe
add
method.
$note->pageconfigure
(page,-option
=>
value);
Likeconfigureforthepageindicatedbypage.Optionsmaybeanyofthe
optionsacceptedbythe
add
method.
$note->raise(page);
Raisethepageidentifiedbypage.
$note->raised;
Returnsthenameofthecurrentlyraisedpage.
Optionmenu
-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
-options=>
[optionList]
Themenuitems,specifiedasareferencetoalistofstrings.
-command=>
callback
ThecallbacktoinvokeaftervarRefof-textvariableisset.
Pod-borderwidth-highlightbackground-relief
-cursor-highlightcolor-takefocus
-height-highlightthickness-width
31
Perl/TkReferenceGuide
$hlist->showEntry
(?entryPath?);
ShowsthelistentryentryPath.
$hlist->xview
;
Returnsalistoftworealfractionsbetween0and1describingthehorizontal
spanthatisvisibleinthewindow.
$hlist->xview
(entryPath);
AdjuststheviewinthewindowsothatthelistentryidentifiedbyentryPath
isalignedtotheleftedgeofthewindow.
$hlist->xviewMoveto
(fraction);
Adjuststheviewinthewindowsothatfractionofthetotalwidthofthe
HListisoff-screentotheleft.
$hlist->xviewScroll
(int,
units|pages
);
Shiftstheviewinthewindowleftorrightaccordingtointandwhat.
$hlist->yview
;
Returnsalistofrealfractionsbetween0and1describingtheverticalspan
thatisvisibleinthewindow.
$hlist->yview
(entryPath);
AdjuststheviewinthewindowsothatentryPathisdisplayedatthetopof
thewindow.
$hlist->yviewMoveto
(fraction);
Adjuststheviewinthewindowsothatfractionofthetotalheightofthe
HListisoff-screentothetop.
$hlist->yviewScroll
(int,
’units’|’pages’
);
Shiftstheviewinthewindowupordownaccordingtointandwhat.
NoteBook
-borderwidth-highlightbackground-relief
-cursor-highlightcolor-takefocus
-height-highlightthickness-width
-dynamicgeometry=>
boolean
Falseensuresallnoteboookpagesarethesamesize.Trueresizesthe
notebookasdifferentpagesareselected.
-ipadx=>
pixels
Theamountofinternalhorizontalpaddingaroundthepages.
-ipady=>
pixels
Theamountofinternalverticalpaddingaroundthepages.
$note->add
(page,-option
=>
value);
Addsapagewithnamepagetothenotebook.
-anchor=>n|ne|e|se|s|sw|w|nw|center
Specifieshowtheinformationinatabistobedisplayed.
-bitmap=>
bitmap
Specifiesabitmaptodisplayonthetabofthispage.Thebitmapisdisplayed
onlyifnoneofthe
-label
or
-image
optionsarespecified.
-image=>
image
Specifiesanimagetodisplayonthetabofthispage.Theimageisdisplayed
onlyifthe
-label
optionisnotspecified.
-label=>
string
Specifiesthetextstringtodisplayonthetabofthispage.
30
Perl/TkReferenceGuide
8.TheTextWidget
TextWidgetOptions-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=>
sizeSpaceinscreenunitsaboveparagraphs.
-spacing2=>
sizeSpaceinscreenunitsbetweenparagraphlines.
-spacing3=>
sizeSpaceinscreenunitsbelowparagraphs.
-tabs=>
tabList
Setoftabstopsasalistofscreendistancesgivingtheirpositions.Eachstop
maybefollowedbyoneof
left,
right,
center,or
numeric.
-wrap=>’none’|’char’|’word’
Howtowraplines.
TextIndicesSyntax:base?modifier...?
Base:’line.char’(linestartsat1,charstartsat0),’
@x,y’,
’end’,’mark’,
’tag.first’,’tag.last’,’pathName’
Modifier:’

count
chars’,’

count
lines’,
’linestart’,
’lineend’,
’wordstart’,
’wordend’
Ranges:Rangesincludeallcharactersfromthestartindexuptobutnot
includingthecharacteratthestopindex.
TextTagOptions-background-justify-spacing2
-borderwidth-relief-spacing3
-font-spacing1-wrap
-foreground
-bgstipple=>
bitmapStipplepatternforbackground.
-fgstipple=>
bitmapStipplepatternforforeground.
-lmargin1=>
sizeLeftmarginoffirstlineofaparagraph.
-lmargin2=>
sizeLeftmarginofwrappedlinesofaparagraph.
-offset=>
sizeOffsetofbaselinefromnormalbaseline.
-overstrike=>
boolean
Whethertooverstriketext.
-rmargin=>
sizeRightmarginofalllines.
-tabs=>
tabListSetoftabstops(see
-tabs
above).
-underline=>
boolean
Whethertounderlinetext.
15
Perl/TkReferenceGuide
TextEmbeddedWindowOptionsUse-windowtopassanyPerl/Tkwidgetreferenceto
windowCreate
.Manage
embeddedwindowswith
windowConfigure
and
windowCget
.
-align=>top|center|bottom|baseline
Wherewindowisdisplayedontheline.
-create=>
script
Scripttocreateandreturnwindowpathnameifno
-window
optionis
given.
-stretch=>
boolean
Whetherwindowshouldbestretchedverticallytofillline.
-window=>
widget
Nameofwindowtodisplay
TextWidgetCommands$text
->bbox
(index);
Returnsalist(x,y,width,height)givinganapproximateboundingboxof
charactergivenbyindex.
$text
->compare(index1,op,index2);
Comparesindicesindex1andindex2accordingtorelationaloperaterop.
$text
->delete(index1?,index2?);
Deleterangeofcharacters(index2defaultstoindex1
￿
1char).
$text
->dlineinfo
(index);
Returnsalist(x,y,width,height,baseline)describingthescreenareataken
bydisplaylineatindex.
$text
->dump(?switches,?index1?,index2?);
Returnsdetailedinfoontextwidgetcontentsinrangeindex1toindex2.
Switchesinclude
-all,
-mark,
-tag,
-text,
-window
forspecifying
typeofinforeturned.Theswitch
-command=>
callbackexiststoinvoke
aprocedureoneachelementtypeintherange.
$text
->get
(index1?,index2?);
Returnsstringofcharactersinrange(index2defaultstoindex1
￿
1char).
$text
->index
(index);
Returnspositionindexinline.charnotation.
$text
->insert
(index?,string?,tagList,string,tagList...??);
InsertstringintotextatindexapplyingtagsfromtagList.
$text
->markGravity
(markName
=>
?left|right
?);
Returns(orsets)whichadjacentcharacteramarkisattachedto.
$text
->markNames
Returnsalistofthenamesofallmarkscurrentlyset.
$text
->markNext
|
markPrevious
(index);
Returnnameofnext/previousmarkatorafter/beforeindex.
$text
->markSet(markName
=>
index);
SetmarkmarkNametopositionjustbeforecharacteratindex.
$text
->markUnset(markName
=>
?,markName...?);
Removeeachmarkspecifiedsotheyarenolongerusuableasindices.
$text
->scan(args);
SeeWidgetScrollCommandsabove.
16
Perl/TkReferenceGuide
$hlist->infoAnchor
;
ReturnstheentryPathofthecurrentanchor.
$hlist->infoBbox
(entryPath);
Returnsalistoffournumbersdescribingthevisibleboundingboxof
entryPath.
$hlist->infoChildren
(?entryPath?);
IfentrpyPathisgiven,returnsalistofitschildrenentries,otherwisereturns
alistofthetoplevel.
$hlist->infoData
(?entryPath?);
ReturnsthedataassociatedwithentryPath.
$hlist->infoDragsite
;
ReturnstheentryPathofthecurrentdragsite.
$hlist->infoDropsite
;
ReturnstheentryPathofthecurrentdropsite.
$hlist->infoExists
(entryPath);
ReturnsabooleanvalueindicatingwhetherentrpyPathexists.
$hlist->infoHidden
(entryPath);
ReturnsabooleanvalueindicatingwhetherentrpyPathishidden.
$hlist->infoNext
(entryPath);
ReturnstheentryPathofthelistentryimmediatelybelowthislistentry.
$hlist->infoParent
(entryPath);
ReturnsthenameoftheparentofentrpyPath.
$hlist->infoPrev
(entryPath);
ReturnstheentryPathofthelistentryimmediatelyabovethislistentry.
$hlist->infoSelection
;
Returnsalistofselectedentries.
$hlist->itemCget
(entryPath,col,option);
ReturnsthecurrentvalueofoptionforentryPathatcolumncol.
$hlist->itemConfigure(entryPath,col,?,option?,
=>
?value);
QueryormodifytheconfigurationoptionsofentryPathatcolumncol.
$hlist->itemCreate(entryPath,col,?,-itemtype
=>
type??,option
=>
value);
CreatesanewdisplayitematcolumncolofentryPath.
$hlist->itemDelete(entryPath,col);
DeletesthedisplayitematcolumncolofentryPath.
$hlist->itemExists(entryPath,col);
ReturnstrueifthereisadisplayitematcolumncolofentryPath.
$hlist->nearest(y);
ReturnstheentryPathofthevisibleelementnearesttoY-coordinatey.
$hlist->see(entryPath);
AdjusttheviewsothatentryPathisvisible.
$hlist->selectionClear(?from??,to?);
Deselectthelistentriesfromthroughto,inclusive.
$hlist->selectionGet;
Thisisanaliasforthe
infoSelection
widgetcommand.
$hlist->selectionIncludes
(entryPath);
ReturnstrueifentryPathiscurrentlyselected.
$hlist->selectionSet(from?,to);
Selectsallofthelistentrie(s)betweenbetweenfromandto,inclusive.
29
Perl/TkReferenceGuide
$hlist->dragsiteSet
(entryPath);
SetsthedragsitetothelistentryidentifiedbyentryPath.
$hlist->dragsiteClear
;
Removethedragsite,ifany.
$hlist->dropsiteSet
(entryPath);
SetsthedropsitetothelistentryidentifiedbyentryPath.
$hlist->dropsiteClear
;
Removethedropsite,ifany.
$hlist->entrycget
(entryPath,-option);
Returnsthecurrentvalueoftheconfigurationoption-optionforentryPath.
$hlist->entryconfigure
(entryPath?,-option
=>
value?);
QueryormodifytheconfigurationoptionsofthelistentryentryPath.
$hlist->headerCget
(col,option);
Ifcolumncolhasaheaderdisplayitem,returnsthevalueofthespecified
optionoftheheaderitem.
$hlist->headerConfigure(col?,option??
=>
value?);
Queryormodifytheconfigurationoptionsoftheheaderdisplayitemof
columncol.
$hlist->headerCreate(col?,-itemtype
=>
type??,-option
=>
value...?);
Createsanewdisplayitemastheheaderforcolumncol.
-borderwidth=>
width
Specifiestheborderwidthofthisheaderitem.
-headerbackground=>
color
Specifiesthebackgroundcolorofthisheaderitem.
-relief=>
relief
Specifiestherelieftypeoftheborderofthisheaderitem.
$hlist->headerDelete(col);
Deletestheheaderdisplayitemforcolumncol.
$hlist->headerExists(col);
Returnstrueifaheaderdisplayitemexistsforcolumncol.
$hlist->headerSize
(col);
Returnsatwoelementlistoftheform[width,height]oftheheaderdisplay
itemforcolumncol;
$hlist->hideEntry
(entryPath);
HidesthelistentryidentifiedbyentryPath.
$hlist->indicatorCget
(entryPath,option);
ReturnsthevalueofthespecifiedoptionoftheindicatorforentryPath.
$hlist->indicatorConfigure(entryPath?,option??
=>
value?);
Queryormodifytheconfigurationoptionsoftheindicatordisplayitemof
entryPath.
$hlist->indicatorCreate(entryPath?,-itemtype
=>
type??,option
=>
value);
CreatesanewdisplayitemastheindicatorforentryPath.
$hlist->indicatorDelete(entryPath);
DeletestheindicatordisplayitemforentryPath.
$hlist->indicatorExists(entryPath);
ReturntrueifanindicatordisplayitemexistsforentryPath.
$hlist->indicatorSize
(entryPath);
Returnsatwoelementlistoftheform[width,height]oftheindicator
displayitemforentryPath.
28
Perl/TkReferenceGuide
$text
->search
(?switches,?pattern,index?,stopIndex?);
Returnsindexoffirstcharactermatchingpatternintextrangeindexto
stopIndex.Switches:
-forwards,-backwards,-exact,-regexp,
-countvar,-nocase
$text
->see(index);
Adjusttheviewinwindowsocharacteratindexiscompletelyvisible.
$text
->tagAdd
(tagName,index1?,index2?);
ApplytagtagNametorange(index2defaultstoindex1
￿
1char).
$text
->tagBind
(tagName?,sequence?,script??);
Arrangeforscripttoberunwhenevereventsequenceoccursforacharacter
withtagtagName.
$text
->tagCget
(tagName
=>
-option);
Returncurrentvalueof-optionfortagtagName.
$text
->tagConfigure
(tagName?,-option?,value?,-option
=>
value...?);
Modifiestag-specificoptionsforthetagtagName.
$text
->tagDelete
(tagName?,tagName...?);
Deletealltaginformationforgiventags.
$text
->tagLower
(tagName?,belowThis?);
ChangepriorityoftagtagNamesoitisjustbelowtagbelowThis.
$text
->tagNames
(?index?);
Returnsalistofthenamesofalltagsassociatedwithcharacteratindex.If
indexisnotgiven,returnslistofalltagsdefinedinwidget.
$text
->tagNextrange
(tagName,index1?,index2?);
Searchescharacterrangeindex1toindex2(default
end)forthefirstregion
taggedwithtagName.Returnscharacterrangeofregionfound.
$text
->tagPrevrange
(tagName,index1?,index2?);
Like
tagNextrange
butsearchsbackwardsfromindex1toindex2(default
1.0).
$text
->tagRaise
(tagName?,aboveThis?);
ChangepriorityoftagtagNamesoitisjustabovetagaboveThis.
$text
->tagRanges
(tagName);
ReturnsalistdescribingallcharacterrangestaggedwithtagName.
$text
->tagRemove
(tagName,index1?,index2?);
RemovetagtagNameforallcharactersinrangeindex1toindex2.
$text
->windowCget
(index,-option);
Returncurrentvalueof-optionforembeddedwindowatindex.
$text
->windowConfigure
(index?,-option?,value?,-option
=>
value...?);
Modifiesembeddedwindow-specificoptionsforthewindowatindex.
$text
->windowCreate
(index?,-option
=>
value...?);
Createanewembeddedwindowatpositionindexwithspecifiedoptions.
$text
->windowNames
;
Returnslistofnamesofallwindowsembeddedinwidget.
$text
->xview
|yview
(args);
SeeWidgetScrollCommandsabove.
17
Perl/TkReferenceGuide
9.OtherStandardWidgets
Button
-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
$button
->flash;
Alternatecheckbuttonbetweenactiveandnormalcolors.
$button
->invoke
;
ToggletheselectionstateofthecheckbuttonandinvokethePerlcommand
specifiedwith
-command,ifany.
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=>
boolean
Whetherornottheindicatorshouldbedrawn.
-offvalue=>
value
Valuegiventovariablespecifiedwith
-variable
optionwhenthe
checkbuttonisdeselected.
-onvalue=>
value
Valuegiventovariablespecifiedwith
-variable
optionwhenthe
checkbuttonisselected.
-selectcolor=>
color
Colorusedtofillinindicatorwhenselected.
-selectimage=>
image
Imagedisplayedinindicatorwhenselected.
-variable=>
varRef
Variabletoassociatewithcheckbutton.
$checkbutton
->deselect;
Deselectthecheckbutton.
$checkbutton
->flash;
Alternatecheckbuttonbetweenactiveandnormalcolors.
18
Perl/TkReferenceGuide
-separator=>
string
Specifiesthecharactertousedastheseparatorcharacterwhenintepreting
thepath-namesoflistentries.Bydefaultthecharacter”.”isused.
-width=>
width
Specifiesthedesiredwidthforthewindowincharacters.
$hlist->add
(entryPath?,-option
=>
value?);
CreatesanewlistentrywiththepathnameentryPath.
-at=>
index
Insertthenewlistatthepositiongivenbypositionindex.
-after=>
index
Insertthenewlistentryaftertheentryidentifiedbyindex.
-before=>
index
Insertthenewlistentrybeforetheentryidentifiedbyindex.
-data=>
string
Specifiesastringtoassociatewiththislistentry.
-itemtype=>imagetext|text|window
Specifiesthedefaulttypeofdisplayitem.
-state=>normal|disabled
Specifieswhetherthisentrycanbeselectedorinvokedbytheuser.
$hlist->addchild
(parent?,-option
=>
value?);
AddsanewchildentrytothechildrenlistofthelistentryparentPathand
returnsthenewentryPath.
$hlist->anchorSet
(entryPath);
SetstheanchortothelistentryidentifiedbyentryPath.
$hlist->anchorClear
;
Removestheanchor,ifany.
$hlist->cget
(-option);
Returnsthecurrentvalueof-option.
$hlist->ColumnWidth(col?,-char??,width?);
Querysorsetsthewidthofthecolumncol.
$hlist->ColumnWidth(col
=>’’
);
Anemptystringindicatesthatthewidthofthecolumnshouldbejustwide
enoughtodisplaythewidestelementinthiscolumn.
$hlist->columnWidth(col,width);
Setcolumncoltopixelwidthwidth.
$hlist->columnWidth(col,-char
=>
nchars);
Thewidthissettobetheaveragewidthoccupiedbyncharsnumberof
charactersofthefontspecifiedbythe-fontoption.
$hlist->configure(?-option
=>
value?);
Queryormodifytheconfigurationoptionsofthewidget.
$hlist->deleteAll;
Deletealllistentries.
$hlist->deleteEntry
(entryPath);
DeletelistentryentryPath.
$hlist->deleteOffsprings(entryPath);
DeletealloffspringsofentryPath.
$hlist->deleteSiblings
(entryPath);
DeleteallthelistentriesthatsharetheparententryPath.
27
Perl/TkReferenceGuide
$fsel->Show
;
MaptheFileSelecttoplevelwindow;returnselectionorundef.
HList
-background-height-selectborderwidth
-borderwidth-highlightbackground-selectforeground
-cursor-highlightcolor-setGrid
-exportselection-highlightthickness-takefocus
-font-relief-width
-foreground-selectbackground-xscrollcommand
-yscrollcommand
-browsecmd=>
callback
Specifiesthecallbackinvokedwhentheuserbrowsesthroughtheentriesin
theHListwidget.
-columns=>
integer
SpecifiesthenumberofcolumnsinthisHListwidget.
-command=>
callback
Specifiesthecallbackinvokedwhentheuserselectsalistentry.
-drawBranch=>
boolean
Tureifabranchlineshouldbedrawntoconnectlistentriestotheirparents.
-header=>
boolean
Specifieswhetherheadersshouldbedisplayed(seethe
header
method
below).
-height=>
integer
Specifiesthedesiredheightforthewindowinnumberofcharacters.
-indent=>pixels|textchars
Specifiestheamountofhorizontalindentationbetweenalistentryandits
children.
-indicator=>
boolean
Specifieswhethertheindicatorsshouldbedisplayed.Seethe
indicator
methodsbelow.
-indicatorCmd=>
callback
Specifiesthecallbackexecutedwhentheusermanipulatestheindicatorof
anHListentry.Thedefaultcallbackisinvokedwithoneimplicitargument,
theentryPathoftheentrywhoseindicatorhasbeentriggered.
-itemType=>imagetext|text|window
Specifiesthedefaulttypeofdisplayitem.
-selectBackground=>
color
Specifiesthebackgroundcolorfortheselectedlistentries.
-selectBorderWidth=>
width
Specifiesthewidthofthe3-Dbordertodrawaroundselecteditems.
-selectForeground=>
color
Specifiestheforegroundcolorfortheselectedlistentries.
-selectMode=>singlebrowsemultipleextended
Specifiesoneofseveralstylesformanipulatingtheselection.
-sizeCmd=>
callback
SpecifiesthecallbackexecutedwhenevertheHListwidgetchangessize.
26
Perl/TkReferenceGuide
$checkbutton
->invoke
;
ToggletheselectionstateofthecheckbuttonandinvokethePerlcommand
specifiedwith
-command,ifany.
$checkbutton
->select;
Selectthecheckbutton.
$checkbutton
->toggle
;
Toggletheselectionstateofthecheckbutton.
Frame
-borderwidth-highlightbackground-relief
-cursor-highlightcolor-takefocus
-height-highlightthickness-width
-background=>
color
Sameasstandardexpectitmaybetheemptystringtopreservecolormap.
-class=>
name
Classnametouseinqueryingtheoptiondatabaseandforbindings.
-colormap=>
colormap
Colormaptouseforthewindowifdifferentfromparent.
-visual=>
visual
Visualinfotouseforthewindowifdifferentfromparent.
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=>
boolean
Iftruethenasmallindicatorwillbedisplayedonthebuttons’srightsideand
thedefaultmenubindingswilltreatthisasanoptionmenubutton.
-menu=>
pathName
Pathnameofmenuwidgettopostwhenbuttonisinvoked.
19
Perl/TkReferenceGuide
Message
-anchor-highlightbackground-relief
-background-highlightcolor-takefocus
-borderwidth-highlightthickness-text
-cursor-justify-textvariable
-font-padx-width
-foreground-pady
-aspect
integer
Ratiooftextwidthtotextheighttimes100tousetodisplaytext.
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=>
boolean
Whetherornottheindicatorshouldbedrawn.
-selectcolor=>
color
Colorusedtofillinindicatorwhenselected.
-selectimage=>
image
Imagedisplayedinindicatorwhenselected.
-value=>
value
Valuegiventovariablespecifiedwith
-variable
optionwhenthe
radiobuttonisselected.
-variable=>
varRef
Variabletoassociatewithradiobutton.
$radiobutton
->deselect;
Deselecttheradiobutton.
$radiobutton
->flash;
Alternateradiobuttonbetweenactiveandnormalcolors.
$radiobutton
->invoke
;
ToggletheselectionstateoftheradiobuttonandinvokethePerlcommand
specifiedwith
-command,ifany.
$radiobutton
->select;
Selecttheradiobutton.
Scale
-activebackground-highlightbackground-repeatdelay
-background-highlightcolor-repeatinterval
-borderwidth-highlightthickness-state
-cursor-orient-takefocus
-foreground-relief-troughcolor
20
Perl/TkReferenceGuide
Dialog
-borderwidth-highlightbackground-relief
-cursor-highlightcolor-takefocus
-height-highlightthickness-width
-title=>
string
Titletodisplayinthedialog’sdecorativeframe.
-text=>
string
Messagetodisplayinthedialogwidget.
-bitmap=>
bitmap
Bitmaptodisplayinthedialog.
-default_button=>
string
Textlabelofthebuttonthatistodisplaythedefaultring.
-buttons=>
[@button
_labels]
Areferencetoalistofbuttonlabelstrings.
$dialog
->Show
(?-global?);
Showdialogandreturntheselectionasastring.Thegrabislocalunless
-globalisspecified.
FileSelect
-borderwidth-highlightbackground-relief
-cursor-highlightcolor-takefocus
-height-highlightthickness-width
-width=>
width
Widthoffileanddirectorylistboxes.
-height=>
height
Heightoffileanddirectorylistboxes.
-directory=>
pathName
Startingdirectorypathname.
-filelabel=>
string
Labelforfileentrywidget.
-filelistlabel=>
string
Labelforfilelistboxwidget.
-filter=>
string
Limitsearchtothewildcardstring.
-dirlabel=>
string
Labelfordirectoryentrywidget.
-dirlistlabel=>
string
Labelfordirectorylistboxwidget.
-accept=>
callback
OverrideFileSelectAcceptsubroutinewithyourown.
-create=>
boolean
Trueifit’sokaytocreatedirectories.
-verify=>
[-verifyOptions]
AlistofPerlfiletestoperatorsand/orcallbackstoyourownverify
subroutine.Thesubroutineisimplicitlycalledwithadirectorypathname
andafile(ordirectory)name,andpossiblyoptionalarguments.
25
Perl/TkReferenceGuide
-cursor-highlightcolor-takefocus
-height-highlightthickness-width
-listwidth=>
width
Specifiesthecharacterwidthofthepopuplistbox.
-variable=>
varRef
Whereenteredvalueisstored.
-browsecmd=>
callback
Specifiesafunctiontocallwhenaselectionismade.Itispassedthewidget
andthetextoftheentryselected.ThisfunctioniscalledaftervarRefhas
beenassignedthevalue.
-listcmd=>
callback
Specifiesthefunctiontocallwhenthebuttonnexttotheentryispressedto
popupthechoicesinthelistbox.Thisiscalledbeforepoppingupthe
listbox,soitcanbeusedtopopulatetheentriesinthelistbox.
$browse
->insert
(index,string);
Insertsthetextofstringatthespecifiedindex.Thisstringthenbecomes
availableasoneofthechoices.
$browse
->delete(index1?,index2?);
Deletesitemsfromindex1toindex2.
ColorEditor
-borderwidth-highlightbackground-relief
-cursor-highlightcolor-takefocus
-height-highlightthickness-width
-title=>
string
Topleveltitle,default=’’.
-cursor=>
cursor
AvalidTkcursorspecification(defaultistop_left_arrow).Thiscursoris
usedoverallColorEditorhotspots.
-command=>
callback
Optionalreplacementfor
set_colors
colorconfigurator.
-widgets=>
[widgetList]
Areferencetoalistofwidgetsforthecolorconfiguratortocolor.
-display_status=>
boolean
TruetodisplaytheColorEditorstatuswindowwhenapplyingcolors.
-add_menu_item=>
itemString
’SEP’(aseparator),oracolorattributemenuitem.
-delete_menu_item=>
itemString
’SEP’,acolorattributemenuitem,orcolorattributemenuordinal.
$cedit->Show
;
MaptheColoreditortoplevelwindow.
$cedit->delete_widgets
([widgetList]);
AreferencetoalistofwidgetstoremovefromColorEditor’sconsideration.
24
Perl/TkReferenceGuide
-font
-bigincrement=>
number
Arealvaluetouseforlargeincrementsofthescale.
-command=>
callback
SpecifiedaPerlcommandtoinvokewhenscale’svalueischanged.The
scale’svaluewillbeappendedasanadditionalargument.
-digits=>
integer
Anintegerspecifyinghowmanysignificantdigitsshouldberetained.
-from=>
number
Arealvaluecorrespondingtoleftortopendofthescale.
-label=>
string
Astringtodisplayaslabelforthescale.
-length=>
size
Specifiestheheight(width)forvertical(horizontal)scales.
-resolution=>
number
Realvaluetowhichscale’svaluewillberoundedtoanevenmultipleof.
-showvalue=>
boolean
Whetherornotscale’scurrentvalueshouldbedisplayedinsidelabel.
-sliderlength=>
size
Sizeoftheslider,measuredalongtheslider’slongdimension.
-sliderrelief=>
relief
Specifythereliefusedtodisplaytheslider.
-tickinterval=>
number
Arealvaluetospecifythespacingbetweennumericaltickmarksdisplayed.
-to=>
number
Arealvaluecorrespondingtotherightorbottomendofthescale.
-variable=>
varRef
Nameofaglobalvariabletolinktothescale.
-width=>
width
Narrowdimensionofscale(notincludingborder).
$scale->coords
(?value?);
Returnsxandycoordinatesofpointcorrespoindingtovalue.
$scale->get
(?x,y?);
Ifx,yisgiven,returnsscalevalueatthatcoordiantepostion.Otherwise,
scale’scurrentvalueisreturned.
$scale->identify(x,y);
Returnsstringindicatingpartofscaleatpostionx,y.Maybeoneof
’slider’,’trough1’,’trough2’
orempty.
$scale->set(value);
Changesthecurrentvalueofscaletovalue.
Scrollbar-activebackground-highlightcolor-repeatdelay
-background-highlightthickness-repeatinterval
-borderwidth-jump-takefocus
-cursor-orient-troughcolor
-highlightbackground-relief
21
Perl/TkReferenceGuide
-activerelief=>
relief
Relieftousewhendisplayingtheelementthatisactive.
-command=>
callbackPrefix
PrefixofaPerlcommandtoinvoketochangetheviewinthewidget
associatedwiththescrollbar.
-elementborderwidth=>
width
Widthofbordersaroundinternalelements(arrowsandslider).
-width=>
width
Narrowdimensionofscrollbar(notincludingborder).
Elements:arrow1,trough1,slider,trough2,arrow2$scrollbar
->activate
(?element?);
Displayelementwithactiveattributes.
$scrollbar
->delta(deltaX,deltaY);
ReturnsfractionalpositionchangeforslidermovementofdeltaXdeltaY.
$scrollbar
->fraction(x,y);
Returnsarealnumberbetween0and1indicatingwherethepointgivenby
pixelcoordsxyliesinthetroughareaofthescrollbar.
$scrollbar
->get
;
Returnscurrentscrollbarsettingsasthelist
{firstlast
}.
$scrollbar
->identify(x,y);
Returnsnameofelementunderpixelcoordsxy.
$scrollbar
->set(first,last);
Describescurrentviewofassociatedwidgetwherefirstandlastarethe
percentagedistancefromwidget’sbeginningofthestartandendoftheview.
Toplevel-borderwidth-highlightbackground-relief
-cursor-highlightcolor-takefocus
-height-highlightthickness-width
-background=>
color
Sameasstandardbutmybeemptytopreservecolormapspace.
-class=>
string
Classnameforthewindowtobeusedbyoptiondatabase.
-colormap=>
colormap
Colormaptouseforwindow.Maybetheword
new,pathnameofother
toplevel,oremptyforthedefaultcolormapofscreen.
-screen=>
screen
Screenonwhichtoplacethewindow.
-visual=>
visual
Specifiesvisualtouseforwindow.
22
Perl/TkReferenceGuide
10.Perl/TkWidgets
HereareTixandusercontributedwidgetsparticulartoPerl/Tk.Adjuster
-borderwidth-highlightbackground-relief
-cursor-highlightcolor-takefocus
-height-highlightthickness-width
$widget
->packAdjust
(?packOptions?);
If
$widgetispackedwith
-side=>left|right
thenwidthis
adjusted.Ifpacked
-side=>top|bottom
thenheightisadjusted.
Ballon
-borderwidth-highlightbackground-relief
-cursor-highlightcolor-takefocus
-height-highlightthickness-width
-initwait=>
delay
Millisecondstowaitwithoutactivitybeforepoppingupahelpballoon
(default350milliseconds).Thisappliesonlytothepoppedupballoon;the
statusbarmessageisshowninstantly.
-state=>balloon|status|both|none
Indicatesthatthehelpballoon,statusbarhelp,bothornone,respectively,
shouldbeactivatedwhenthemousepausesovertheclientwidget.
-statusbar=>$
widget
Specifiesthewidgetusedtodisplaythestatusmessage.Thiswidgetshould
acceptthe
-text
optionandistypicallyaLabel.
$balloon->attach
(-options);
Attachesthewidgetindicatedbywidgettothehelpsystem.
-statusmsg=>
statusMessage
Themessageshownonthestatusbarwhenthemousepassesoverthisclient.
Ifnotspecifiedbut-msgisspecifiedthenthemessagedisplayedonthe
statusbaristhesameastheargumentfor-msg.
-balloonmsg=>
balloonMessage
Themessagedisplayedintheballoonwhenthemousepausesoverthe
client.Aswith-statusmsgifthisisnotspecified,thenittakesitsvaluefrom
the-msgspecification.Ifneither-balloonmsgnor-msgarespecified,thenan
emptyballoonwillbepoppedup.
-msg=>
defaultMessage
Thecatch-allfor-statusmsgand-balloonmsg.Thisisaconvenientwayof
specifyingthesamemessagetobedisplayedinboththeballoonandthe
statusbarfortheclient.
$balloon->detach
($widget);
Detachesthespecifiedwidgetfromthehelpsystem.
BrowseEntry-borderwidth-highlightbackground-relief
23