Manual Pages for UNIX Darwin command on man treectrl

treectrl(n) Tk Commands treectrl(n)

NAME

treectrl - Create and manipulate hierarchical multicolumn widgets

SYNOPSIS

package require ttrreeeeccttrrll 11..00 ttrreeeeccttrrll pathName ?options? pathName aaccttiivvaattee itemDesc pathName ccaannvvaassxx screenx pathName ccaannvvaassyy screeny pathName ccggeett option

pathName ccoollllaappssee ?-rreeccuurrssee? ?itemDesc ...?

pathName ccoolluummnn option column ?arg ...? pathName ccoolluummnn bbbbooxx column pathName ccoolluummnn ccggeett column option pathName ccoolluummnn ccoonnffiigguurree column ?option? ?value? ?option value ...? pathName ccoolluummnn ddeelleettee column pathName ccoolluummnn iinnddeexx column pathName ccoolluummnn mmoovvee column before pathName ccoolluummnn nneeeeddeeddwwiiddtthh column pathName ccoolluummnn wwiiddtthh column pathName ccoommppaarree itemDesc1 op itemDesc2 pathName ccoonnffiigguurree ?option? ?value option value ...? pathName ccoonntteennttbbooxx pathName ddeebbuugg option ?arg arg ...? pathName ddeebbuugg ccggeett element option pathName ddeebbuugg ccoonnffiigguurree element ?option? ?value? ?option value ...? pathName ddeebbuugg ddiinnffoo pathName ddeebbuugg ssccrroollll pathName ddeepptthh ?itemDesc? pathName ddrraaggiimmaaggee option ?arg ...? pathName ddrraaggiimmaaggee aadddd itemDesc ?column? ?element? pathName ddrraaggiimmaaggee ccggeett option pathName ddrraaggiimmaaggee cclleeaarr pathName ddrraaggiimmaaggee ccoonnffiigguurree ?option? ?value? ?option value ...? pathName ddrraaggiimmaaggee ooffffsseett ?x y? pathName ddrraaggiimmaaggee vviissiibbllee ?boolean? pathName eelleemmeenntt option ?element? ?arg arg ...? pathName eelleemmeenntt ccggeett element option pathName eelleemmeenntt ccoonnffiigguurree element ?option? ?value? ?option value ...? pathName eelleemmeenntt ccrreeaattee element type ?option value ...? pathName eelleemmeenntt ddeelleettee ?element ...? pathName eelleemmeenntt nnaammeess pathName eelleemmeenntt ttyyppee element

pathName eexxppaanndd ?-rreeccuurrssee? ?itemDesc ...?

pathName iiddeennttiiffyy x y pathName iinnddeexx itemDesc pathName iitteemm option ?arg ...? pathName iitteemm aanncceessttoorrss itemDesc pathName iitteemm bbbbooxx itemDesc ?column? ?element? pathName iitteemm cchhiillddrreenn itemDesc pathName iitteemm ccoommpplleexx itemDesc list ... pathName iitteemm ccrreeaattee pathName iitteemm ddeelleettee first ?last? pathName iitteemm dduummpp itemDesc pathName iitteemm eelleemmeenntt command itemDesc column element ?arg ...? pathName iitteemm eelleemmeenntt aaccttuuaall itemDesc column element option pathName iitteemm eelleemmeenntt ccggeett itemDesc column element option pathName iitteemm eelleemmeenntt ccoonnffiigguurree itemDesc column element ?option? ?value? ?option value ...? pathName iitteemm ffiirrssttcchhiilldd parent ?child? pathName iitteemm hhaassbbuuttttoonn itemDesc ?boolean? pathName iitteemm iinnddeexx itemDesc pathName iitteemm iissaanncceessttoorr itemDesc descendant pathName iitteemm iissooppeenn itemDesc pathName iitteemm llaassttcchhiilldd parent ?child? pathName iitteemm nneexxttssiibblliinngg sibling ?next? pathName iitteemm nnuummcchhiillddrreenn itemDesc pathName iitteemm ppaarreenntt itemDesc pathName iitteemm pprreevvssiibblliinngg sibling ?prev? pathName iitteemm rreemmoovvee itemDesc pathName iitteemm rrnncc itemDesc pathName iitteemm ssoorrtt itemDesc ?option ...? pathName iitteemm ssttaattee ggeett itemDesc ?stateName ...? pathName iitteemm ssttaattee sseett itemDesc ?lastItem? ?stateDescList? pathName iitteemm ssttyyllee command itemDesc ?arg ...? pathName iitteemm ssttyyllee eelleemmeennttss itemDesc column pathName iitteemm ssttyyllee mmaapp itemDesc column style map pathName iitteemm ssttyyllee sseett itemDesc ?column? ?style? ?column style ...? pathName iitteemm tteexxtt itemDesc column ?text? ?column text ...? pathName iitteemm vviissiibbllee itemDesc ?boolean? pathName mmaarrqquueeee option ?arg ...? pathName mmaarrqquueeee aanncchhoorr ?x y? pathName mmaarrqquueeee ccggeett option pathName mmaarrqquueeee ccoonnffiigguurree ?option? ?value? ?option value ...? pathName mmaarrqquueeee ccoooorrddss ?x1 y1 x2 y2? pathName mmaarrqquueeee ccoorrnneerr ?x y? pathName mmaarrqquueeee iiddeennttiiffyy pathName mmaarrqquueeee vviissiibbllee ?boolean? pathName nnoottiiffyy option ?arg ...? pathName nnoottiiffyy bbiinndd ?object? ?pattern? ?script? pathName nnoottiiffyy ccoonnffiigguurree window pattern ?option? ?value? ?option value ...? pathName nnoottiiffyy ddeettaaiillnnaammeess eventName pathName nnoottiiffyy eevveennttnnaammeess pathName nnoottiiffyy ggeenneerraattee pattern ?charMap? pathName nnoottiiffyy iinnssttaallll ddeettaaiill eventName detail ?percentsCommand? pathName nnoottiiffyy iinnssttaallll eevveenntt eventName ?percentsCommand? pathName nnoottiiffyy lliinnkkaaggee eventName ?detail? pathName nnoottiiffyy uunniinnssttaallll ddeettaaiill eventName detail pathName nnoottiiffyy uunniinnssttaallll eevveenntt eventName pathName nnuummccoolluummnnss pathName nnuummiitteemmss pathName oorrpphhaannss pathName rraannggee first last pathName ssttaattee option ?stateName? pathName ssttaattee ddeeffiinnee stateName pathName ssttaattee lliinnkkaaggee stateName pathName ssttaattee nnaammeess pathName ssttaattee uunnddeeffiinnee ?stateName ...? pathName sseeee itemDesc pathName sseelleeccttiioonn option arg pathName sseelleeccttiioonn aadddd first ?last? pathName sseelleeccttiioonn aanncchhoorr ?itemDesc? pathName sseelleeccttiioonn cclleeaarr ?first? ?last? pathName sseelleeccttiioonn ccoouunntt pathName sseelleeccttiioonn ggeett pathName sseelleeccttiioonn iinncclluuddeess itemDesc pathName sseelleeccttiioonn mmooddiiffyy select deselect pathName ssttyyllee option ?element? ?arg arg ...? pathName ssttyyllee ccggeett style option pathName ssttyyllee ccoonnffiigguurree style ?option? ?value? ?option value ...? pathName ssttyyllee ccrreeaattee style ?option value ...? pathName ssttyyllee ddeelleettee ?style ...? pathName ssttyyllee eelleemmeennttss style ?elementList? pathName ssttyyllee llaayyoouutt style element ?option? ?value? ?option value ...? pathName ssttyyllee nnaammeess

pathName ttooggggllee ?-rreeccuurrssee? ?itemDesc ...?

pathName xxvviieeww ?args? pathName xxvviieeww pathName xxvviieeww mmoovveettoo fraction pathName xxvviieeww ssccrroollll number what pathName yyvviieeww ?args? pathName yyvviieeww pathName yyvviieeww mmoovveettoo fraction pathName yyvviieeww ssccrroollll number what

DESCRIPTION

ttrreeeeccttrrll pathName ?options?

The ttrreeeeccttrrll command creates a new window (given by the pathName argu-

ment) and makes it into a treectrl widget. Additional options,

described above, may be specified on the command line or in the option

database to configure aspects of the treectrl such as its background

color and relief. The ttrreeeeccttrrll command returns the path name of the new window. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist.

A treectrl is a widget which displays items one per line. Every item

has a set of states, which are boolean properties. The item may be spread about one or more columns. For each column of an item there is a style associated, which determines how to display the item's column respecting the item's current state set. One column can be defined to display the data in a hierarchical structure.

Normally the origin of the coordinate system is at the upper-left cor-

ner of the window containing the treectrl. It is possible to adjust

the origin of the coordinate system relative to the origin of the win-

dow using the xxvviieeww and yyvviieeww widget commands; this is typically used for scrolling.

A treectrl widget can be horizontal or vertical oriented like many

other Tk widgets. For displaying hierarchical data only vertical ori-

entation is useful, since only then the children of an item are dis-

played directly below their parent. If the treectrl widget is used

only to display data in a multicolumn listbox, the specification of an orientation will give useful results. SSTTAANNDDAARRDD OOPPTTIIOONNSS

-bbaacckkggrroouunndd

-bboorrddeerrwwiiddtthh

-ccuurrssoorr

-ffoonntt

-hhiigghhlliigghhttbbaacckkggrroouunndd

-hhiigghhlliigghhttccoolloorr

-hhiigghhlliigghhtttthhiicckknneessss

-oorriieenntt

-rreelliieeff

-ttaakkeeffooccuuss

-xxssccrroollllccoommmmaanndd

-yyssccrroollllccoommmmaanndd

-ffoorreeggrroouunndd

See the ooppttiioonn manual entry for details on the standard options. WWIIDDGGEETT SSPPEECCIIFFIICC OOPPTTIIOONNSS

Command-Line Switch: -bbaacckkggrroouunnddmmooddee

Database Name: bbaacckkggrroouunnddMMooddee Database Class: BBaacckkggrroouunnddMMooddee

Specifies the desired mode for changing the background of indi-

vidual items. The value should be one of rrooww, ccoolluummnn, iinnddeexx, or vviissiinnddeexx. The default is rrooww. This option has only an effect

for columns which have -iitteemmbbaacckkggrroouunndd defined as list of two or

more colors (see section CCOOLLUUMMNNSS below for more on this). The

color of items is changed for any row or column, if rrooww or ccooll-

uummnn is specified respectively. When iinnddeexx is specified, col-

lapsed items are counted also for evaluating the background color, for vviissiinnddeexx only the visible items are counted.

Command-Line Switch: -bbuuttttoonnccoolloorr

Database Name: bbuuttttoonnCCoolloorr Database Class: BBuuttttoonnCCoolloorr Specifies the foreground color which should be used for drawing the outline and the plus or minus sign of the button to the left of an item.

Command-Line Switch: -bbuuttttoonnssiizzee

Database Name: bbuuttttoonnSSiizzee Database Class: BBuuttttoonnSSiizzee Specifies the diameter of the button drawn to the left of an item in any of the forms acceptable to TTkkGGeettPPiixxeellss.

Command-Line Switch: -bbuuttttoonntthhiicckknneessss

Database Name: bbuuttttoonnTThhiicckknneessss Database Class: BBuuttttoonnTThhiicckknneessss Specifies the width of the outline and the plus or minus sign of the button to the left of an item in any of the forms acceptable to TTkkGGeettPPiixxeellss.

Command-Line Switch: -cclloosseeddbbuuttttoonnbbiittmmaapp

Database Name: cclloosseeddBBuuttttoonnBBiittmmaapp Database Class: CClloosseeddBBuuttttoonnBBiittmmaapp Specifies the bitmap to be used as the button to the left of an closed item in any of the forms acceptable to TTkkGGeettPPiixxeellss.

Command-Line Switch: -cclloosseeddbbuuttttoonniimmaaggee

Database Name: cclloosseeddBBuuttttoonnIImmaaggee Database Class: CClloosseeddBBuuttttoonnIImmaaggee Specifies the image to be used as the button to the left of an closed item in any of the forms acceptable to TTkkGGeettIImmaaggee.

Command-Line Switch: -ccoolluummnnpprrooxxyy

Database Name: ccoolluummnnPPrrooxxyy Database Class: CCoolluummnnPPrrooxxyy If this option specifies a non empty value, it should be a screen distance in any of the forms acceptable to TTkkGGeettPPiixxeellss.

Then a 1 pixel thick vertical line will be drawn at the speci-

fied screen distance from the left edge of the treectrl widget,

which reaches from top to bottom of the treectrl widget and uses

an inverting color (i.e black on lighter background, white on darker background). This line can be used to give the user a visual feedback during column resizing.

Command-Line Switch: -ddoouubblleebbuuffffeerr

Database Name: ddoouubblleeBBuuffffeerr Database Class: DDoouubblleeBBuuffffeerr

Specifies if double-buffering should be used to improve display-

ing. The value should be one of nnoonnee, wwiinnddooww, or iitteemm. For

nnoonnee no double-buffering is used at all, which may be most mem-

ory efficient, but will probably generate some flickering on the

screen. For wwiinnddooww the complete tree is double-buffered, which

requires a buffer big enough to contain the complete widget.

For iitteemm, which is the default, every item is separately double-

buffered, so it works with a buffer size as big as the biggest item.

Command-Line Switch: -hheeiigghhtt

Database Name: hheeiigghhtt Database Class: HHeeiigghhtt Specifies the desired height for the window in any of the forms acceptable to TTkkGGeettPPiixxeellss. The default is 200 pixel. If this option is less than or equal to zero then the window will not request any size at all.

Command-Line Switch: -iinnddeenntt

Database Name: iinnddeenntt Database Class: IInnddeenntt

Specifies the amount of indentation in any of the forms accept-

able to TTkkGGeettPPiixxeellss. The default is 19 pixel. Indentation is the screen distance an item is displayed more to the right than its father.

Command-Line Switch: -iitteemmhheeiigghhtt

Database Name: iitteemmHHeeiigghhtt Database Class: IItteemmHHeeiigghhtt Specifies the minimal height of an item in any of the forms acceptable to TTkkGGeettPPiixxeellss. The default is 0, which means that every item has exactly the height of it stallest element.

Command-Line Switch: -lliinneeccoolloorr

Database Name: lliinneeCCoolloorr Database Class: LLiinneeCCoolloorr

Specifies the color which should be used for drawing the con-

necting lines between related items.

Command-Line Switch: -lliinneessttyyllee

Database Name: lliinneeSSttyyllee Database Class: LLiinneeSSttyyllee Specifies the style of the connecting lines between related items, should be ddoott which is the default, or ssoolliidd.

Command-Line Switch: -lliinneetthhiicckknneessss

Database Name: lliinneeTThhiicckknneessss Database Class: LLiinneeTThhiicckknneessss Specifies the thickness of the connecting lines between related items in any of the forms acceptable to TTkkGGeettPPiixxeellss.

Command-Line Switch: -ooppeennbbuuttttoonnbbiittmmaapp

Database Name: ooppeennBBuuttttoonnBBiittmmaapp Database Class: OOppeennBBuuttttoonnBBiittmmaapp Specifies the bitmap to be used as the button to the left of an opened item in any of the forms acceptable to TTkkGGeettBBiittmmaapp.

Command-Line Switch: -ooppeennbbuuttttoonniimmaaggee

Database Name: ooppeennBBuuttttoonnIImmaaggee Database Class: OOppeennBBuuttttoonnIImmaaggee Specifies the image to be used as the button to the left of an opened item in any of the forms acceptable to TTkkGGeettIImmaaggee.

Command-Line Switch: -ssccrroollllmmaarrggiinn

Database Name: ssccrroollllMMaarrggiinn Database Class: SSccrroollllMMaarrggiinn The interpretation of this option is left to Tcl scripts that implement scrolling: the widget implementation ignores this option entirely. Defaults to 0.

Command-Line Switch: -sseelleeccttmmooddee

Database Name: sseelleeccttMMooddee Database Class: SSeelleeccttMMooddee Specifies one of several styles for manipulating the selection.

The value of the option may be arbitrary, but the default bind-

ings expect it to be either ssiinnggllee, bbrroowwssee, mmuullttiippllee, or eexxtteennddeedd; the default value is bbrroowwssee.

Command-Line Switch: -sshhoowwbbuuttttoonnss

Database Name: sshhoowwBBuuttttoonnss Database Class: SShhoowwBBuuttttoonnss Specifies a boolean value that determines whether this widget displays a button to the left of any item. If the button is actually drawn can be configured for every item with the iitteemm hhaassbbuuttttoonn widget command, but if this option is set to false, the configuration of an item has no effect. The default value is true.

Command-Line Switch: -sshhoowwhheeaaddeerr

Database Name: sshhoowwHHeeaaddeerr Database Class: SShhoowwHHeeaaddeerr Specifies a boolean value that determines whether this widget should display the header line with the column names at the top of the widget. The default value is true.

Command-Line Switch: -sshhoowwlliinneess

Database Name: sshhoowwLLiinneess Database Class: SShhoowwLLiinneess Specifies a boolean value that determines whether this widget should draw the connecting lines between related items. The default value is true.

Command-Line Switch: -sshhoowwrroooott

Database Name: sshhoowwRRoooott Database Class: SShhoowwRRoooott Specifies a boolean value that determines whether this widget should draw the root item. By suppressing the drawing of the root item the widget can have multiple items that appear as toplevel items. The default value is true.

Command-Line Switch: -sshhoowwrroooottbbuuttttoonn

Database Name: sshhoowwRRoooottBBuuttttoonn Database Class: SShhoowwRRoooottBBuuttttoonn Specifies a boolean value that determines whether this widget should draw a button before the root item. The default value is false.

Command-Line Switch: -ttrreeeeccoolluummnn

Database Name: ttrreeeeCCoolluummnn Database Class: TTrreeeeCCoolluummnn Specifies an integer value that determines which column displays the data in an hierarchical fashion. Default is 0 meaning that the first column displays the tree.

Command-Line Switch: -wwiiddtthh

Database Name: wwiiddtthh Database Class: WWiiddtthh Specifies the desired width for the window in any of the forms acceptable to TTkkGGeettPPiixxeellss. The default is 200 pixel. If this option is less than or equal to zero then the window will not request any size at all.

Command-Line Switch: -wwrraapp

Database Name: wwrraapp Database Class: WWrraapp

Specifies how to arrange items inside treectrl's window. The

value must be an emtyp string, wwiinnddooww, or a list with an integer as first element and either iitteemmss or ppiixxeellss as second element. The empty string as wrap mode means that each item appears on exactly one line on the screen. In the other modes multiple items may be displayed in one screen line. In wwiinnddooww mode a screen line break may occur after any element; in iitteemmss mode a line break will only be made after the specified number of items; in ppiixxeellss mode a line break will only be made after the specified screen distance is reached.

Command-Line Switch: -xxssccrroollllddeellaayy

Database Name: xxSSccrroollllDDeellaayy Database Class: SSccrroollllDDeellaayy Specifies the amount of time before the default binding should handle repeating mouse motion events in horizontal direction with button 1 pressed. The value should be a list of upto 2

integers. The first integer specifies the timespan in microsec-

onds before the active item should be changed to get nearer to the current mouse position. If there are two integers specified, the first is only used for the first motion event, any repeating

motion events are handled after the seconds amount of milisec-

onds is elapsed.

Command-Line Switch: -xxssccrroolllliinnccrreemmeenntt

Database Name: xxSSccrroollllIInnccrreemmeenntt Database Class: SSccrroollllIInnccrreemmeenntt Specifies an increment for horizontal scrolling, in any of the usual forms permitted for screen distances. If the value of this option is greater than zero, the horizontal view in the window will be constrained so that the x coordinate at the left

edge of the window is always an even multiple of -xxssccrroolllliinnccrree-

mmeenntt; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar are selected)

will also be -xxssccrroolllliinnccrreemmeenntt. If the value of this option is

less than or equal to zero, then horizontal scrolling is uncon-

strained.

Command-Line Switch: -yyssccrroollllddeellaayy

Database Name: yySSccrroollllDDeellaayy Database Class: SSccrroollllDDeellaayy Specifies the amount of time before the default binding should handle repeating mouse motion events in vertical direction with

button 1 pressed. The value should be a list of upto 2 inte-

gers. The first integer specifies the timespan in microseconds before the active item should be changed to get nearer to the current mouse position. If there are two integers specified, the first is only used for the first motion event, any repeating

motion events are handled after the seconds amount of milisec-

onds is elapsed.

Command-Line Switch: -yyssccrroolllliinnccrreemmeenntt

Database Name: yySSccrroollllIInnccrreemmeenntt Database Class: SSccrroollllIInnccrreemmeenntt Specifies an increment for vertical scrolling, in any of the usual forms permitted for screen distances. If the value of

this option is greater than zero, the vertical view in the win-

dow will be constrained so that the y coordinate at the top edge

of the window is always an even multiple of -yyssccrroolllliinnccrreemmeenntt;

furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will

also be -yyssccrroolllliinnccrreemmeenntt. If the value of this option is less

than or equal to zero, then vertical scrolling is unconstrained. WWIIDDGGEETT CCOOMMMMAANNDD The ttrreeeeccttrrll command creates a new Tcl command whose name is the same

as the path name of the treectrl's window. This command may be used to

invoke various operations on the widget. It has the following general form: pathName option ?arg arg ...?

PathName is the name of the command, which is the same as the treectrl

widget's path name. Option and the args determine the exact behavior

of the command. The following commands are possible for treectrl wid-

gets: pathName aaccttiivvaattee itemDesc Sets the active item to the one described by itemDesc, and switches on the state aaccttiivvee for this item. From now on the item can be retrieved with the item description aaccttiivvee. An <> event is generated. pathName ccaannvvaassxx screenx

Given a window x-coordinate in the treectrl screenx, this com-

mand returns the treectrl x-coordinate that is displayed at that

location. pathName ccaannvvaassyy screeny

Given a window y-coordinate in the treectrl screeny, this com-

mand returns the treectrl y-coordinate that is displayed at that

location. pathName ccggeett option Returns the current value of the configuration option given by option. Option may have any of the values accepted by the ttrreeee command.

pathName ccoollllaappssee ?-rreeccuurrssee? ?itemDesc ...?

Switches off the ooppeenn state of the item(s) described by

itemDesc. If the item has descendants, they are no longer dis-

played. If the item is configured to have a button, the button will now display the image or bitmap configured with the widget

options -cclloosseeddbbuuttttoonniimmaaggee or -cclloosseeddbbuuttttoonnbbiittmmaapp, or a ++ sign

if no image or bitmap is configured. If the item is already closed, this command has no effect. ItemDesc may also be the

string aallll, in which case all items of the treectrl widget are

collapsed. If -rreeccuurrssee is specified, all descendants of

itemDesc will also be collapsed. For every item, that actually

will be collapsed, two events are generated: a <>

event before the item state is changed, and a <>

event after the item state was changed. pathName ccoolluummnn option column ?arg ...?

This command is used to manipulate the columns of the treectrl

widget (see section CCOOLLUUMMNNSS below). The exact behavior of the command depends on the option argument that follows the ccoolluummnn argument. The following forms of the command are supported: pathName ccoolluummnn bbbbooxx column Returns a list with four elements giving an approximate bounding box for the column header specified by column.

If the treectrl is configured to don't display the column

headers by means of the -sshhoowwhheeaaddeerr option, an empty list

is returned instead. pathName ccoolluummnn ccggeett column option This command returns the current value of the option named option for the column specified by column, Column may also be the string ttaaiill to specify the tail column. Option may have any of the values accepted by the ccoolluummnn ccoonnffiigguurree widget command. pathName ccoolluummnn ccoonnffiigguurree column ?option? ?value? ?option value ...? This command is similar to the ccoonnffiigguurree widget command

except that it modifies options associated with the col-

umn specified by column instead of modifying options for

the overall treectrl widget. Column may also be the

string ttaaiill to specify the tail column. If no option is specified, the command returns a list describing all of the available options for column (see TTkkCCoonnffiigguurreeIInnffoo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more

option-value pairs are specified, then the command modi-

fies the given option(s) to have the given value(s) for column; in this case the command returns an empty string. The specified column is created, if it not already exists

and if at least one option-value pair is specified. See

CCOOLLUUMMNNSS below for details on the options available for columns. pathName ccoolluummnn ddeelleettee column

Deletes the specified column from the treectrl widget.

All remaining columns of the treectrl widget will get new

column numbers: in an unchanged order, but with succesive numbers. pathName ccoolluummnn iinnddeexx column This command returns a decimal string giving the column number of the column specified by column, which may also be the string ttaaiill to specify the tail column. pathName ccoolluummnn mmoovvee column before Moves the specified column to the left of the column specified by before. If before is the string ttaaiill, the column column will become the last column. pathName ccoolluummnn nneeeeddeeddwwiiddtthh column This command returns a decimal string giving the needed width of the column specified by column. The needed width is the maximum of the width of the column header and the width of the widest currently visible item. pathName ccoolluummnn wwiiddtthh column This command returns a decimal string giving the width of

the column specified by column, even if the treectrl is

configured to don't display the column headers by means

of the -sshhoowwhheeaaddeerr option.

pathName ccoommppaarree itemDesc1 op itemDesc2 From both items described by the itemDescs the index is retrieved (as returned from the iitteemm iinnddeexx widget command). Then these indexes are compared using the operator op, which must be either <<, <<==, ====, >>==, >>, or !!==. The return value of

this command is 1 if the comparison evaulated to true, 0 other-

wise. pathName ccoonnffiigguurree ?option? ?value option value ...? Query or modify the configuration options of the widget. If no

option is specified, returns a list describing all of the avail-

able options for pathName (see TTkkCCoonnffiigguurreeIInnffoo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or

more option-value pairs are specified, then the command modifies

the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the ttrreeeeccttrrll command. pathName ccoonntteennttbbooxx Returns a list with four elements giving an approximate bounding box for the space used to display the items inside the columns,

i.e. the space of the treectrl widget without the surrounding

borders and the column headers. pathName ddeebbuugg option ?arg arg ...?

This command is used to facilitate debugging of the treectrl

widget. The exact behavior of the command depends on the option argument that follows the ddeebbuugg argument. The following forms of the command are supported: pathName ddeebbuugg ccggeett element option This command returns the current value of the debugging option named option. Option may have any of the values accepted by the ddeebbuugg ccoonnffiigguurree widget command. pathName ddeebbuugg ccoonnffiigguurree element ?option? ?value? ?option value ...? This command is similar to the ccoonnffiigguurree widget command

except that it modifies debugging options instead of mod-

ifying options for the overall treectrl widget. If no

option is specified, the command returns a list describ-

ing all of the available debugging options (see TTkkCCoonn-

ffiigguurreeIInnffoo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or

more option-value pairs are specified, then the command

modifies the given debugging option(s) to have the given value(s); in this case the command returns an empty string. The following debugging options are supported:

-ddiissppllaayyddeellaayy millis

Specifies a time duration in milliseconds, which should be waited after something has been drawn to the screen. Setting this option has only an

effect, if the debugging options -eennaabbllee and -ddiiss-

ppllaayy are switched on.

-ddaattaa boolean

If this option is switched on (together with the

debugging option -eennaabbllee), at various places a

consistence check on the internal data structure is made (e.g. for every item is checked, if the

registered number of children is equal to the num-

ber of child items). If an inconsistency was found, a Tcl background error is raised.

-ddiissppllaayy boolean

If this option is switched on (together with the

debugging option -eennaabbllee), at varios places addi-

tional debugging output is printed to stdout.

-eennaabbllee boolean

All other debugging options only take effect, if this option is also switched on.

-eerraasseeccoolloorr color

Use this color, when parts of the treectrl widget

should be deleted. If you use an unusual color for this option (like ppiinnkk), superflous screen redraws can be spotted more easily. Setting this option has only an effect, if the debugging

options -eennaabbllee and -ddiissppllaayy are switched on.

pathName ddeebbuugg ddiinnffoo

For every of the treectrl widget a line with some inter-

nal valuess info about all items is printed to stdout. The command returns the empty string. pathName ddeebbuugg ssccrroollll Returns a string useful for debugging vertical scrolling. pathName ddeepptthh ?itemDesc?

If the additional argument itemDesc is specified, returns a dec-

imal string giving the depth of the item describing by itemDesc, whereas depth is defined as the number of steps you must go upward to reach to root item. If no itemDesc is specified, the

maximum depth of all items in the treectrl widget is returned

instead. pathName ddrraaggiimmaaggee option ?arg ...? This command is used to manipulate the dragimage, one or more

dotted lines around rectangular regions of the treectrl widget.

The exact behavior of the command depends on the option argument that follows the ddrraaggiimmaaggee argument. The following forms of the command are supported: pathName ddrraaggiimmaaggee aadddd itemDesc ?column? ?element? Adds the shapes of the item described by itemDesc to the shapes of the dragimage. Specifying additional arguments reduces the number of rectangles that are added to the dragimage. If no additional arguments is specified, for

every element of the item in every column a dotted rec-

tangles is added. If column is specified, all elements

in other columns are ignored. If also element is speci-

fied, only a rectangle for this one element of the speci-

fied item in the given column is added. pathName ddrraaggiimmaaggee ccggeett option This command returns the current value of the dragimage option named option. Option may have any of the values accepted by the ddrraaggiimmaaggee ccoonnffiigguurree widget command. pathName ddrraaggiimmaaggee cclleeaarr Removes all shapes (if there are any) from the dragimage. This command does not modify the dragimage offset. pathName ddrraaggiimmaaggee ccoonnffiigguurree ?option? ?value? ?option value ...? This command is similar to the ccoonnffiigguurree widget command except that it modifies the dragimage options instead of

modifying options for the overall treectrl widget. If no

option is specified, the command returns a list describ-

ing all of the available dragimage options (see TTkkCCoonn-

ffiigguurreeIInnffoo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named dragimage option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one

or more option-value pairs are specified, then the com-

mand modifies the given dragimage option(s) to have the given value(s); in this case the command returns an empty string. The following dragimage options are supported:

-vviissiibbllee boolean

Specifies a boolean value which determines whether the dragimage should currently be visible. This option should not be modified by means of the ddrraaggiimmaaggee ccoonnffiigguurree widget command; instead use the ddrraaggiimmaaggee vviissiibbllee widget command. pathName ddrraaggiimmaaggee ooffffsseett ?x y? Returns a list containing the x and y offsets of the dragimage, if no additional arguments are specified. The dragimage offset is the screen distance, the image is displayed relative to the item its shape is derived from.

If two coordinates are specified, sets the dragimage off-

set to the given coordinates x and y. pathName ddrraaggiimmaaggee vviissiibbllee ?boolean? If the additional argument specifies true, the dotted

lines will become visible and the dragimage option -vviissii-

bbllee becomes 1; if it specifies false, the dotted lines

will be hidden and the dragimage option -vviissiibbllee becomes

0. Returns 1 if the dragimage is currently visible, 0 otherwise. pathName eelleemmeenntt option ?element? ?arg arg ...? This command is used to manipulate elements (see EELLEEMMEENNTTSS below). The exact behavior of the command depends on the option argument that follows the eelleemmeenntt argument. The following forms of the command are supported: pathName eelleemmeenntt ccggeett element option This command returns the current value of the option

named option associated with the element given by ele-

ment. Option may have any of the values accepted by the eelleemmeenntt ccoonnffiigguurree widget command. pathName eelleemmeenntt ccoonnffiigguurree element ?option? ?value? ?option value ...? This command is similar to the ccoonnffiigguurree widget command

except that it modifies options associated with the ele-

ment given by element instead of modifying options for

the overall treectrl widget. If no option is specified,

the command returns a list describing all of the avail-

able options for element (see TTkkCCoonnffiigguurreeIInnffoo for infor-

mation on the format of this list). If option is speci-

fied with no value, then the command returns a list

describing the one named option (this list will be iden-

tical to the corresponding sublist of the value returned

if no option is specified). If one or more option-value

pairs are specified, then the command modifies the given option(s) to have the given value(s) in element; in this case the command returns an empty string. See EELLEEMMEENNTTSS below for details on the options available for elements. pathName eelleemmeenntt ccrreeaattee element type ?option value ...? Create a new elememt in pathName of type type with name element. The exact format of the arguments after type depends on type, but generally consist of specifications for zero or more element options. See the subsections on individual element types below for more on the syntax of this command. This command returns the name for the new element. pathName eelleemmeenntt ddeelleettee ?element ...? Deletes each of the named elements and returns an empty

string. If an element is deleted while it is still con-

figured as an element of one or more styles by means of the ssttyyllee eelleemmeennttss widget command, it is also removed from the element lists of these styles. pathName eelleemmeenntt nnaammeess

Returns a list containing the names of all existing ele-

ments. pathName eelleemmeenntt ttyyppee element Returns the type of the elements given by element, such as rreecctt or tteexxtt.

pathName eexxppaanndd ?-rreeccuurrssee? ?itemDesc ...?

Switches on the ooppeenn state of the item(s) described by itemDesc. If the item has descendants, they are now displayed. If the item is configured to have a button, the button will now display

the image or bitmap configured with the widget options -ooppeennbbuutt-

ttoonniimmaaggee or -ooppeennbbuuttttoonnbbiittmmaapp, or a - sign if no image or bitmap

is configured. If the item is already open, this command has no effect. ItemDesc may also be the string aallll, in which case all

items of the treectrl widget are expanded. If -rreeccuurrssee is spec-

ified, all descendants of itemDesc will also be expanded. For

every item, that actually will be expanded, two events are gen-

erated: an <> event before the item state is

changed, and an <> event after the item state was

changed. pathName iiddeennttiiffyy x y

Returns a list containing some diagnostics about what is dis-

played at the given windows coordinates xx and yy. The resulting

list may be empty, if nothing is displayed at the given coordi-

nates, otherwise the first list element is hheeaaddeerr or iitteemm. If the coordinates are in the header area and thus the first element of the result is hheeaaddeerr, the number of the column or the string ttaaiill is the second element in the resulting list; if the x coordinate is near the left or right end of the header, a third element lleefftt or rriigghhtt is added respectively. If the coordinates are below the header area and thus the first element of the result is iitteemm, the numerical id of the item is the second element in the resulting list. If the x coordinate

doesn't fall into the column displaying the hierarchical struc-

ture, the elements ccoolluummnn and the column number are added. If the x coordinate if above the column displaying the hierarchical structure, the following elements are added to the resulting list: lliinnee and the numerical id of the item the line comes from, if the x coordinate is above an item connecting line; bbuuttttoonn, if the x coordinate is above a button; ccoolluummnn, the column number,

eelleemm, and the element name, if the x coordinate is above an ele-

ment of the item; ccoolluummnn and the column number, if the x coordi-

nate is to the right of the elements; nothing otherwise. pathName iinnddeexx itemDesc This command returns a decimal string giving the numerical id of

h ie seiid y tmec se ITEM DESCRIPTION eo)

pathName iitteemm option ?arg ...? This command is used to manipulate items. The exact behavior of the command depends on the option argument that follows the iitteemm argument. The following forms of the command are supported: pathName iitteemm aanncceessttoorrss itemDesc Returns a list containing the numerical indexes of all

ancestors of the item specified by itemDesc from its par-

ent upto the root item. pathName iitteemm bbbbooxx itemDesc ?column? ?element? Returns a list with four elements giving an approximate bounding box for the item described by itemDesc. If no further argument is specified, the bbox spans the area of the item over all columns. If a column is specified, only the area of the item in this column is considered, if an additional element is specified, the area of this element in column of the specified item is returned. pathName iitteemm cchhiillddrreenn itemDesc Returns a list containing the numerical indexes of all children of the item specified by itemDesc in the correct order from the first child to the last child. pathName iitteemm ccoommpplleexx itemDesc list ... Modifies the elements of the item described by itemDesc.

For every column of the treectrl there may be specified

one list, which in turn is an odd elemented list with at least three elements: the name of an element followed by

option-value pairs. Every option must be known by the

element's type (see EELLEEMMEENNTTSS below). The corresponding value will overwrite the value of the element for this one column in this item. pathName iitteemm ccrreeaattee Creates a new item and returns its numerical indexes. The new item has set the states ooppeenn and eennaabblleedd. If the

treectrl widget has currently the focus, also the state

ffooccuuss is set. pathName iitteemm ddeelleettee first ?last? Deletes the specified item(s). First must be the string

aallll or an itemDesc, last must be an itemDesc if speci-

fied. If first is specified as aallll, all items are deleted; if first is specified as itemDesc and last isn't specified, the item described by first is delete. If both first and last are specified, the must decribe items with the same root item; then the range of items between first and last is deleted. There is no way to delete the

root item of the treectrl widget; in all cases the speci-

fication of the root item is ignored; pathName iitteemm dduummpp itemDesc Returns a list with six elements in the form iinnddeexx index iinnddeexxVViiss indexVis nneeeeddeeddHHeeiigghhtt neededHeight. pathName iitteemm eelleemmeenntt command itemDesc column element ?arg ...? This command is used to manipulate elements of the item. The exact behavior of the command depends on the command

argument that follows the eelleemmeenntt argument. The follow-

ing forms of the command are supported: pathName iitteemm eelleemmeenntt aaccttuuaall itemDesc column element option This command returns the current value of the option named option associated with element inside column of the item described by itemDesc; if it was already configured for the actual item, the return value is the same as if the iitteemm eelleemmeenntt aaccttuuaall widget command was used; otherwise the option value of the underlynig element is returned. Option may have any of the values accepted by the type of the specified element (see EELLEEMMEENNTTSS below) pathName iitteemm eelleemmeenntt ccggeett itemDesc column element option This command returns the value of the option named option associated with element inside column of the item described by itemDesc, if it was already configured for the actual item. Option may have any of the values accepted by the type of the specified element (see EELLEEMMEENNTTSS below) pathName iitteemm eelleemmeenntt ccoonnffiigguurree itemDesc column element ?option? ?value? ?option value ...? This command is similar to the ccoonnffiigguurree widget command except that it modifies options associated with element inside column of the item described by itemDesc instead of modifying options for the

overall treectrl widget. If no option is speci-

fied, the command returns a list describing all of

the available options for the element (see TTkkCCoonn-

option is specified). If one or more option-value

pairs are specified, then the command modifies the given option(s) to have the given value(s) in the element inside column of the item described by itemDesc; in this case the command returns an empty string. pathName iitteemm ffiirrssttcchhiilldd parent ?child? If child is not specified, returns the numerical index of the first child of the item described by parent. If child is specified, it must described an item that is not an ancestor of parent. Then it will become the new first child of parent. pathName iitteemm hhaassbbuuttttoonn itemDesc ?boolean? If boolean is not specified, returns 1 if to the left of the item described by itemDesc a button should be drawn, 0 otherwise. If boolean is specified, it must be a valid boolean value specifying if a button should be displayed to the left of this item. pathName iitteemm iinnddeexx itemDesc Returns a list of two integers, which corresponds to the row of the item described by itemDesc, if all items above are counted and if only the displayed items are counted. This command should not be confused with the iinnddeexx widget command, which return the invariable item id. The index here is basically the row of the item. pathName iitteemm iissaanncceessttoorr itemDesc descendant Returns 1 if the item described by itemDesc is a direct or indirect parent of the item decribed by descendant, 0 otherwise. pathName iitteemm iissooppeenn itemDesc Returns 1, if the item described by itemDesc has cuurently the state ooppeenn switched on, 0 otherwise. pathName iitteemm llaassttcchhiilldd parent ?child? If child is not specified, returns the numerical index of the last child of the item described by parent. If child is specified, it must described an item that is not an ancestor of parent. Then it will become the new last child of parent. pathName iitteemm nneexxttssiibblliinngg sibling ?next? If next is not specified, returns the numerical index of the next sibling of the item described by sibling. If next is specified, it must described an item that is not an ancestor of sibling. Then it will become the new next sibling of sibling. pathName iitteemm nnuummcchhiillddrreenn itemDesc Returns the number of children of the item described by itemDesc. pathName iitteemm ppaarreenntt itemDesc Returns the numerical index of the parent of the item described by itemDesc. pathName iitteemm pprreevvssiibblliinngg sibling ?prev? If prev is not specified, returns the numerical index of the previous sibling of the item described by sibling. If prev is specified, it must described an item that is not an ancestor of sibling. Then it will become the new previous sibling of sibling. pathName iitteemm rreemmoovvee itemDesc Removes the item described by itemDesc from the children list of its father, so that it will become an orphan. pathName iitteemm rrnncc itemDesc Returns a list of two integers, which corresponds to the row and column of the item described by itemDesc. pathName iitteemm ssoorrtt itemDesc ?option ...? Sorts the children of the item described by itemDesc, and redisplays the tree with the items in the new order. The range of items which should be sorted can be

restricted by means of the -ffiirrsstt and/or -llaasstt options,

which should be children of the item described by itemDesc; the order between these two limiting items doesn't matter.

The sort column can be specified by means of the -ccoolluummnn

option; this option can be used repeatedly to define a multi column sort. The sorting is done by looking at the

text of the element specified by the -eelleemmeenntt option,

which must be a text element defined in the style of the sorting column, by default the first text element is used.

If the -nnoottrreeaallllyy option is specified, no rearranging of

the items is done; instead the sorted items are returned as result of the command. By default ASCII sorting is used with the result returned in increasing order. The order can be modified by means

of the -iinnccrreeaassiinngg (the default) or -ddeeccrreeaassiinngg flag.

Any of the following options may be specified to control the sorting process of the previously specified column (unique abbreviations are accepted):

-aasscciiii Use string comparison with ASCII collation order.

This is the default.

-ccoommmmaanndd command

Use command as a comparison command. To compare two items, evaluate a Tcl script consisting of command with the numerical ids of the two items appended as additional arguments. The script should return an integer less than, equal to, or

greater than zero if the first item is to be con-

sidered less than, equal to, or greater than the second, respectively.

-ddiiccttiioonnaarryy

Use dictionary-style comparison. This is the same

as -aasscciiii except (a) case is ignored except as a

tie-breaker and (b) if two strings contain embed-

ded numbers, the numbers compare as integers, not

characters. For example, in -ddiiccttiioonnaarryy mode,

bbiiggBBooyy sorts between bbiiggbbaanngg and bbiiggbbooyy, and xx1100yy sorts between xx99yy and xx1111yy.

-iinntteeggeerr

Convert to integers and use integer comparison.

-rreeaall Convert to floating-point values and use floating

comparison. pathName iitteemm ssttaattee ggeett itemDesc ?stateName ...? If no stateName is specified, returns a list containing the names of all (predefined and user defined) states which are currently switched on for the item described by itemDesc. If a stateName is specified, 1 is returned if the specified state is currently switched on for the item, 0 otherwise. pathName iitteemm ssttaattee sseett itemDesc ?lastItem? ?stateDescList? Every element of stateDescList must describe a user defined state (see SSTTAATTEESS below), with the particularity that the state name may have also a leading ~~. Every state with a leading !! will be switched off for the item described by itemDesc, every state with a leading ~~ will be toggled, and every state without leading !! or ~~ will be switched on. If lastItem is specified, the state changes will be made for all items in the range betwen itemDesc and lastItem. ItemDesc may be the string aallll, then the state changes are made for all items of the

treectrl widget.

pathName iitteemm ssttyyllee command itemDesc ?arg ...? This command is used to manipulate the style of the item. The exact behavior of the command depends on the command argument that follows the ssttyyllee argument. The following forms of the command are supported: pathName iitteemm ssttyyllee eelleemmeennttss itemDesc column A list is returned containing the currently defined elements of the style, which is set for the item described by itemDesc in column. pathName iitteemm ssttyyllee mmaapp itemDesc column style map

Map must be a list with an even number of ele-

ments, and each element must be the name of an

element created by the eelleemmeenntt ccrreeaattee widget com-

mand. Replaces elements in the style of the item

described by itemDesc in column based on the from-

to pairs in map. pathName iitteemm ssttyyllee sseett itemDesc ?column? ?style? ?column style ...?

If no column is specified, returns a list contain-

ing the names of the styles set for all columns of

the item described by itemDesc. If no style argu-

ment is specified, returns the name of the style set for the item described by itemDesc in column.

If there are one or more style arguments speci-

fied, it must be column-style pairs; then the

style(s) of item in column will be set to style. pathName iitteemm tteexxtt itemDesc column ?text? ?column text ...? If no text argument is specified, returns the text of the item described by itemDesc in column. If there are one

or more text arguments specified, it must be column-text

pairs; then the text(s) of item in column will be set to text. pathName iitteemm vviissiibbllee itemDesc ?boolean? If boolean is not specified, returns 1 if the item described by itemDesc is currently visible, 0 otherwise. If boolean is specified, it must be a valid boolean value specifying if the item should be visible. The visibility

of an item is independend from the state of its ances-

tors. So if the state of one of the ancestors is cur-

rently not opened, the item may be considered visible although it is not displayed on the screen. pathName mmaarrqquueeee option ?arg ...? This command is used to manipulate the marquee, a rectangular

region of the treectrl widget optionally marked with a surround-

ing dotted line. One corner point of the marquee is fixed as

long as the marquee is visible and called the anchor; the diago-

nally opposite corner is dragged with the mouse while resizing

the marquee and simply called the corner. All coordinates han-

dled by this widget command are treectrl coordinates, i.e. the

ccaannvvaassxx or ccaannvvaassyy widget command should be used before any win-

dow coordinates can be used. The exact behavior of the command

depends on the option argument that follows the mmaarrqquueeee argu-

ment. The following forms of the command are supported: pathName mmaarrqquueeee aanncchhoorr ?x y? Returns a list containing the x and y coordinates of the anchor, if no additional arguments are specified. If two coordinates are specified, sets the anchor to the given coordinates x and y. pathName mmaarrqquueeee ccggeett option This command returns the current value of the marquee option named option. Option may have any of the values accepted by the mmaarrqquueeee ccoonnffiigguurree widget command. pathName mmaarrqquueeee ccoonnffiigguurree ?option? ?value? ?option value ...? This command is similar to the ccoonnffiigguurree widget command except that it modifies the marquee options instead of

modifying options for the overall treectrl widget. If no

option is specified, the command returns a list describ-

ing all of the available marquee options (see TTkkCCoonnffiigg-

uurreeIInnffoo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named marquee option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one

or more option-value pairs are specified, then the com-

mand modifies the given marquee option(s) to have the given value(s); in this case the command returns an empty string. The following marquee options are supported:

-vviissiibbllee boolean

Specifies a boolean value which determines whether

the dotted line surrounding the region of the mar-

quee should currently be visible. This option should not be modified by means of the mmaarrqquueeee ccoonnffiigguurree widget command; instead use the mmaarrqquueeee vviissiibbllee widget command. pathName mmaarrqquueeee ccoooorrddss ?x1 y1 x2 y2? Returns a list containing the x and y coordinates of the anchor followed by the x and y coordinates of the corner,

if no additional arguments are specified. If four coor-

dinates are specified, sets the anchor to the given coor-

dinates x1 and y1 and the corner to the coordinates x2 and y2. pathName mmaarrqquueeee ccoorrnneerr ?x y? Returns a list containing the x and y coordinates of the corner, if no additional arguments are specified. If two coordinates are specified, sets the corner to the given coordinates x and y. pathName mmaarrqquueeee iiddeennttiiffyy Returns a list with information about the items inside the marquee. The list has as elements a list itself for every item which is displayed inside the marquee. The first element of these lists is the numerical item id, followed by another list with information about every column of the item inside the marque. These lists start with the column number, followed by the elements of the style defined for the item in this column if there are any. pathName mmaarrqquueeee vviissiibbllee ?boolean? If the additional argument specifies true, the dotted

line will become visible and the marquee option -vviissiibbllee

becomes 1; if it specifies false, the dotted line will be

hidden and the marquee option -vviissiibbllee becomes 0.

Returns 1 if the dotted line surrounding the marquee is currently visible, 0 otherwise. pathName nnoottiiffyy option ?arg ...? This command is used to manipulate the event mechanism of a

treectrl widget, which stands in parallel to Tk's event mecha-

nism. It has two major advantages: arbitrary new events can be defined together with arbitrary details, and before the event is triggered the called Tcl command underlys a customizable percent substitution. The exact behavior of the command depends on the option argument that follows the nnoottiiffyy argument. The following forms of the command are supported: pathName nnoottiiffyy bbiinndd ?object? ?pattern? ?script? This command associates script with the object given by object such that whenever the event sequence given by pattern occurs for the object the command will be

invoked. This widget command is similar to the bbiinndd com-

mand except that it operates on any object in a treectl rather than entire widgets, and it works also for non X11 event pattern. If all arguments are specified then a new binding is created, replacing any existing binding for the same pattern and object (if the first character of script is ++ then script augments an existing binding rather than replacing it). In this case the return value

is an empty string. If script is omitted then the com-

mand returns the script associated with object and pat-

tern (an error occurs if there is no such binding). If both script and pattern are omitted then the command returns a list of all the sequences for which bindings have been defined for object. If no optional argument is

specified, a list of all objects to which a pattern-

script combination is bound yet, is returned. pathName nnoottiiffyy ccoonnffiigguurree window pattern ?option? ?value? ?option value ...? This command is similar to the ccoonnffiigguurree widget command except that it modifies event options defined for pattern in window instead of modifying options for the overall

treectrl widget. If no option is specified, the command

returns a list with option-value pairs describing all the

available event options for pattern in window. If option

is specified with no value, then the command does noth-

ing. If one or more option-value pairs are specified,

then the command modifies the given option(s) to have the given value(s) for the layout; in this case the command returns an empty string. The following event options are supported:

-aaccttiivvee boolean

Specifies if the event should be active. As long as this option is specified as false, the event will not trigger. pathName nnoottiiffyy ddeettaaiillnnaammeess eventName Returns a list containing the names of all details, which are installed for the event with the name eventName by means of the nnoottiiffyy iinnssttaallll ddeettaaiill widget command or by

the treectrl widget itself.

pathName nnoottiiffyy eevveennttnnaammeess Returns a list containing the names of all events, which are installed by means of the nnoottiiffyy iinnssttaallll eevveenntt widget

command or by the treectrl widget itself.

pathName nnoottiiffyy ggeenneerraattee pattern ?charMap? The event with the pattern pattern is generated, if it is configured as active. If there are details defined for

the event, pattern must describe an eventName-detail

pair, otherwise pattern should be a simple event name.

The optional charMap is a list of key-value pairs as in

the form returned by aarrrraayy ggeett; each key has to be exactly one character. If this argument is specified, the following substitution will be done in the script registered for the generated event before it will be

evaluated: every occurence of a percent character (%%)

followed by a key will be replaced with its corresponding value.

pathName nnoottiiffyy iinnssttaallll ddeettaaiill eventName detail ?percentsCom-

mand? Installs a new detail detail for the event with the name eventName. A detail create by this command is called

dynamic, whereas details created by the treectrl widget

itself are called static. The optional percentsCommand will be called before the event is triggered for every two character sequence

starting with a percent character (%%). The script is

called with at least four additional arguments: the sec-

ond character of the sequence, the window for which the event is triggered, eventName and detail, and finally the

field-value pairs specified as arguments in the nnoottiiffyy

ggeenneerraattee call to generate the event (the leading dash is dropped from the fields). The two character sequence of the command will be replaced by the returning string, or

by an empty string if the command returns with a return-

Code other than 0. pathName nnoottiiffyy iinnssttaallll eevveenntt eventName ?percentsCommand? Installs a new event with the name eventName. An event create by this command is called dynamic, whereas events

created by the treectrl widget itself are called static.

For the optional percentsCommand argument see the description of the nnoottiiffyy iinnssttaallll ddeettaaiill widget command above; the value for the argument detail is the empty string. pathName nnoottiiffyy lliinnkkaaggee eventName ?detail? Returns a string indicating whether the specified event

or detail is created by means of the nnoottiiffyy iinnssttaallll wid-

get command (ddyynnaammiicc) or by the treectrl widget itself

(ssttaattiicc). pathName nnoottiiffyy uunniinnssttaallll ddeettaaiill eventName detail If the specified detail detail of the event with the name

eventName is static (i.e. created by the treectrl widget

itself), an error is generated. Otherwise the dynamic detail is removed from the event. pathName nnoottiiffyy uunniinnssttaallll eevveenntt eventName If the specified event with the name eventName is static

(i.e. created by the treectrl widget itself), an error is

generated. Otherwise the dynamic event is removed. pathName nnuummccoolluummnnss Returns a decimal string giving the number of columns configured

in the treectrl widget. Since the always existant tail column

is ignored by this command, the number can be 0 if no column is configured yet. pathName nnuummiitteemmss Returns a decimal string giving the number of items created in

the treectrl widget. This number is always positive, since a

newly created treectrl widget has already the root item, which

cannot be deleted. pathName oorrpphhaannss Returns a list containing the numerical ids of all items which has no parent item. An item is created without having a parent, and can later become an orphan again by means of the iitteemm rreemmoovvee widget command. pathName rraannggee first last First and last must be an itemDesc. Returns a list containing the numerical ids of all items in the range between first and

last, inclusive. The order between first and last doesn't mat-

ter, and the result is always ordered by the increasing index of the items. pathName ssttaattee option ?stateName? This command is used to manipulate the list of user defined states, see section SSTTAATTEESS below. The exact behavior of the command depends on the option argument that follows the ssttaattee argument. The following forms of the command are supported: pathName ssttaattee ddeeffiinnee stateName Defines a new state with the name stateName, which must not be the name of a predefined or already user defined state. pathName ssttaattee lliinnkkaaggee stateName Returns a string indicating whether the specified state

is user defined by means of the ssttaattee ddeeffiinnee widget com-

mand (ddyynnaammiicc) or predefined by the treectrl widget

itself (ssttaattiicc). pathName ssttaattee nnaammeess Returns a list containing the names of all user defined states. pathName ssttaattee uunnddeeffiinnee ?stateName ...? Every stateName must be the name of a user defined state. Removes this state from the list of user defined states. pathName sseeee itemDesc

Adjust the view in the treectrl so that the item described by

itemDesc is visible. If the item is already visible then the

command has no effect; otherwise the treectrl scrolls to bring

the item into view, and the corresponding <> and/or

<> events are generated.

pathName sseelleeccttiioonn option arg

This command is used to adjust the selection within a treectrl.

It has several forms, depending on option: pathName sseelleeccttiioonn aadddd first ?last? First and last (if specified) must be the string aallll or an itemDesc. Selects all of the items in the range between first and last, inclusive, without affecting the selection state of items outside that range. If one of

the arguments is the string aallll, all items of the treec-

trl widget are added to the selection instead. A < ttiioonn>> event is generated. pathName sseelleeccttiioonn aanncchhoorr ?itemDesc? If itemDesc is specified, the selection anchor is set to the described item. The selection anchor is the end of

the selection that is fixed while dragging out a selec-

tion with the mouse. The item description aanncchhoorr may be used to refer to the anchor item. This command doesn't modify the selection state of any item. Returns the numerical id of the selection anchor item. pathName sseelleeccttiioonn cclleeaarr ?first? ?last? First and last (if specified) must be the string aallll or an itemDesc. If any of the items between first and last (inclusive) are selected, they are deselected. The selection state is not changed for items outside this range. If no additional arguments is given or one of the arguments is the string aallll, the selection is completely cleared instead. A <> event is generated. pathName sseelleeccttiioonn ccoouunntt Returns an integer indicating the number of items in the

treectrl that are currently selected.

pathName sseelleeccttiioonn ggeett Returns a list containing the numerical ids of all of the

items in the treectrl that are currently selected. If

there are no items selected in the treectrl then an empty

string is returned. pathName sseelleeccttiioonn iinncclluuddeess itemDesc Returns 1 if the item indicated by itemDesc is currently selected, 0 if it isn't. pathName sseelleeccttiioonn mmooddiiffyy select deselect Both arguments select and deselect must be the string aallll or a possibly empty list of itemDescs. Selects all of the items described by select, then deselects all items described by deselect, without affecting the selection state of any item not mentioned in both arguments. If

one item is described in both arguments select and dese-

lect, it is added to the selection. A <> event is generated. pathName ssttyyllee option ?element? ?arg arg ...?

This command is used to manipulate styles, which could be con-

sidered as a geometry manager for the elements of one item. The exact behavior of the command depends on the option argument that follows the ssttyyllee argument. The following forms of the command are supported: pathName ssttyyllee ccggeett style option This command returns the current value of the option named option associated with the style given by style. Option may have any of the values accepted by the ssttyyllee ccoonnffiigguurree widget command. pathName ssttyyllee ccoonnffiigguurree style ?option? ?value? ?option value ...? This command is similar to the ccoonnffiigguurree widget command except that it modifies options associated with the style

given by style instead of modifying options for the over-

all treectrl widget. If no option is specified, the com-

mand returns a list describing all of the available options for style (see TTkkCCoonnffiigguurreeIInnffoo for information on the format of this list). If option is specified with no value, then the command returns a list describing the

one named option (this list will be identical to the cor-

responding sublist of the value returned if no option is

specified). If one or more option-value pairs are speci-

fied, then the command modifies the given option(s) to

have the given value(s) in style; in this case the com-

mand returns an empty string.

The options of a style have effect on all elements man-

aged by the style. The following options are supported:

-oorriieenntt varName

This option specifies which orientation should be used when laying out the elements associated with this style. Must be either hhoorriizzoonnttaall (the default) or vveerrttiiccaall or an abbreviation of one of these. pathName ssttyyllee ccrreeaattee style ?option value ...? Create a new style in pathName with name style. After

style there may be any number of option-value pairs, each

of which sets one of the configuration options for the

style. These same option-value pairs may be used in

ssttyyllee ccoonnffiigguurree widget commands to change the styles's configuration. Returns the name of the new style. pathName ssttyyllee ddeelleettee ?style ...? Deletes each of the named styles and returns an empty string. If a style is deleted while it is still used to display one or more items, it is also removed from the style list of these items. pathName ssttyyllee eelleemmeennttss style ?elementList? Specifies the elements which should be layed out by this style. Each element of elementList must be the name of an element created by the widget command eelleemmeenntt ccrreeaattee. Duplicate names in elementList are ignored. An element which was specified in a former call of this command for style but is not included in elementList, will be deleted from the elements layed out by style. If the elementList argument is not specified, a list is returned containing the currently defined elements of style. pathName ssttyyllee llaayyoouutt style element ?option? ?value? ?option value ...? This command is similar to the ccoonnffiigguurree widget command except that it modifies options used by style for laying out element instead of modifying options for the overall

treectrl widget. If no option is specified, the command

returns a list with option-value pairs describing all of

the available options for the layout. If option is spec-

ified with no value, then the command returns the value

of the named option. If one or more option-value pairs

are specified, then the command modifies the given option(s) to have the given value(s) for the layout; in this case the command returns an empty string. The options of a layout have effect on exactly the one element element managed by style. The following options are supported:

-ppaaddxx amount

-ppaaddyy amount

Amount specifies how much external padding to

leave on the left and right (for -ppaaddxx) or top and

bottom (for -ppaaddyy) side of the element. Amount

may be a list of two values to specify padding for the two sides separately, it defaults to 0.

-iippaaddxx amount

-iippaaddyy amount

Amount specifies how much internal padding to

leave on the left and right (for -iippaaddxx) or top

and bottom (for -iippaaddyy) side of the element.

Amount may be a list of two values to specify pad-

ding for the two sides separately, it defaults to 0.

-eexxppaanndd style

-iieexxppaanndd style

It can happen that the element's space is larger than its requested dimensions. These options may be used to position (or stretch) the slave within its cell. Style is a string that contains zero or more of the characters nn, ss, ee or ww. The string can contain other characters, but they are ignored. Each letter refers to a side (north,

south, east, or west) in which direction the ele-

ment will grow to.

-ssqquueeeezzee style

If an elements's area is smaller than its requested dimensions, this option may be used to allow shrinking of the element. Style is a

string that contains zero or more of the charac-

ters xx or yy. The string can contain other charac-

ters, but they are ignored. xx shrinks the element horizontally, yy shrinks it vertically.

-uunniioonn elementList

Specifies a list of other elements, which should be layed out inside the space of this element.

-ddeettaacchh boolean

Specifies whether the element should be positioned by themselves, i.e. independent from the other elements. pathName ssttyyllee nnaammeess Returns a list containing the names of all existing styles.

pathName ttooggggllee ?-rreeccuurrssee? ?itemDesc ...?

Changes the ooppeenn state of the item(s) described by itemDesc. If the state is currently switched off, this command does the same as the eexxppaanndd widget command, otherwise the same as the ccoollllaappssee widget command. ItemDesc may also be the string aallll, in which

case the state of all items of the treectrl widget are toggled.

If -rreeccuurrssee is specified, the state of all descendants of

itemDesc will also be toggles. pathName xxvviieeww ?args? This command is used to query and change the horizontal position

of the information displayed in the treectrl's window. It can

take any of the following forms: pathName xxvviieeww Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For

example, if the first element is .2 and the second ele-

ment is .6, 20% of the tree's area is off-screen to the

left, the middle 40% is visible in the window, and 40% of

the tree is off-screen to the right. These are the same

values passed to scrollbars via the -xxssccrroollllccoommmmaanndd

option. pathName xxvviieeww mmoovveettoo fraction Adjusts the view in the window so that fraction of the

total width of the tree is off-screen to the left. Frac-

tion must be a fraction between 0 and 1. A <>

event is generated. pathName xxvviieeww ssccrroollll number what This command shifts the view in the window left or right according to number and what. Number must be an integer. What must be either uunniittss or ppaaggeess or an abbreviation of one of these. If what is uunniittss, the view adjusts left or

right in units of the -xxssccrroolllliinnccrreemmeenntt option, if it is

greater than zero, or in units of one-tenth the window's

width otherwise. If what is ppaaggeess then the view adjusts

in units of nine-tenths the window's width. If number is

negative then information farther to the left becomes visible; if it is positive then information farther to

the right becomes visible. A <> event is gener-

ated. pathName yyvviieeww ?args? This command is used to query and change the vertical position

of the information displayed in the treectrl's window. It can

take any of the following forms: pathName yyvviieeww Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the vertical span that is visible in the window. For

example, if the first element is .6 and the second ele-

ment is 1.0, the lowest 40% of the tree's area is visible

in the window. These are the same values passed to

scrollbars via the -yyssccrroollllccoommmmaanndd option.

pathName yyvviieeww mmoovveettoo fraction Adjusts the view in the window so that fraction of the

tree's area is off-screen to the top. Fraction is a

fraction between 0 and 1. A <> event is gener-

ated. pathName yyvviieeww ssccrroollll number what This command adjusts the view in the window up or down according to number and what. Number must be an integer. What must be either uunniittss or ppaaggeess. If what is uunniittss, the view adjusts up or down in units of the

-yyssccrroolllliinnccrreemmeenntt option, if it is greater than zero, or

in units of one-tenth the window's height otherwise. If

what is ppaaggeess then the view adjusts in units of nine-

tenths the window's height. If number is negative then higher information becomes visible; if it is positive

then lower information becomes visible. A <>

event is generated. CCOOLLUUMMNNSS

A treectrl widget is capable of displaying multiple columns next to

each other. An item can be considered as a row, which reaches over all columns.

Many of the widget commands for a treectrl take as one argument an

indicator of which column of the treectrl to operate on. These indica-

tors are called columns and may be specified as numerical index as given by the first ccoolluummnn ccoonnffiigguurree widget command which created the

column or by its name, which can be configured my means of the -ttaagg

column option. There is always one special column, the tail column, which fills all space to the right of the last ordinary column. This column has no

number; it can only be specified by its tag ttaaiill, which cannot be modi-

fied. It is explicitely mentioned for a widget command, if its column argument can also specify the tail column. The following options are supported for columns:

-aarrrrooww direction

Indicates whether or not an arrow should be drawn in the column header to the right of the column title. Direction must have one of the values nnoonnee (the default), uupp, or ddoowwnn.

-aarrrroowwssiiddee side

Indicates on which side an arrow should be drawn, if at all. Side must be either lleefftt or rriigghhtt (the default).

-aarrrroowwggrraavviittyy side

Indicates onto which side an arrow should be packed, if there is more space available for drawing the arrow then needed. Side must be either lleefftt (the default) or rriigghhtt.

-aarrrroowwppaadd amount

Amount specifies how much padding to leave on the left and right

side of the arrow. Amount may be a list of two values to spec-

ify padding for left and right separately, it defaults to 0.

-bbiittmmaapp bitmap

Specifies the bitmap to display in the element to the left of the column title.

-bbaacckkggrroouunndd color

Specifies the color to use for the background of the column header.

-bboorrddeerrwwiiddtthh size

Specifies a non-negative value indicating the width of the 3-D

border to draw around the outside of the column header (if such

a border is being drawn; the -rreelliieeff column option determines

this). The value may have any of the forms acceptable to TTkkGGeettPPiixxeellss.

-bbuuttttoonn boolean

Indicates whether or not a mouse click on the column header should change the sorting order of the tree.

-eexxppaanndd boolean

Indicates whether or not any extra spaces should be distributed to this column. This option will actually only work, if the

column has no fix width defined by means of the -wwiiddtthh column

option.

-ffoonntt fontName

Specifies the font to use for the column title inside the column header.

-iimmaaggee image

Specifies the image to display in the element to the left of the

column title. This option overrides the -bbiittmmaapp column option.

-iimmaaggeeppaaddxx amount

-iimmaaggeeppaaddyy amount

Amount specifies how much padding to leave on the left and right

(for -iimmaaggeeppaaddxx) or top and bottom (for -iimmaaggeeppaaddyy) side of the

image. Amount may be a list of two values to specify padding for the two sides separately, it defaults to 0.

-iitteemmbbaacckkggrroouunndd colorList

Specifies a list of colors, which should be used as alternating background color for the items of this column. See also the

-bbaacckkggrroouunnddmmooddee widget option for more on this.

-jjuussttiiffyy justification

This option determines how the items (and the title) line up with each other. Must be one of lleefftt (the default), cceenntteerr, or rriigghhtt.

-mmiinnwwiiddtthh size

Specifies the minimum size, in screen units, that will be per-

mitted for this column.

-rreelliieeff relief

Specifies the 3-D effect desired for the column header contain-

ing the title. Acceptable values are the typical relief values,

but the value seems to be ignored anyway; better use the -ssuunnkkeenn

column option instead.

-sstteeppwwiiddtthh size

Specifies a sort of tabbed alignment for columns that displays

more than one item next to each other (typically in a treectrl

widget with horizontal orientation). Every item will get an x-

coordinate which is a multiple of size.

-ssuunnkkeenn boolean

Indicates whether or not the column header containing the column title will be displayed with a sunken relief.

-ttaagg tag

Defines a unique name for the columns which can be used in sub-

sequent calls of the treectrl widget commands, wherever a column

must be specified.

-tteexxtt text

Specifies a text to be displayed inside the column title.

-tteexxttccoolloorr color

Specifies a color, which should be used as foreground color to display the column title.

-tteexxttppaaddxx amount

-tteexxttppaaddyy amount

Amount specifies how much padding to leave on the left and right

(for -tteexxttppaaddxx) or top and bottom (for -tteexxttppaaddyy) side of the

text. Amount may be a list of two values to specify padding for the two sides separately, it defaults to 0.

-wwiiddtthh size

Specifies the width of the column.

-vviissiibbllee boolean

Indicates whether or not the column should be displayed.

-wwiiddtthhhhaacckk boolean

Indicates whether or not all items inside the column should have

the same width (typically in a treectrl widget with horizontal

orientation). SSTTAATTEESS A state consists basically of just a string: its stateName. For every item a set of these states is managed, which means that every item can

have every state switched on or off. The following states are prede-

fined for every item: aaccttiivvee At every time this state is set for exactly one item, which

therefore is called the active item. When the treectrl widget

is created or when the active item is deleted, the root item will become the active element. This state can be modified by means of the widget command aaccttiivvaattee. eennaabblleedd This state is set for every item, when it is created. It cannot be modified.

ffooccuuss This state is set for every item, if the treectrl widget has

currently the focus. It cannot be modified by means of a widget

command, but is maintained as reaction of a or sOut> event. ooppeenn If this state is switched on, the descendants of the item are

displayed - the item is expanded. If this state is switched

off, the descendants of the item are not displayed - the item is

collapsed. For a new item this state is switched on. It can be modified by means of the widget commands eexxppaanndd, ccoollllaappssee, or ttooggggllee. sseelleecctteedd This state is set for every item, which is included in the selection. It can be modified by means of the widget command sseelleeccttiioonn.

By means of the ssttaattee ddeeffiinnee widget command upto 27 additional state-

Names can be defined. Some widget commands expect a stateDesc argument, which is a stateName optionally preceded by an exclamation mark (!!). If the stateName has no leading !! it describes a currently switched on state, if it has a leading !! it describes a currently switched off state. Some widget commands expect a statePattern argument, which should be a

non empty list of stateDescs. The pattern matches, if for every ele-

ment of the list the stateDesc describes the same state as the item currently has. EELLEEMMEENNTTSS

Elements are the smallest building block which are handled by a treec-

trl widget. One or more elements together can be combined to a style, which can be considered as a blueprint for an item. They can also be used to create an item directly by means of the iitteemm ccoommpplleexx widget command. An element can be of type bbiittmmaapp, bboorrddeerr, iimmaaggee, rreecctt, or tteexxtt. For each element type there is a section below describing all options which can modify the behaviour of an element of this type. There are some options which can be configured to get different values dependent on the state of the item in which their element is included. The values of these options are basically a list. If the list has one element, the value is valid regardless of the item state. A list with

an even number of elements (value-statePattern pairs) specifies differ-

ent values for different states. For acceptable values of statePattern see the section SSTTAATTEESS above. The last statePattern can be empty,

implementing a sort of otherwise clause. The options with this behav-

iour are called per state options. BBIITTMMAAPP EELLEEMMEENNTT An element of type bbiittmmaapp can be used to display a bitmap in an item. The following options are supported for bitmap elements:

-bbaacckkggrroouunndd color

Specifies as a per state option the color to use for each of the bitmap's '0' valued pixels.

-bbiittmmaapp bitmap

Specifies as a per state option the bitmap to display in the element.

-ffoorreeggrroouunndd color

Specifies as a per state option the color to use for each of the bitmap's '1' valued pixels. BBOORRDDEERR EELLEEMMEENNTT An element of type bboorrddeerr can be used to add a border to an item. The following options are supported for border elements:

-bbaacckkggrroouunndd color

Specifies as a per state option the color to use for the back-

ground of the border.

-ffiilllleedd boolean

Specifies whether the interior of the border should also be filled with the specified background color. Default to false, which means that the background color of the tree is visible between the borders.

-hheeiigghhtt size

Specifies the height of the area of the border.

-rreelliieeff reliefList

Specifies as a per state option relief of the border. For

acceptable values see the description of the -rreelliieeff option in

the ooppttiioonnss manual page.

-tthhiicckknneessss thickness

Specifies the thickness of the border.

-wwiiddtthh size

Specifies the width of the area of the border. IIMMAAGGEE EELLEEMMEENNTT An element of type iimmaaggee can be used to display an image in an item. The following options are supported for image elements:

-hheeiigghhtt size

Specifies the height of the image.

-iimmaaggee image

Specifies as a per state option the image to display in the ele-

ment.

-wwiiddtthh size

Specifies the width of the image. RREECCTTAANNGGLLEE EELLEEMMEENNTT An element of type rreecctt can be used to display a rectangle in an item. The following options are supported for rectangle elements:

-ffiillll fillColor

Specifies as a per state option the color to be used to fill rectangle's area. Color may have any of the forms accepted by TTkkGGeettCCoolloorr. If color is an empty string (the default), then the rectangle will not be filled.

-hheeiigghhtt size

Specifies the height of the rectangle.

-ooppeenn open

This option may be used to get an incomplete drawing of the out-

line. Open is a string that contains zero or more of the char-

acters nn, ss, ee or ww. Each letter refers to a side (north, south, east, or west) that the outline will not be drawn. The default is , which causes the outline to be drawn completely.

-oouuttlliinnee outlineColor

Specifies as a per state option the color that should be used to draw the outline of the rectangle. Color may have any of the forms accepted by TTkkGGeettCCoolloorr. If color is specified as an empty string (the default), then no outline is drawn for the rectangle.

-oouuttlliinneewwiiddtthh outlineWidth

Specifies the width of the outline to be drawn around the rec-

tangle's region. outlineWidth may be in any of the forms

acceptable to TTkkGGeettPPiixxeellss. If the -oouuttlliinnee option has been

specified as an empty string (the default), then no outline is drawn.

-sshhoowwffooccuuss boolean

Specifies a boolean value indicating whether a "focus ring" should be drawn around the rectangle, if the item containing the

rectangle is the active item and the treectrl widget has cur-

rently the focus.

-wwiiddtthh size

Specifies the width of the rectangle. TTEEXXTT EELLEEMMEENNTT An element of type tteexxtt can be used to display a text in an item. The following options are supported for text elements:

-ddaattaa data

Specifies raw data to be printed as text.

-ddaattaattyyppee dataType

Specifies the datatype which should be used to convert the value

of the -ddaattaa option to the text to be printed. Acceptable values

are ddoouubbllee, iinntteeggeerr, lloonngg, ssttrriinngg, or ttiimmee.

-ffiillll color

Specifies as a per state option the color to be used as fore-

ground color of the text. Color may have any of the forms accepted by TTkkGGeettCCoolloorr. If color is an empty string (the

default), then the text will be displayed with the color speci-

fied as foreground color of the treectrl widget.

-ffoorrmmaatt format

This option overwrites the default format choosen by means of

the -ddaattaattyyppee option. For a datatype ttiimmee format should be a

valid format string for the cclloocckk command, for all other

datatypes it should be a valid format element of the ffoorrmmaatt com-

mand.

-ffoonntt fontName

Specifies as a per state option the font to use for the text. FontName may be any string acceptable to TTkkGGeettFFoonntt. If this option isn't specified, it defaults to the font configured for

the treectrl widget.

-jjuussttiiffyy how

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

-lliinneess lineCount

Specifies the maximal number of lines the text should be printed. If the doesn't fit into the area of lineCount lines with the configured width, it will be truncated at the right end and filled up with an ellipsis.

-tteexxtt string

String specifies the characters to be displayed in the text. Non printable characters are displayed in their escaped form (e.g. a new line character is displayed as the two characters

00ffRR)).. IIff tthhiiss ooppttiioonn iiss ssppeecciiffiieedd,, aannyy vvaalluueess ooff -ddaattaa,

-ddaattaattyyppee, and -ffoorrmmaatt are ignored. -wwiiddtthh size Specifies the

width of the area of the text.

-wwrraapp mode

Mode specifies how to handle lines that are wider than the text's area. Acceptable values are cchhaarr or wwoorrdd.

ITEM DESCRIPTION

Many of the widget commands for a treectrl take as one argument an

indicator of which item of the treectrl to operate on. These indica-

tors are called itemDescs and may be specified in any of the following forms: number Specifies the item numerically, where number should be the return value of a prior call of the iitteemm ccrreeaattee widget command, or 00 to specify the root item. aaccttiivvee Indicates the item that is currently active, i.e. normally the

item specified as argument of the last successful aaccttiivvaattee wid-

get command, or the root item if no such call happened yet. aanncchhoorr Indicates the anchor item of the selection, i.e. normally the item specified as argument of the last successful sseelleeccttiioonn aanncchhoorr widget command, or the root item if no such call happened yet. ffiirrsstt ?vviissiibbllee?

Indicates the first item of the treectrl, i.e. the root item.

If vviissiibbllee is specified and the widget is configured with -sshhooww-

rroooott nnoo, the first visible child of the root node is specified instead. llaasstt ?vviissiibbllee?

Indicates the last item of the treectrl. If vviissiibbllee is speci-

fied and the last item is currently not visible, i.e. one of its father nodes is collapsed, the last visible item is specified instead. nneeaarreesstt x y Indicates the item nearest to the point given by x and y. rrnncc row column

Indicates the item in the given row and column. You can memo-

rize rrnncc as abbreviation of "row 'n' column".

rroooott Indicates the root item of the treectrl.

The itemDesc may be followed by one or more modifiers. A modifier changes the item described by the itemDesc relative to the description upto this point. It may be specified in any of the following forms, all optionally followed by vviissiibbllee: aabboovvee Use the item one row above in this column. bbeellooww Use the item one row below in this column. bboottttoomm Use the item in the last row of this column. cchhiilldd n Use the nth child of the item. ffiirrssttcchhiilldd Use the first child of the item. llaassttcchhiilldd Use the last child of the item. lleefftt Use the item one column to the left in the same row. lleeffttmmoosstt Use the item of the first column in the same row. nneexxtt Use the next item, which is the first existant (or visible) item of the following list: the first child, the next sibling or the next sibling of the nearest parent which has one. nneexxttssiibblliinngg Use the next sibling of the item. ppaarreenntt Use the parent of the item. pprreevv Use the last child of the previous sibling, or the parent if there is no previos sibling. pprreevvssiibblliinngg Use the previous sibling of the item. rriigghhtt Use the item one column to the right in the same row. rriigghhttmmoosstt Use the item of the last column in the same row. ssiibblliinngg n Use the nth child of the item's parent. ttoopp Use the item in the first row of this column. EEVVEENNTTSS AANNDD SSCCRRIIPPTT SSUUBBSSTTIITTUUTTIIOONNSS Beside of all the normal Tk events, which are generated as reaction of

e.g. mouse movements or key presses, the treectrl widget generates at

various places events created by treectrl widget:

<> Generated without detail whenever the active item changes. <> Generated with the detail aafftteerr or bbeeffoorree, whenever an item is collapsed. <> Generated with the detail aafftteerr or bbeeffoorree, whenever an item is expanded. <> Generated with the detail xx or yy, whenever the origin of the window changes. <> Generated without detail whenever the selection changes.

By means of the nnoottiiffyy bbiinndd widget command Tcl scripts can be speci-

fied, which will be executed whenever the event triggers. The command will be executed in the same interpreter that the nnoottiiffyy bbiinndd command was executed in, and it will run at global level (only global variables

will be accessible). If the script contains any %% characters, then the

script will not be executed directly. Instead, a new script will be

generated by replacing each %%, and the character following it, with

information from the current event. The replacement depends on the

character following the %%, as defined in the list below. Unless other-

wise indicated, Some of the substitutions are only valid for certain types of events; if they are used for other types of events the value substituted is undefined.

%%%% Replaced with a single percent.

%%cc Replaced with the number of items that are currently selected

for a selection event, or with the numerical id of the item, which will become the active item for an activation event, invalid for other event types.

%%dd Replaced with the detail of the event, or with the empty string

if the event has no detail. Valid for all event types.

%%DD Replaced with a (possibly empty) list of item ids; all mentioned

items will be removed from the selection. Valid only for selec-

tion events.

%%ee Replaced with the name of the event. Valid for all event types.

%%II Replaced with the numerical id of the item, which is to be col-

lapsed or expanded. Valid only for collapse or expand events.

%%ll Replaced with the lower bound, i.e. the first fraction as

returned by the widget command xxvviieeww for horizontal scrolling or yyvviieeww for vertical scrolling. Valid only for scrolling events.

%%pp Replaced with the numerical id of the item, which was the

active item upto now. Valid only for activation events.

%%SS Replaced with a (possibly empty) list of item ids; all mentioned

items will be added to the selection. Valid only for selection events.

%%TT Replaced with the path name of the treectrl widget. Valid for

all event types.

%%uu Replaced with the upper bound, i.e. the second fraction returned

by the widget command xxvviieeww for horizontal scrolling or yyvviieeww for vertical scrolling. Valid only for scrolling events.

%%WW Replaced with the name of the object the event is bound for.

This can be a widget path (then the string starts with ..), or a generic tag. Valid for all event types. DDEEFFAAUULLTT BBIINNDDIINNGGSS

Tk automatically creates class bindings for treectrls that give them

the following default behavior. [1] Clicking mouse button 1 over an item positions the active cursor on the item, sets the input focus to this widget, and resets the selection of the widget to this item, if it is not already in the selection.

[2] Clicking mouse button 1 with the Control key down will reposi-

tion the active cursor and add the item to the selection without ever removing any items from the selection. [3] If the mouse is dragged out of the widget while button 1 is

pressed, the treectrl will automatically scroll to make more

items visible (if there are more items off-screen on the side

where the mouse left the window). [4] The Left and Right keys move the active cursor one item to the

left or right; for an hierarchical tree with vertical orienta-

tion nothing will happen, since it has no two items in the same row. The selection is set to include only the active item. If Left or Right is typed with the Shift key down, then the active cursor moves and the selection is extended to include the new item. [5] The Up and Down keys move the active cursor one item up or down. The selection is set to include only the active item. If Up or Down is typed with the Shift key down, then the active cursor moves and the selection is extended to include the new item.

[6] The Next and Prior keys move the active cursor forward or back-

wards by one screenful, without affecting the selection.

[7] Control-Next and Control-Prior scroll the view right or left by

one page without moving the active cursor or affecting the

selection. Control-Left and Control-Right behave the same.

[8] The Home and End keys scroll to the left or right end of the

widget without moving the active cursor or affecting the selec-

tion.

[9] The Control-Home and Control-End keys scroll to the top or bot-

tom of the widget, they also activate and select the first or

last item. If also the Shift key is down, then the active cur-

sor moves and the selection is extended to include the new item. [10] The Space and Select keys set the selection to the active item.

[11] Control-/ selects the entire contents of the widget.

[12] Control-\ clears any selection in the widget.

[13] The + and - keys expand or collapse the active item, the Return

key toggles the active item. [14] The mousewheel scrolls the view of the widget four lines up or down depending on the direction, the wheel was turned. The active cursor or the selection is not affected.