From 3119a6b4195b4f8ae8c338788103160833936983 Mon Sep 17 00:00:00 2001 From: treectrl Date: Sat, 23 Jul 2005 00:35:20 +0000 Subject: Changes for 2.1. --- doc/What's New in TkTreeCtrl.html | 611 +++++++++++++++++++++++++++++++++++++- doc/treectrl.html | 305 +++++++++---------- doc/treectrl.man | 301 +++++++++---------- doc/treectrl.n | 297 +++++++++--------- 4 files changed, 1041 insertions(+), 473 deletions(-) diff --git a/doc/What's New in TkTreeCtrl.html b/doc/What's New in TkTreeCtrl.html index 25dfdba..ed598ef 100644 --- a/doc/What's New in TkTreeCtrl.html +++ b/doc/What's New in TkTreeCtrl.html @@ -1,10 +1,12 @@ - + + + @@ -12,6 +14,9 @@ + + + @@ -27,151 +32,194 @@ +

What's New in TkTreeCtrl 2.1

+ This version should be backwards compatible with 2.0, except for a few obscure changes.
+

TreeCtrl Configuration Options

+ + + + + + + + + + + + + + + + + + + +

New	Comment
-itemwidth	+
-itemwidthequal	Deprecates the column -widthhack option.
-itemwidthmultiple	Deprecates the column -stepwidth option.

Column Configuration Options

+ + + + + + + + + + + + + + + +

Deprecated	What to use instead
-stepwidth	treectrl's -itemwidthmultiple option
-widthhack	treectrl's -itemwidthequal option

Element Command

+ @@ -184,25 +232,38 @@ instead + + + + + + + + + + +

New	Comment
element perstate	Like [item element perstate].

Item Configuration Options

+ @@ -211,396 +272,520 @@ instead + + + + + + + + + + +

New	Comment
-height	Overrides the treectrl's -itemheight option

Item Command

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Deprecated	What to use instead
item element actual	item element perstate
item complex	item element configure
Behaviour Changed	What changed
item bbox	No longer returns an error if no style had been assigned to the column.
item state forcolumn	No longer returns an error if no style had been assigned to the column.
item style set	Does nothing when replacing a style with the same style. Previously the old style was freed before assigning the new style, losing the element config info if the old and new styles were the same. + Potential incompatibility
Arguments/Result Changed	What changed
item create	Added options: -count -height, -nextsibling, -open, -parent, -prevsibling, and -returnid. Multiple items may be created with one call using the -count option.
item element configure	Multiple elements in multiple columns may be configured with a single call. Use '+' to separate elements, and ',' to separate columns. See the docs.
item style set	When no column is specified, returns a list of one style name per column. Previously, the list would have less values than the number of columns if no styles had ever been assigned to the rightmost column(s). + Potential incompatibility
item text	When no column is specified, returns a list of one string per column.
New	Comment
item image	Partner to the [item text] command.
item element perstate	Not really new, just renamed from [item element actual] to better describe what it does. Accepts a new optional argument which specifies the state to use when determining the value of the per-state option. + + The following options no longer return a default value if the per-state option itself does not have a value specified: + + + bitmap -foreground, -background + border -relief + text -fill, -font + + + Potential incompatibility
item span	A style may now be displayed over multiple adjacent columns. +

Notify Command

+ + + + + + + + + + + +

New	Comment
notify unbind +	Let's you unbind all scripts from an object with one call.

Style Layout Changes

Column justification will now affect the position of elements in 2 situations which previously had no effect (Potential incompatibility):

If a -detach element had a fixed width larger than the other elements.
If an element had -iexpand x specified as well as -maxwidth, leaving some space available.

Element Changes

Bitmap, image and text elements are drawn clipped if given less space than they need.
Fixed line wrapping of text elements. It did not work for single lines of text at all (Potential incompatibility).
The text -wrap option can now be none to disable line wrapping.

Event Changes

The new static event <ItemVisibility> is generated when items become visible on screen and when items are no longer visible on screen. This event allows you to create really big lists by only assigning styles when items are about to be displayed. See the EVENTS AND SCRIPT @@ -608,168 +793,210 @@ SUBSTITUTIONS section in the help file, and the new demo "Big List".

Other Changes

On WinXP, the column header sort arrow is drawn like Explorer draws it if -usetheme is true.

Demo Changes

New demo "Big List". Demonstrates the new <ItemVisibility> event, using <Expand-before> to add items on demand, and column spanning.
The context menu has a Span submenu that lets you maninpulate column spanning in items. See the item span command in the help file.
Under WinXP, the "Explorer" demos will use the new shellicon extension if available. This extension allows a treectrl to display file/folder icons using the Win32 Shell API. It may work on other versions of Windows but it hasn't been tested.

What's New in TkTreeCtrl 2.0

TreeCtrl Configuration Options

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -921,115 +1183,144 @@ buttons/lines. +

TreeCtrl Commands

Replaced	What to use instead
-openbuttonimage	-buttonimage
-closedbuttonimage	-buttonimage
-openbuttonbitmap	-buttonbitmap
-closedbuttonbitmap	-buttonbitmap
Usage Changed	How it changed
-backgroundmode	The values "index" and "visindex" are deprecated. The value "order" should be used instead of "index", and "ordervisible" should be used instead of "visindex". This brings @@ -778,18 +1005,22 @@ index" command.
-treecolumn	This used to be any integer value which may or may not have corresponded to an actual column. Now the value must be a valid column description, or an empty string to indicate no column should display @@ -797,122 +1028,153 @@ buttons/lines.
New
-backgroundimage
-columnprefix
-columnresizemode
-itemprefix
-minitemheight
-usetheme

+ + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -1038,276 +1329,345 @@ instead +

Column Configuration Options

Deprecated	What to use instead
compare	item compare
index	item id
numcolumns	column count
numitems	item count
range	item range

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -1316,255 +1676,318 @@ for valid state names. +

Column Command

Removed	What to use instead
-relief +	-state
-sunken	-state
Renamed +	New name
-arrowpad	-arrowpadx
Usage Changed	How it changed
-background	This is now a per-state option. See COLUMNS in the help file for valid state names.
New +
-arrowbitmap +
-arrowimage
-arrowpady
-maxwidth
-resize
-state
-textlines

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -1573,147 +1996,184 @@ index in the list of columns. +

Item Command

Deprecated	What to use instead
column index	column id
Arguments/Result Changed	What changed
column configure +	A column description of "all" is allowed if at least one option-value pair is given. +
column create	The result is a unique identifier. Previously the result was an index in the list of columns.
column delete	A column description of "all" is allowed.
New	Comment
column compare
column count	replaces "numcolumns"
column dragconfigure
column dragcget
column id	replaces "column index"
column list
column order

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -1722,68 +2182,85 @@ instead +

Notify Command

Removed	What to use instead
item index	item order
New	Comment
item compare	replaces "compare"
item count	replaces "numitems"
item id	replaces "index"
item order	replaces "item index"
item range	replaces "range"

+ + + + + + + + + + + + + + @@ -1798,10 +2277,13 @@ argument + New syntax:
+ + @@ -1809,6 +2291,8 @@ New syntax:
+ + @@ -1816,26 +2300,33 @@ New syntax:
+ + + + + + + + + + + + @@ -1917,42 +2427,52 @@ above +

Style Layout Options

Arguments/Result Changed	What changed
notify generate +	Added optional percentsCommand argument
notify install	Old syntax (supported but deprecated): + + @@ -1791,6 +2268,8 @@ argument
notify linkage	Old syntax (supported but deprecated): + + @@ -1843,10 +2334,13 @@ New syntax: + notify linkage eventName + + @@ -1854,14 +2348,18 @@ New syntax: + + New syntax: + + @@ -1869,10 +2367,13 @@ New syntax: + notify linkage <eventName> + + @@ -1880,35 +2381,44 @@ New syntax: + +
notify uninstall	see notify install above

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -2144,14 +2710,17 @@ surrounds. +

Element Changes

A new element type window was added. See the new demo "Firefox Privacy" and the ELEMENTS section in the help @@ -2159,11 +2728,13 @@ file.
All element types have a new per-state boolean option called -draw.
The text element type has a new option called -textvariable. See the new demo @@ -2171,18 +2742,22 @@ See the new demo +

Event Changes

2 new %-substitution characters %P and %? are allowed in binding scripts. See the EVENTS AND SCRIPT SUBSTITUTIONS section in the help @@ -2190,82 +2765,99 @@ file.
The new static event <ItemDelete> is generated when items are deleted. See the EVENTS AND SCRIPT SUBSTITUTIONS section in the help file.

Library Script Changes

filelist-bindings.tcl:

The Priv(edit) variable, which is used to specify which text elements may be edited, now has the same format as Priv(sensitive). Previously only elements in the first column could be edited.
3 new commands in the TreeCtrl namespace should be used to access the Priv(dragimage), Priv(edit) and Priv(sensitive) variables. The commands are SetDragImage, SetEditable and SetSensitive.
Two new dynamic events <Edit-begin> and <Edit-end> are generated when editing a file name.

treectrl.tcl:

On OSX/Aqua, the Command key is used to perform discontinuous selection. Previously the Control key was used but Command is specified by Apple's user-interface guidelines.

Other Changes

On WinXP, the column headers and open/close buttons are drawn using the system theme if -usetheme is true. The sort arrow is drawn the old-fashioned way.
On OSX/Aqua, the column headers and open/close buttons are drawn using the system theme if -usetheme @@ -2275,35 +2867,42 @@ and -arrowgravity options.
Columns can be moved by drag-and-drop. See column dragconfigure in the help file.
Columns can be specified in new ways. See the COLUMN DESCRIPTION section in the help file.
Added new section DYNAMIC EVENTS to the help file.
Added new section PER-STATE OPTIONS to the help file.
The new style layout option -indent allows elements to be displayed in the button/line area. See the style layout command in the help file and the new demo "Firefox Privacy".
The new item description end is equivalent to last.
If you have version 1.1 installed, replace the old pkgIndex.tcl file with the one from this version (but replace the version number 2.0 with 1.1). Otherwise the old pkgIndex.tcl file will @@ -2312,44 +2911,54 @@ scripts are found.

Demo Changes

New demo "Firefox Privacy". Demonstrates the new window element type and -indent style layout option.
New demo "Textvariable". Demonstrates the new -textvariable option of the text element.
Added a new Event Browser window to display events generated by the main treectrl widget.
The context menu can be popped up in all the demo lists. A <Control-ButtonPress-1> binding for this was added under OSX/Aqua.
In the "Explorer" demos, the file name is hidden while editing the file name.

+ diff --git a/doc/treectrl.html b/doc/treectrl.html index c89a604..bfaf0cb 100644 --- a/doc/treectrl.html +++ b/doc/treectrl.html @@ -1,14 +1,14 @@ -treectrl - Tk Commands - -

treectrl(n) 2.0 treectrl "Tk Commands"

treectrl(n) 2.1 treectrl "Tk Commands"

NAME

treectrl - Create and manipulate hierarchical multicolumn widgets @@ -43,7 +43,7 @@ KEYWORDS

SYNOPSIS

-package require treectrl 2.0
+package require treectrl 2.1

Usage Changed	How it changed
-iexpand	Two new flags "x' and "y" are allowed. Previously, only the -ipadx and -ipady padding could be expanded by this option. The new xy flags expand the display area of the element, not the padding. To @@ -1960,6 +2480,8 @@ update your code, you will probably want to change this: + + @@ -1967,18 +2489,23 @@ update your code, you will probably want to change this: + $T style layout $S $E -iexpand we + + to this: + + @@ -1986,156 +2513,195 @@ to this: + $T style layout $S $E -iexpand x + + Keep in mind that -union elements are not affected by -iexpand xy, since the size of a -union element is determined by the elements it surrounds.
New +
-height
-maxheight
-maxwidth
-minheight
-minwidth
-sticky
-width

@@ -131,7 +131,7 @@ package require treectrl 2.0
- + @@ -407,7 +407,7 @@ Database Class: Height

Specifies the desired height for the window in any of the forms acceptable to Tk_GetPixels. -The default is 200 pixel. +The default is 200 pixels. If this option is less than or equal to zero then the window will not request any size at all. @@ -451,14 +451,9 @@ Database Name: itemWidth
Database Class: ItemWidth

Specifies a fixed width for every item in any of the forms acceptable to Tk_GetPixels. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "". +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column).

Command-Line Switch: -itemwidthequal
@@ -466,16 +461,10 @@ Database Name: itemWidthEqual
Database Class: ItemWidthEqual

Specifies a boolean that says whether all items should have the same width. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, and -the treectrl's -itemwidth option is <= 0, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -itemwidth option is <= 0. +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). +If the -itemwidth option is specified, then this option has no effect.

Command-Line Switch: -itemwidthmultiple
@@ -483,16 +472,10 @@ Database Name: itemWidthMultiple
Database Class: ItemWidthMultiple

Specifies a screen distance that every item's width will be evenly divisible by in any of the forms acceptable to Tk_GetPixels. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, and -the treectrl's -itemwidth option is <= 0, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -itemwidth option is <= 0. +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). +If the -itemwidth option is specified, then this option has no effect.

Command-Line Switch: -linecolor
@@ -614,9 +597,9 @@ The default value is true. Database Name: treeColumn
Database Class: TreeColumn

-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. +Specifies a column description that determines which +column displays the buttons and lines. +The default is unspecified.

Command-Line Switch: -usetheme
@@ -643,18 +626,22 @@ not request any size at all. Database Name: wrap
Database Class: Wrap

-Specifies how to arrange items inside treectrl's window. -The value must be an empty string, window, -or a list with an integer as first element -and either items or pixels 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 window mode a screen line break may occur after any element; -in items mode a line break will only be made after the specified -number of items; -in pixels mode a line break will only be made after the -specified screen distance is reached. +Specifies whether items are arranged in a 1- or 2-dimensional layout. + +If the value is an empty string (the default), then items are arranged from top +to bottom (-orient vertical) or from left to right (-orient horizontal) in +a 1-dimensional layout. + +If the value is "N items", then a no more than N items will appear in +a vertical group (-orient vertical) or horizontal group (-orient horizontal). + +If the value is "N pixels", then a no vertical group of items will be +taller than N pixels (-orient vertical) or no horizontal group of items will +be wider than N pixels (-orient horizontal). + +If the value is window, then a no vertical group of items will be +taller than the window (-orient vertical) or no horizontal group of items will +be wider than the window (-orient horizontal).

Command-Line Switch: -xscrolldelay
@@ -780,10 +767,10 @@ The following forms of the command are supported:

pathName column bbox column

-Returns a list with four elements giving an approximate bounding box +Returns a list with four elements giving the 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 -showheader option, +If the treectrl is configured not to display the column headers +by means of the -showheader option, then an empty list is returned instead.

@@ -980,10 +967,10 @@ command.

pathName contentbox

-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. +Returns a list with four elements giving the bounding box +for the space used to display the items, +i.e. the space of the treectrl window without +the surrounding borders or the column headers.

pathName debug option ?arg arg ...?

@@ -1062,7 +1049,7 @@ debugging options -enable and -display are swi

pathName debug dinfo

For every of the treectrl widget -a line with some internal valuess info about all items +a line with some internal values info about all items is printed to stdout. The command returns the empty string. @@ -1288,14 +1275,15 @@ The following forms of the command are supported:

pathName item ancestors itemDesc: -Returns a list containing the numerical indexes of all ancestors -of the item specified by itemDesc from its parent up to the -root item. +Returns a list containing the item ids of the ancestors +of the item specified by itemDesc. The first list value is the parent, +the second is the parent's parent, an so on. The last list value will be the +root item if itemDesc is a descendant of the root item.
pathName item bbox itemDesc ?column? ?element?: -Returns a list with four elements giving an approximate bounding box +Returns a list with four elements giving the 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 @@ -1313,7 +1301,7 @@ values accepted by the item configure command.
pathName item children itemDesc: -Returns a list containing the numerical indexes of all children +Returns a list containing the item ids of all children of the item specified by itemDesc in the correct order from the first child to the last child. @@ -1463,9 +1451,10 @@ and b) each ancestor's -visible option is true
pathName item delete first ?last?: Deletes the specified item(s). -First and last must be the string all or an itemDesc. -If either first or last is specified as all, all items are -deleted; if first is specified as itemDesc and last isn't +First and last must be the string all or a valid +item description. +If either first or last is specified as all, then all items are +deleted. If first is specified and last isn't specified, the item described by first is deleted. If both first and last are specified, they must decribe items with a common ancestor; @@ -1476,6 +1465,12 @@ If the current active item is deleted, the root item becomes th If the current selection anchor item is deleted, the root item becomes the new anchor item. There is no way to delete the root item of the treectrl widget; in all cases the specification of the root item is ignored. +

+For each call to this command, two events may be generated. +If any of the deleted items are selected, then a <Selection> event +is generated just before the items are deleted. +If any items were actually deleted, then an <ItemDelete> event event is generated just before the items +are deleted.
pathName item dump itemDesc: @@ -1570,7 +1565,7 @@ and an <Expand-after> event after the item state was chan
pathName item firstchild parent ?child?: -If child is not specified, returns the numerical index of the first +If child is not specified, returns the item id 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. @@ -1579,8 +1574,8 @@ Then it will become the new first child of parent.
pathName item id itemDesc: -This command resolves the item description itemDesc into a unique item -identifier (see ITEM DESCRIPTION below). If the item described by +This command resolves the item description itemDesc into a unique item +identifier. If the item described by itemDesc doesn't exist, this command returns an empty string.

@@ -1610,24 +1605,24 @@ parent of the item decribed by descendant, 0 otherwise.
pathName item isopen itemDesc: -Returns 1, if the item described by itemDesc has cuurently the +Returns 1 if the item described by itemDesc has the state open switched on, 0 otherwise.
pathName item lastchild parent ?child?: -If child is not specified, returns the numerical index of the last +If child is not specified, returns the item id of the last child of the item described by parent. -If child is specified, it must described an item +If child is specified, it must describe an item that is not an ancestor of parent. Then it will become the new last child of parent.
pathName item nextsibling sibling ?next?: -If next is not specified, returns the numerical index of the next +If next is not specified, returns the item id of the next sibling of the item described by sibling. -If next is specified, it must described an item +If next is specified, it must describe an item that is not an ancestor of sibling. Then it will become the new next sibling of sibling. @@ -1650,25 +1645,26 @@ is not visible.
pathName item parent itemDesc: -Returns the numerical index of the parent of the item +Returns the item id of the parent of the item described by itemDesc.
pathName item prevsibling sibling ?prev?: -If prev is not specified, returns the numerical index of the previous +If prev is not specified, returns the item id of the previous sibling of the item described by sibling. -If prev is specified, it must described an item +If prev is specified, it must describe an item that is not an ancestor of sibling. Then it will become the new previous sibling of sibling.
pathName item range first last: -Returns a list containing the unique identifiers of all items +Returns a list containing the item ids of all items in the range between first and last, inclusive. The order between first and last doesn't matter, -and the result is always ordered by the increasing index of the items. +and the result is always sorted by the increasing order of the items (as +returned by the item order command). The items specified by first and last must share a common ancestor. @@ -1676,13 +1672,15 @@ ancestor.
pathName item remove itemDesc: Removes the item described by itemDesc -from the children list of its father, so that it will become an orphan. +from the list of children of its parent, so that it will become an orphan.
pathName item rnc itemDesc: Returns a list of two integers, which corresponds to the row and column -of the item described by itemDesc. +of the item described by itemDesc. The row and column corresponds to +the on-screen arrangement of items as determined by the -orient and -wrap +options. If the item is not displayed, this command returns an empty string.
pathName item sort itemDesc ?option ...?: @@ -1777,32 +1775,34 @@ The following forms of the command are supported:
pathName item state forcolumn itemDesc column ?stateDescList?: -Just like item state set but manipulates user-defined states for a single -item column, not the item as a whole. +Just like item state set but manipulates dynamic states for a single +item column, not the item as a whole. If stateDescList is unspecified, +this command returns a list containing the names of all the dynamic states +which are switched on in column.
pathName item state get itemDesc ?stateName?: If no stateName is specified, returns a list containing -the names of all (predefined and user defined) states +the names of all (static and dynamic) 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 item state set itemDesc ?lastItem? ?stateDescList?: +
pathName item state set itemDesc ?lastItem? stateDescList: Every element of stateDescList -must describe a user defined state (see STATES below), -with the particularity that the state name may have also a leading ~. +must be the name of a dynamic state (see STATES below), +optionally preceded by a ~ or ! character. 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 all, +If ItemDesc is the string all, then the state changes are made for all items of the treectrl widget.

@@ -1818,9 +1818,10 @@ The following forms of the command are supported:

pathName item style elements 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. +This command returns a list containing the names of elements which were +configured by the item element configure command for the item +described by itemDesc in column. If there is no style assigned +to column an error is returned.
pathName item style map itemDesc column style map: @@ -2186,11 +2187,11 @@ Deprecated. Use the item count command instead.
pathName orphans: -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 item remove widget command. +Returns a list containing the item ids of all items +which have no parent. +When an item is created, it has no parent by default, +and can later become an orphan +by means of the item remove widget command. The root item is not returned.
pathName range first last: @@ -2200,7 +2201,7 @@ Deprecated. Use the item range command instead.
pathName state option ?stateName?: -This command is used to manipulate the list of user defined states, +This command is used to manipulate the list of user-defined states, see section STATES below. The exact behavior of the command depends on the option argument that follows the state argument. @@ -2211,26 +2212,26 @@ The following forms of the command are supported:
pathName state define stateName: Defines a new state with the name stateName, -which must not be the name of a predefined or already user defined state. +which must not be the name of an existing state.
pathName state linkage stateName: Returns a string indicating -whether the specified state is user defined +whether the specified state is user-defined by means of the state define widget command (dynamic) or predefined by the treectrl widget itself (static).
pathName state names: -Returns a list containing the names of all user defined states. +Returns a list containing the names of all user-defined states.
pathName state undefine ?stateName ...?: -Every stateName must be the name of a user defined state. -Removes this state from the list of user defined states. +Every stateName must be the name of a user-defined state. +Removes this state from the list of user-defined states.

pathName see itemDesc

@@ -2253,13 +2254,14 @@ It has several forms, depending on option:

pathName selection add first ?last?

First and last (if specified) -must be the string all or an itemDesc. -Selects all of the items in the range between -first and last, inclusive, +must be the string all or a valid item description. +Adds every unselected item in the range between +first and last, inclusive, to the selection without affecting the selection state of items outside that range. If one of the arguments is the string all, -all items of the treectrl widget are added to the selection instead. -A <Selection> event is generated. +every unselected item in the treectrl widget is added to the selection. +A <Selection> event is generated if any items were added to the +selection.

pathName selection anchor ?itemDesc?

@@ -2276,14 +2278,15 @@ Returns the numerical id of the selection anchor item.

pathName selection clear ?first? ?last?

First and last (if specified) -must be the string all or an itemDesc. +must be the string all or a valid item description. 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 all, -the selection is completely cleared instead. -A <Selection> event is generated. +If no additional arguments are given, +or if one of the arguments is the string all, +then all items are removed from the selection. +A <Selection> event is generated if any items were removed from the +selection.

pathName selection count

@@ -2294,7 +2297,7 @@ of items in the treectrl that are currently selected.

pathName selection get

-Returns a list containing the numerical ids of +Returns a list containing the item 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. @@ -2302,27 +2305,24 @@ string is returned.

pathName selection includes itemDesc

-Returns 1 if the item indicated by itemDesc is currently +Returns 1 if the item described by itemDesc is currently selected, 0 if it isn't.

pathName selection modify select deselect

Both arguments select and deselect must be -the string all 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 deselect, -it is added to the selection. -A <Selection> event is generated. +the string all or a possibly-empty list of item descriptions. +Any unselected items in select are added to the selection, +and any selected items in deselect are removed from the selection (except +for those items which are also in select). +A <Selection> event is generated if any items were selected or deselected.

pathName style option ?element? ?arg arg ...?

-This command is used to manipulate styles, which could be considered -as a geometry manager for the elements of one item. +This command is used to manipulate styles, which can be thought of +as a geometry manager for elements. The exact behavior of the command depends on the option argument that follows the style argument. The following forms of the command are supported: @@ -2649,8 +2649,7 @@ The following options are supported for columns:

-arrow direction

-Indicates whether or not an arrow should be drawn in the column header -to the right of the column title. +Indicates whether or not an arrow should be drawn in the column header. Direction must have one of the values none (the default), up, or down. @@ -2667,7 +2666,7 @@ If an image is specified for a certain state, it overrides the -arrowbitmap opti

-arrowside side

-Indicates on which side an arrow should be drawn, if at all. +Indicates on which side of the bitmap/image/text the arrow should be drawn. Side must be either left or right (the default).

@@ -2679,7 +2678,7 @@ if there is more space available for drawing the arrow then needed.

-arrowpadx amount

Amount specifies how much padding to -leave on the left and right side of the arrow. +leave on the left and right of the arrow. Amount may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2734,7 +2733,7 @@ This option overrides the -bitmap column option.

-imagepadx amount

Amount specifies how much padding to -leave on the left and right side of the image. +leave on the left and right of the image (or bitmap). Amount may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2742,15 +2741,15 @@ it defaults to 6.

-imagepady amount

Amount specifies how much padding to -leave on the top and bottom of the image. +leave on the top and bottom of the image (or bitmap). Amount may be a list of two values to specify padding for top and bottom separately; it defaults to 0.

-itembackground colorList

-Specifies a list of colors, which should be used as -alternating background color for the items of this column. +Specifies a list of zero or more colors, which are used as +alternating background colors for items in this column. See also the -backgroundmode widget option for more on this.

@@ -2801,7 +2800,7 @@ whenever a column must be specified.

-text text

-Specifies a text to be displayed inside the column title. +Specifies a text string to be displayed as the column title.

-textcolor color

@@ -2821,7 +2820,7 @@ of text.

-textpadx amount

Amount specifies how much padding to -leave on the left and right side of the text. +leave on the left and right of the text. Amount may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2925,17 +2924,16 @@ is true.

STATES

-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. +For every item a set of boolean states is managed. These states play an +integral role in the appearance of each item. The following states are predefined for every item:

active: -At every time this state is set for exactly one item, -which therefore is called the active item. +At all times this state is set for exactly one item. The active item is +used with keyboard navigation. When the treectrl widget is created or when the active item is deleted, -the root item will become the active element. +the root item will become the active item. This state can be modified by means of the widget command activate.

@@ -2946,9 +2944,9 @@ It cannot be modified.
focus: This state is set for every item, -if the treectrl widget has currently the focus. +if the treectrl widget currently has the focus. It cannot be modified by means of a widget command, -but is maintained as reaction of a <FocusIn> or <FocusOut> event. +but is maintained in reaction to the <FocusIn> and <FocusOut> events.
open: @@ -2958,33 +2956,19 @@ the descendants of the item are displayed 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 +For a new item this state is switched on by default. +This state can be modified by means of the widget commands item expand, item collapse, or item toggle.
selected: -This state is set for every item, which is included in the selection. +This state is set for every item included in the selection. It can be modified by means of the widget command selection.

By means of the state define widget command -up to 27 additional stateNames 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 element of the list -the stateDesc describes the same state as the item currently has. +up to 27 additional states can be defined.

PER-STATE OPTIONS

@@ -3399,6 +3383,9 @@ Indicates the item nearest to the point given by x and

rnc row column

Indicates the item in the given row and column. +The row and column corresponds to +the on-screen arrangement of items as determined by the -orient and -wrap +options. You can memorize rnc as abbreviation of "row 'n' column".

diff --git a/doc/treectrl.man b/doc/treectrl.man index 9ed125d..01dbc94 100644 --- a/doc/treectrl.man +++ b/doc/treectrl.man @@ -3,11 +3,11 @@ See the file "license.terms" for information on usage and redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES. - $Id: treectrl.man,v 1.30 2005/07/15 01:39:20 treectrl Exp $} -][manpage_begin treectrl n 2.0] + $Id: treectrl.man,v 1.31 2005/07/23 00:35:20 treectrl Exp $} +][manpage_begin treectrl n 2.1] [moddesc {Tk Commands}] [titledesc {Create and manipulate hierarchical multicolumn widgets}] -[require treectrl 2.0] +[require treectrl 2.1] [description] [list_begin definitions] @@ -165,7 +165,7 @@ double-buffered, so it works with a buffer size as big as the biggest item. [tkoption_def -height height Height] Specifies the desired height for the window in any of the forms acceptable to [fun Tk_GetPixels]. -The default is 200 pixel. +The default is 200 pixels. If this option is less than or equal to zero then the window will not request any size at all. @@ -193,40 +193,23 @@ use it. [tkoption_def -itemwidth itemWidth ItemWidth] Specifies a fixed width for every item in any of the forms acceptable to [fun Tk_GetPixels]. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "". +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). [tkoption_def -itemwidthequal itemWidthEqual ItemWidthEqual] Specifies a boolean that says whether all items should have the same width. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, and -the treectrl's -itemwidth option is <= 0, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -itemwidth option is <= 0. +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). +If the -itemwidth option is specified, then this option has no effect. [tkoption_def -itemwidthmultiple itemWidthMultiple ItemWidthMultiple] Specifies a screen distance that every item's width will be evenly divisible by in any of the forms acceptable to [fun Tk_GetPixels]. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, and -the treectrl's -itemwidth option is <= 0, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -itemwidth option is <= 0. +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). +If the -itemwidth option is specified, then this option has no effect. [tkoption_def -linecolor lineColor LineColor] Specifies the color which should be used for drawing @@ -296,9 +279,9 @@ should draw the connecting lines between children of the root item. The default value is true. [tkoption_def -treecolumn treeColumn TreeColumn] -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. +Specifies a [sectref {COLUMN DESCRIPTION} {column description}] that determines which +column displays the buttons and lines. +The default is unspecified. [tkoption_def -usetheme useTheme UseTheme] Specifies a boolean value that determines whether this widget should draw @@ -313,18 +296,22 @@ If this option is less than or equal to zero then the window will not request any size at all. [tkoption_def -wrap wrap Wrap] -Specifies how to arrange items inside treectrl's window. -The value must be an empty string, [const window], -or a list with an integer as first element -and either [const items] or [const pixels] 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 [const window] mode a screen line break may occur after any element; -in [const items] mode a line break will only be made after the specified -number of items; -in [const pixels] mode a line break will only be made after the -specified screen distance is reached. +Specifies whether items are arranged in a 1- or 2-dimensional layout. + +If the value is an empty string (the default), then items are arranged from top +to bottom (-orient vertical) or from left to right (-orient horizontal) in +a 1-dimensional layout. + +If the value is "[emph N] [const items]", then a no more than [emph N] items will appear in +a vertical group (-orient vertical) or horizontal group (-orient horizontal). + +If the value is "[emph N] [const pixels]", then a no vertical group of items will be +taller than [emph N] pixels (-orient vertical) or no horizontal group of items will +be wider than [emph N] pixels (-orient horizontal). + +If the value is [const window], then a no vertical group of items will be +taller than the window (-orient vertical) or no horizontal group of items will +be wider than the window (-orient horizontal). [tkoption_def -xscrolldelay xScrollDelay ScrollDelay] Specifies the amount of time before the default binding should handle @@ -422,10 +409,10 @@ The following forms of the command are supported: [list_begin definitions] [call [arg pathName] [cmd {column bbox}] [arg column]] -Returns a list with four elements giving an approximate bounding box +Returns a list with four elements giving the bounding box for the column header specified by [arg column]. -If the treectrl is configured to don't display the column headers -by means of the [option -showheader] option, +If the treectrl is configured not to display the column headers +by means of the [option -showheader] option, then an empty list is returned instead. [call [arg pathName] [cmd {column cget}] [arg column] [arg option]] @@ -585,10 +572,10 @@ this case the command returns an empty string. command. [call [arg pathName] [cmd contentbox]] -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. +Returns a list with four elements giving the bounding box +for the space used to display the items, +i.e. the space of the treectrl window without +the surrounding borders or the column headers. [call [arg pathName] [cmd debug] [arg option] [opt [arg {arg arg ...}]]] This command is used to facilitate debugging of the treectrl widget. @@ -656,7 +643,7 @@ debugging options [option -enable] and [option -display] are switched on. [call [arg pathName] [cmd {debug dinfo}]] For every of the treectrl widget -a line with some internal valuess info about all items +a line with some internal values info about all items is printed to stdout. The command returns the empty string. @@ -849,13 +836,14 @@ The following forms of the command are supported: [list_begin definitions] [call [arg pathName] [cmd {item ancestors}] [arg itemDesc]] -Returns a list containing the numerical indexes of all ancestors -of the item specified by [arg itemDesc] from its parent up to the -root item. +Returns a list containing the item ids of the ancestors +of the item specified by [arg itemDesc]. The first list value is the parent, +the second is the parent's parent, an so on. The last list value will be the +root item if [arg itemDesc] is a descendant of the root item. [call [arg pathName] [cmd {item bbox}] [arg itemDesc] [opt [arg column]] \ [opt [arg element]]] -Returns a list with four elements giving an approximate bounding box +Returns a list with four elements giving the bounding box for the item described by [arg itemDesc]. If no further argument is specified, the bbox spans the area of the item over all columns. If a [arg column] is specified, only the area of the item @@ -869,7 +857,7 @@ Returns the current value of the configuration option for the item specified by values accepted by the [cmd "item configure"] command. [call [arg pathName] [cmd {item children}] [arg itemDesc]] -Returns a list containing the numerical indexes of all children +Returns a list containing the item ids of all children of the item specified by [arg itemDesc] in the correct order from the first child to the last child. @@ -997,9 +985,10 @@ and b) each ancestor's [option -visible] option is true [call [arg pathName] [cmd {item delete}] [arg first] [opt [arg last]]] Deletes the specified item(s). -[arg First] and [arg last] must be the string [const all] or an [arg itemDesc]. -If either [arg first] or [arg last] is specified as [const all], all items are -deleted; if [arg first] is specified as [arg itemDesc] and [arg last] isn't +[arg First] and [arg last] must be the string [const all] or a valid +[sectref {ITEM DESCRIPTION} {item description}]. +If either [arg first] or [arg last] is specified as [const all], then all items are +deleted. If [arg first] is specified and [arg last] isn't specified, the item described by [arg first] is deleted. If both [arg first] and [arg last] are specified, they must decribe items with a common ancestor; @@ -1010,6 +999,12 @@ If the current [const active] item is deleted, the root item becomes the new act If the current selection [const anchor] item is deleted, the root item becomes the new anchor item. There is no way to delete the root item of the treectrl widget; in all cases the specification of the root item is ignored. +[nl] +For each call to this command, two events may be generated. +If any of the deleted items are selected, then a [const ] event +is generated just before the items are deleted. +If any items were actually deleted, then an [const ] event event is generated just before the items +are deleted. [call [arg pathName] [cmd {item dump}] [arg itemDesc]] Returns a list with six elements in the form @@ -1095,15 +1090,15 @@ an [const ] event before the item state is changed, and an [const ] event after the item state was changed. [call [arg pathName] [cmd {item firstchild}] [arg parent] [opt [arg child]]] -If [arg child] is not specified, returns the numerical index of the first +If [arg child] is not specified, returns the item id of the first child of the item described by [arg parent]. If [arg child] is specified, it must described an item that is not an ancestor of [arg parent]. Then it will become the new first child of [arg parent]. [call [arg pathName] [cmd {item id}] [arg itemDesc]] -This command resolves the item description [arg itemDesc] into a unique item -identifier (see [sectref {ITEM DESCRIPTION}] below). If the item described by +This command resolves the [sectref {ITEM DESCRIPTION} {item description}] [arg itemDesc] into a unique item +identifier. If the item described by [arg itemDesc] doesn't exist, this command returns an empty string. [call [arg pathName] [cmd {item image}] [arg itemDesc] [opt [arg column]] \ @@ -1128,20 +1123,20 @@ Returns 1 if the item described by [arg itemDesc] is a direct or indirect parent of the item decribed by [arg descendant], 0 otherwise. [call [arg pathName] [cmd {item isopen}] [arg itemDesc]] -Returns 1, if the item described by [arg itemDesc] has cuurently the +Returns 1 if the item described by [arg itemDesc] has the state [const open] switched on, 0 otherwise. [call [arg pathName] [cmd {item lastchild}] [arg parent] [opt [arg child]]] -If [arg child] is not specified, returns the numerical index of the last +If [arg child] is not specified, returns the item id of the last child of the item described by [arg parent]. -If [arg child] is specified, it must described an item +If [arg child] is specified, it must describe an item that is not an ancestor of [arg parent]. Then it will become the new last child of [arg parent]. [call [arg pathName] [cmd {item nextsibling}] [arg sibling] [opt [arg next]]] -If [arg next] is not specified, returns the numerical index of the next +If [arg next] is not specified, returns the item id of the next sibling of the item described by [arg sibling]. -If [arg next] is specified, it must described an item +If [arg next] is specified, it must describe an item that is not an ancestor of [arg sibling]. Then it will become the new next sibling of [arg sibling]. @@ -1158,31 +1153,34 @@ result of this command is the row the item falls in. If the optional argument is not visible. [call [arg pathName] [cmd {item parent}] [arg itemDesc]] -Returns the numerical index of the parent of the item +Returns the item id of the parent of the item described by [arg itemDesc]. [call [arg pathName] [cmd {item prevsibling}] [arg sibling] [opt [arg prev]]] -If [arg prev] is not specified, returns the numerical index of the previous +If [arg prev] is not specified, returns the item id of the previous sibling of the item described by [arg sibling]. -If [arg prev] is specified, it must described an item +If [arg prev] is specified, it must describe an item that is not an ancestor of [arg sibling]. Then it will become the new previous sibling of [arg sibling]. [call [arg pathName] [cmd {item range}] [arg first] [arg last]] -Returns a list containing the unique identifiers of all items +Returns a list containing the item ids of all items in the range between [arg first] and [arg last], inclusive. The order between [arg first] and [arg last] doesn't matter, -and the result is always ordered by the increasing index of the items. +and the result is always sorted by the increasing order of the items (as +returned by the [cmd {item order}] command). The items specified by [arg first] and [arg last] must share a common ancestor. [call [arg pathName] [cmd {item remove}] [arg itemDesc]] Removes the item described by [arg itemDesc] -from the children list of its father, so that it will become an orphan. +from the list of children of its parent, so that it will become an orphan. [call [arg pathName] [cmd {item rnc}] [arg itemDesc]] Returns a list of two integers, which corresponds to the row and column -of the item described by [arg itemDesc]. +of the item described by [arg itemDesc]. The row and column corresponds to +the on-screen arrangement of items as determined by the -orient and -wrap +options. If the item is not displayed, this command returns an empty string. [call [arg pathName] [cmd {item sort}] [arg itemDesc] [opt [arg {option ...}]]] Sorts the children of the item described by [arg itemDesc], @@ -1266,30 +1264,32 @@ The following forms of the command are supported: [call [arg pathName] [cmd {item state forcolumn}] [arg itemDesc] [arg column] \ [opt [arg stateDescList]]] -Just like [cmd {item state set}] but manipulates user-defined states for a single -item column, not the item as a whole. +Just like [cmd {item state set}] but manipulates dynamic states for a single +item column, not the item as a whole. If [arg stateDescList] is unspecified, +this command returns a list containing the names of all the dynamic states +which are switched on in [arg column]. [call [arg pathName] [cmd {item state get}] [arg itemDesc] \ [opt [arg {stateName}]]] If no [arg stateName] is specified, returns a list containing -the names of all (predefined and user defined) states +the names of all (static and dynamic) states which are currently switched on for the item described by [arg itemDesc]. If a [arg stateName] is specified, 1 is returned if the specified state is currently switched on for the item, 0 otherwise. [call [arg pathName] [cmd {item state set}] [arg itemDesc] \ - [opt [arg lastItem]] [opt [arg stateDescList]]] + [opt [arg lastItem]] [arg stateDescList]] Every element of [arg stateDescList] -must describe a user defined state (see [sectref STATES] below), -with the particularity that the state name may have also a leading [const ~]. +must be the name of a dynamic state (see [sectref STATES] below), +optionally preceded by a [const ~] or [const !] character. Every state with a leading [const !] will be switched off for the item described by [arg itemDesc], every state with a leading [const ~] will be toggled, and every state without leading [const !] or [const ~] will be switched on. If [arg lastItem] is specified, the state changes will be made for all items in the range betwen [arg itemDesc] and [arg lastItem]. -[arg ItemDesc] may be the string [const all], +If [arg ItemDesc] is the string [const all], then the state changes are made for all items of the treectrl widget. [list_end] @@ -1303,9 +1303,10 @@ The following forms of the command are supported: [list_begin definitions] [call [arg pathName] [cmd {item style elements}] [arg itemDesc] [arg column]] -A list is returned -containing the currently defined elements of the style, -which is set for the item described by [arg itemDesc] in [arg column]. +This command returns a list containing the names of elements which were +configured by the [cmd {item element configure}] command for the item +described by [arg itemDesc] in [arg column]. If there is no style assigned +to [arg column] an error is returned. [call [arg pathName] [cmd {item style map}] [arg itemDesc] [arg column] \ [arg style] [arg map]] @@ -1628,17 +1629,17 @@ Deprecated. Use the [cmd {column count}] command instead. Deprecated. Use the [cmd {item count}] command instead. [call [arg pathName] [cmd orphans]] -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 [cmd {item remove}] widget command. +Returns a list containing the item ids of all items +which have no parent. +When an item is created, it has no parent by default, +and can later become an orphan +by means of the [cmd {item remove}] widget command. The root item is not returned. [call [arg pathName] [cmd range] [arg first] [arg last]] Deprecated. Use the [cmd {item range}] command instead. [call [arg pathName] [cmd state] [arg option] [opt [arg stateName]]] -This command is used to manipulate the list of user defined states, +This command is used to manipulate the list of user-defined states, see section [sectref STATES] below. The exact behavior of the command depends on the [arg option] argument that follows the [cmd state] argument. @@ -1647,20 +1648,20 @@ The following forms of the command are supported: [list_begin definitions] [call [arg pathName] [cmd {state define}] [arg stateName]] Defines a new state with the name [arg stateName], -which must not be the name of a predefined or already user defined state. +which must not be the name of an existing state. [call [arg pathName] [cmd {state linkage}] [arg stateName]] Returns a string indicating -whether the specified state is user defined +whether the specified state is user-defined by means of the [cmd {state define}] widget command ([const dynamic]) or predefined by the treectrl widget itself ([const static]). [call [arg pathName] [cmd {state names}]] -Returns a list containing the names of all user defined states. +Returns a list containing the names of all user-defined states. [call [arg pathName] [cmd {state undefine}] [opt [arg {stateName ...}]]] -Every [arg stateName] must be the name of a user defined state. -Removes this state from the list of user defined states. +Every [arg stateName] must be the name of a user-defined state. +Removes this state from the list of user-defined states. [list_end] [call [arg pathName] [cmd see] [arg itemDesc]] @@ -1678,13 +1679,14 @@ It has several forms, depending on [arg option]: [list_begin definitions] [call [arg pathName] [cmd {selection add}] [arg first] [opt [arg last]]] [arg First] and [arg last] (if specified) -must be the string [const all] or an [arg itemDesc]. -Selects all of the items in the range between -[arg first] and [arg last], inclusive, +must be the string [const all] or a valid [sectref {ITEM DESCRIPTION} {item description}]. +Adds every unselected item in the range between +[arg first] and [arg last], inclusive, to the selection without affecting the selection state of items outside that range. If one of the arguments is the string [const all], -all items of the treectrl widget are added to the selection instead. -A [const ] event is generated. +every unselected item in the treectrl widget is added to the selection. +A [const ] event is generated if any items were added to the +selection. [call [arg pathName] [cmd {selection anchor}] [opt [arg itemDesc]]] If [arg itemDesc] is specified, @@ -1698,45 +1700,43 @@ Returns the numerical id of the selection anchor item. [call [arg pathName] [cmd {selection clear}] \ [opt [arg first]] [opt [arg last]]] [arg First] and [arg last] (if specified) -must be the string [const all] or an [arg itemDesc]. +must be the string [const all] or a valid [sectref {ITEM DESCRIPTION} {item description}]. If any of the items between [arg first] and [arg 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 [const all], -the selection is completely cleared instead. -A [const ] event is generated. +If no additional arguments are given, +or if one of the arguments is the string [const all], +then all items are removed from the selection. +A [const ] event is generated if any items were removed from the +selection. [call [arg pathName] [cmd {selection count}]] Returns an integer indicating the number of items in the treectrl that are currently selected. [call [arg pathName] [cmd {selection get}]] -Returns a list containing the numerical ids of +Returns a list containing the item 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. [call [arg pathName] [cmd {selection includes}] [arg itemDesc]] -Returns 1 if the item indicated by [arg itemDesc] is currently +Returns 1 if the item described by [arg itemDesc] is currently selected, 0 if it isn't. [call [arg pathName] [cmd {selection modify}] [arg select] [arg deselect]] Both arguments [arg select] and [arg deselect] must be -the string [const all] or a possibly empty list of [arg itemDesc]s. -Selects all of the items described by [arg select], -then deselects all items described by [arg deselect], -without affecting the selection state of any item -not mentioned in both arguments. -If one item is described in both arguments [arg select] and [arg deselect], -it is added to the selection. -A [const ] event is generated. +the string [const all] or a possibly-empty list of [sectref {ITEM DESCRIPTION} {item descriptions}]. +Any unselected items in [arg select] are added to the selection, +and any selected items in [arg deselect] are removed from the selection (except +for those items which are also in [arg select]). +A [const ] event is generated if any items were selected or deselected. [list_end] [call [arg pathName] [cmd style] [arg option] [opt [arg element]] \ [opt [arg {arg arg ...}]]] -This command is used to manipulate styles, which could be considered -as a geometry manager for the elements of one item. +This command is used to manipulate styles, which can be thought of +as a geometry manager for elements. The exact behavior of the command depends on the [arg option] argument that follows the [cmd style] argument. The following forms of the command are supported: @@ -2027,8 +2027,7 @@ The following options are supported for columns: [list_begin opt] [opt_def [option -arrow] [arg direction]] -Indicates whether or not an arrow should be drawn in the column header -to the right of the column title. +Indicates whether or not an arrow should be drawn in the column header. [arg Direction] must have one of the values [const none] (the default), [const up], or [const down]. @@ -2042,7 +2041,7 @@ use to draw the arrow if this column's -arrow option is not [const none]. If an image is specified for a certain state, it overrides the -arrowbitmap option. [opt_def [option -arrowside] [arg side]] -Indicates on which side an arrow should be drawn, if at all. +Indicates on which side of the bitmap/image/text the arrow should be drawn. [arg Side] must be either [const left] or [const right] (the default). [opt_def [option -arrowgravity] [arg side]] @@ -2052,7 +2051,7 @@ if there is more space available for drawing the arrow then needed. [opt_def [option -arrowpadx] [arg amount]] [arg Amount] specifies how much padding to -leave on the left and right side of the arrow. +leave on the left and right of the arrow. [arg Amount] may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2098,21 +2097,21 @@ This option overrides the [option -bitmap] column option. [opt_def [option -imagepadx] [arg amount]] [arg Amount] specifies how much padding to -leave on the left and right side of the image. +leave on the left and right of the image (or bitmap). [arg Amount] may be a list of two values to specify padding for left and right separately; it defaults to 6. [opt_def [option -imagepady] [arg amount]] [arg Amount] specifies how much padding to -leave on the top and bottom of the image. +leave on the top and bottom of the image (or bitmap). [arg Amount] may be a list of two values to specify padding for top and bottom separately; it defaults to 0. [opt_def [option -itembackground] [arg colorList]] -Specifies a list of colors, which should be used as -alternating background color for the items of this column. +Specifies a list of zero or more colors, which are used as +alternating background colors for items in this column. See also the [option -backgroundmode] widget option for more on this. [opt_def [option -justify] [arg justification]] @@ -2154,7 +2153,7 @@ Defines a unique name for the column which can be used whenever a column must be specified. [opt_def [option -text] [arg text]] -Specifies a text to be displayed inside the column title. +Specifies a text string to be displayed as the column title. [opt_def [option -textcolor] [arg color]] Specifies a color, which should be used as foreground color @@ -2171,7 +2170,7 @@ of text. [opt_def [option -textpadx] [arg amount]] [arg Amount] specifies how much padding to -leave on the left and right side of the text. +leave on the left and right of the text. [arg Amount] may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2261,17 +2260,16 @@ is true. [list_end] [section STATES] -A state consists basically of just a string: its [arg stateName]. -For every item a set of these states is managed, -which means that every item can have every state switched on or off. +For every item a set of boolean states is managed. These states play an +integral role in the appearance of each item. The following states are predefined for every item: [list_begin definitions] [lst_item [const active]] -At every time this state is set for exactly one item, -which therefore is called the active item. +At all times this state is set for exactly one item. The active item is +used with keyboard navigation. When the treectrl widget is created or when the active item is deleted, -the root item will become the active element. +the root item will become the active item. This state can be modified by means of the widget command [cmd activate]. [lst_item [const enabled]] @@ -2280,9 +2278,9 @@ It cannot be modified. [lst_item [const focus]] This state is set for every item, -if the treectrl widget has currently the focus. +if the treectrl widget currently has the focus. It cannot be modified by means of a widget command, -but is maintained as reaction of a or event. +but is maintained in reaction to the and events. [lst_item [const open]] If this state is switched on, @@ -2291,32 +2289,18 @@ the descendants of the item are displayed 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 +For a new item this state is switched on by default. +This state can be modified by means of the widget commands [cmd {item expand}], [cmd {item collapse}], or [cmd {item toggle}]. [lst_item [const selected]] -This state is set for every item, which is included in the selection. +This state is set for every item included in the selection. It can be modified by means of the widget command [cmd selection]. [list_end] [para] By means of the [cmd {state define}] widget command -up to 27 additional [arg stateName]s can be defined. - -[para] -Some widget commands expect a [arg stateDesc] argument, -which is a [arg stateName] -optionally preceded by an exclamation mark ([const !]). -If the [arg stateName] has no leading [const !] -it describes a currently switched on state, -if it has a leading [const !] it describes a currently switched off state. - -[para] -Some widget commands expect a [arg statePattern] argument, -which should be a non empty list of [arg stateDesc]s. -The pattern matches, if for every element of the list -the [arg stateDesc] describes the same state as the item currently has. +up to 27 additional states can be defined. [section {PER-STATE OPTIONS}] @@ -2684,6 +2668,9 @@ Indicates the item nearest to the point given by [arg x] and [arg y]. [lst_item "[const rnc] [arg {row column}]"] Indicates the item in the given [arg row] and [arg column]. +The row and column corresponds to +the on-screen arrangement of items as determined by the -orient and -wrap +options. You can memorize [const rnc] as abbreviation of "row 'n' column". [lst_item [const root]] diff --git a/doc/treectrl.n b/doc/treectrl.n index 38fd512..2aac72e 100644 --- a/doc/treectrl.n +++ b/doc/treectrl.n @@ -6,14 +6,14 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" $Id: treectrl.n,v 1.46 2005/07/15 01:39:20 treectrl Exp $ +'\" $Id: treectrl.n,v 1.47 2005/07/23 00:35:21 treectrl Exp $ .so man.macros -.TH "treectrl" n 2.0 treectrl "Tk Commands" +.TH "treectrl" n 2.1 treectrl "Tk Commands" .BS .SH "NAME" treectrl \- Create and manipulate hierarchical multicolumn widgets .SH "SYNOPSIS" -package require \fBtreectrl 2.0\fR +package require \fBtreectrl 2.1\fR .sp \fBtreectrl\fR \fIpathName\fR ?\fIoptions\fR? .sp @@ -189,7 +189,7 @@ package require \fBtreectrl 2.0\fR .sp \fIpathName\fR \fBitem state get\fR \fIitemDesc\fR ?\fIstateName\fR? .sp -\fIpathName\fR \fBitem state set\fR \fIitemDesc\fR ?\fIlastItem\fR? ?\fIstateDescList\fR? +\fIpathName\fR \fBitem state set\fR \fIitemDesc\fR ?\fIlastItem\fR? \fIstateDescList\fR .sp \fIpathName\fR \fBitem style\fR \fIcommand\fR \fIitemDesc\fR ?\fIarg ...\fR? .sp @@ -569,7 +569,7 @@ Database Class: \fBHeight\fR .IP Specifies the desired height for the window in any of the forms acceptable to \fBTk_GetPixels\fR. -The default is 200 pixel. +The default is 200 pixels. If this option is less than or equal to zero then the window will not request any size at all. .LP @@ -625,14 +625,9 @@ Database Class: \fBItemWidth\fR .fi .IP Specifies a fixed width for every item in any of the forms acceptable to \fBTk_GetPixels\fR. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "". +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). .LP .nf .ta 6c @@ -643,16 +638,10 @@ Database Class: \fBItemWidthEqual\fR .fi .IP Specifies a boolean that says whether all items should have the same width. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, and -the treectrl's -itemwidth option is <= 0, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -itemwidth option is <= 0. +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). +If the -itemwidth option is specified, then this option has no effect. .LP .nf .ta 6c @@ -663,16 +652,10 @@ Database Class: \fBItemWidthMultiple\fR .fi .IP Specifies a screen distance that every item's width will be evenly divisible by in any of the forms acceptable to \fBTk_GetPixels\fR. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, and -the treectrl's -itemwidth option is <= 0, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -itemwidth option is <= 0. +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). +If the -itemwidth option is specified, then this option has no effect. .LP .nf .ta 6c @@ -833,9 +816,9 @@ Database Class: \fBTreeColumn\fR .fi .IP -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. +Specifies a \fBcolumn description\fR that determines which +column displays the buttons and lines. +The default is unspecified. .LP .nf .ta 6c @@ -871,18 +854,18 @@ Database Class: \fBWrap\fR .fi .IP -Specifies how to arrange items inside treectrl's window. -The value must be an empty string, \fBwindow\fR, -or a list with an integer as first element -and either \fBitems\fR or \fBpixels\fR 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 \fBwindow\fR mode a screen line break may occur after any element; -in \fBitems\fR mode a line break will only be made after the specified -number of items; -in \fBpixels\fR mode a line break will only be made after the -specified screen distance is reached. +Specifies whether items are arranged in a 1- or 2-dimensional layout. +If the value is an empty string (the default), then items are arranged from top +to bottom (-orient vertical) or from left to right (-orient horizontal) in +a 1-dimensional layout. +If the value is "\fIN\fR \fBitems\fR", then a no more than \fIN\fR items will appear in +a vertical group (-orient vertical) or horizontal group (-orient horizontal). +If the value is "\fIN\fR \fBpixels\fR", then a no vertical group of items will be +taller than \fIN\fR pixels (-orient vertical) or no horizontal group of items will +be wider than \fIN\fR pixels (-orient horizontal). +If the value is \fBwindow\fR, then a no vertical group of items will be +taller than the window (-orient vertical) or no horizontal group of items will +be wider than the window (-orient horizontal). .LP .nf .ta 6c @@ -1000,10 +983,10 @@ The following forms of the command are supported: .RS .TP \fIpathName\fR \fBcolumn bbox\fR \fIcolumn\fR -Returns a list with four elements giving an approximate bounding box +Returns a list with four elements giving the bounding box for the column header specified by \fIcolumn\fR. -If the treectrl is configured to don't display the column headers -by means of the \fB-showheader\fR option, +If the treectrl is configured not to display the column headers +by means of the \fB-showheader\fR option, then an empty list is returned instead. .TP \fIpathName\fR \fBcolumn cget\fR \fIcolumn\fR \fIoption\fR @@ -1158,10 +1141,10 @@ this case the command returns an empty string. command. .TP \fIpathName\fR \fBcontentbox\fR -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. +Returns a list with four elements giving the bounding box +for the space used to display the items, +i.e. the space of the treectrl window without +the surrounding borders or the column headers. .TP \fIpathName\fR \fBdebug\fR \fIoption\fR ?\fIarg arg ...\fR? This command is used to facilitate debugging of the treectrl widget. @@ -1228,7 +1211,7 @@ debugging options \fB-enable\fR and \fB-display\fR are switched on. .TP \fIpathName\fR \fBdebug dinfo\fR For every of the treectrl widget -a line with some internal valuess info about all items +a line with some internal values info about all items is printed to stdout. The command returns the empty string. .TP @@ -1411,12 +1394,13 @@ The following forms of the command are supported: .RS .TP \fIpathName\fR \fBitem ancestors\fR \fIitemDesc\fR -Returns a list containing the numerical indexes of all ancestors -of the item specified by \fIitemDesc\fR from its parent up to the -root item. +Returns a list containing the item ids of the ancestors +of the item specified by \fIitemDesc\fR. The first list value is the parent, +the second is the parent's parent, an so on. The last list value will be the +root item if \fIitemDesc\fR is a descendant of the root item. .TP \fIpathName\fR \fBitem bbox\fR \fIitemDesc\fR ?\fIcolumn\fR? ?\fIelement\fR? -Returns a list with four elements giving an approximate bounding box +Returns a list with four elements giving the bounding box for the item described by \fIitemDesc\fR. If no further argument is specified, the bbox spans the area of the item over all columns. If a \fIcolumn\fR is specified, only the area of the item @@ -1430,7 +1414,7 @@ Returns the current value of the configuration option for the item specified by values accepted by the \fBitem configure\fR command. .TP \fIpathName\fR \fBitem children\fR \fIitemDesc\fR -Returns a list containing the numerical indexes of all children +Returns a list containing the item ids of all children of the item specified by \fIitemDesc\fR in the correct order from the first child to the last child. .TP @@ -1558,9 +1542,10 @@ and b) each ancestor's \fB-visible\fR option is true .TP \fIpathName\fR \fBitem delete\fR \fIfirst\fR ?\fIlast\fR? Deletes the specified item(s). -\fIFirst\fR and \fIlast\fR must be the string \fBall\fR or an \fIitemDesc\fR. -If either \fIfirst\fR or \fIlast\fR is specified as \fBall\fR, all items are -deleted; if \fIfirst\fR is specified as \fIitemDesc\fR and \fIlast\fR isn't +\fIFirst\fR and \fIlast\fR must be the string \fBall\fR or a valid +\fBitem description\fR. +If either \fIfirst\fR or \fIlast\fR is specified as \fBall\fR, then all items are +deleted. If \fIfirst\fR is specified and \fIlast\fR isn't specified, the item described by \fIfirst\fR is deleted. If both \fIfirst\fR and \fIlast\fR are specified, they must decribe items with a common ancestor; @@ -1571,6 +1556,12 @@ If the current \fBactive\fR item is deleted, the root item becomes the new activ If the current selection \fBanchor\fR item is deleted, the root item becomes the new anchor item. There is no way to delete the root item of the treectrl widget; in all cases the specification of the root item is ignored. +.sp +For each call to this command, two events may be generated. +If any of the deleted items are selected, then a \fB\fR event +is generated just before the items are deleted. +If any items were actually deleted, then an \fB\fR event event is generated just before the items +are deleted. .TP \fIpathName\fR \fBitem dump\fR \fIitemDesc\fR Returns a list with six elements in the form @@ -1651,15 +1642,15 @@ an \fB\fR event before the item state is changed, and an \fB\fR event after the item state was changed. .TP \fIpathName\fR \fBitem firstchild\fR \fIparent\fR ?\fIchild\fR? -If \fIchild\fR is not specified, returns the numerical index of the first +If \fIchild\fR is not specified, returns the item id of the first child of the item described by \fIparent\fR. If \fIchild\fR is specified, it must described an item that is not an ancestor of \fIparent\fR. Then it will become the new first child of \fIparent\fR. .TP \fIpathName\fR \fBitem id\fR \fIitemDesc\fR -This command resolves the item description \fIitemDesc\fR into a unique item -identifier (see \fBITEM DESCRIPTION\fR below). If the item described by +This command resolves the \fBitem description\fR \fIitemDesc\fR into a unique item +identifier. If the item described by \fIitemDesc\fR doesn't exist, this command returns an empty string. .TP \fIpathName\fR \fBitem image\fR \fIitemDesc\fR ?\fIcolumn\fR? ?\fIimage\fR? ?\fIcolumn image ...\fR? @@ -1679,20 +1670,20 @@ Returns 1 if the item described by \fIitemDesc\fR is a direct or indirect parent of the item decribed by \fIdescendant\fR, 0 otherwise. .TP \fIpathName\fR \fBitem isopen\fR \fIitemDesc\fR -Returns 1, if the item described by \fIitemDesc\fR has cuurently the +Returns 1 if the item described by \fIitemDesc\fR has the state \fBopen\fR switched on, 0 otherwise. .TP \fIpathName\fR \fBitem lastchild\fR \fIparent\fR ?\fIchild\fR? -If \fIchild\fR is not specified, returns the numerical index of the last +If \fIchild\fR is not specified, returns the item id of the last child of the item described by \fIparent\fR. -If \fIchild\fR is specified, it must described an item +If \fIchild\fR is specified, it must describe an item that is not an ancestor of \fIparent\fR. Then it will become the new last child of \fIparent\fR. .TP \fIpathName\fR \fBitem nextsibling\fR \fIsibling\fR ?\fInext\fR? -If \fInext\fR is not specified, returns the numerical index of the next +If \fInext\fR is not specified, returns the item id of the next sibling of the item described by \fIsibling\fR. -If \fInext\fR is specified, it must described an item +If \fInext\fR is specified, it must describe an item that is not an ancestor of \fIsibling\fR. Then it will become the new next sibling of \fIsibling\fR. .TP @@ -1709,31 +1700,34 @@ result of this command is the row the item falls in. If the optional argument is not visible. .TP \fIpathName\fR \fBitem parent\fR \fIitemDesc\fR -Returns the numerical index of the parent of the item +Returns the item id of the parent of the item described by \fIitemDesc\fR. .TP \fIpathName\fR \fBitem prevsibling\fR \fIsibling\fR ?\fIprev\fR? -If \fIprev\fR is not specified, returns the numerical index of the previous +If \fIprev\fR is not specified, returns the item id of the previous sibling of the item described by \fIsibling\fR. -If \fIprev\fR is specified, it must described an item +If \fIprev\fR is specified, it must describe an item that is not an ancestor of \fIsibling\fR. Then it will become the new previous sibling of \fIsibling\fR. .TP \fIpathName\fR \fBitem range\fR \fIfirst\fR \fIlast\fR -Returns a list containing the unique identifiers of all items +Returns a list containing the item ids of all items in the range between \fIfirst\fR and \fIlast\fR, inclusive. The order between \fIfirst\fR and \fIlast\fR doesn't matter, -and the result is always ordered by the increasing index of the items. +and the result is always sorted by the increasing order of the items (as +returned by the \fBitem order\fR command). The items specified by \fIfirst\fR and \fIlast\fR must share a common ancestor. .TP \fIpathName\fR \fBitem remove\fR \fIitemDesc\fR Removes the item described by \fIitemDesc\fR -from the children list of its father, so that it will become an orphan. +from the list of children of its parent, so that it will become an orphan. .TP \fIpathName\fR \fBitem rnc\fR \fIitemDesc\fR Returns a list of two integers, which corresponds to the row and column -of the item described by \fIitemDesc\fR. +of the item described by \fIitemDesc\fR. The row and column corresponds to +the on-screen arrangement of items as determined by the -orient and -wrap +options. If the item is not displayed, this command returns an empty string. .TP \fIpathName\fR \fBitem sort\fR \fIitemDesc\fR ?\fIoption ...\fR? Sorts the children of the item described by \fIitemDesc\fR, @@ -1809,28 +1803,30 @@ The following forms of the command are supported: .RS .TP \fIpathName\fR \fBitem state forcolumn\fR \fIitemDesc\fR \fIcolumn\fR ?\fIstateDescList\fR? -Just like \fBitem state set\fR but manipulates user-defined states for a single -item column, not the item as a whole. +Just like \fBitem state set\fR but manipulates dynamic states for a single +item column, not the item as a whole. If \fIstateDescList\fR is unspecified, +this command returns a list containing the names of all the dynamic states +which are switched on in \fIcolumn\fR. .TP \fIpathName\fR \fBitem state get\fR \fIitemDesc\fR ?\fIstateName\fR? If no \fIstateName\fR is specified, returns a list containing -the names of all (predefined and user defined) states +the names of all (static and dynamic) states which are currently switched on for the item described by \fIitemDesc\fR. If a \fIstateName\fR is specified, 1 is returned if the specified state is currently switched on for the item, 0 otherwise. .TP -\fIpathName\fR \fBitem state set\fR \fIitemDesc\fR ?\fIlastItem\fR? ?\fIstateDescList\fR? +\fIpathName\fR \fBitem state set\fR \fIitemDesc\fR ?\fIlastItem\fR? \fIstateDescList\fR Every element of \fIstateDescList\fR -must describe a user defined state (see \fBSTATES\fR below), -with the particularity that the state name may have also a leading \fB~\fR. +must be the name of a dynamic state (see \fBSTATES\fR below), +optionally preceded by a \fB~\fR or \fB!\fR character. Every state with a leading \fB!\fR will be switched off for the item described by \fIitemDesc\fR, every state with a leading \fB~\fR will be toggled, and every state without leading \fB!\fR or \fB~\fR will be switched on. If \fIlastItem\fR is specified, the state changes will be made for all items in the range betwen \fIitemDesc\fR and \fIlastItem\fR. -\fIItemDesc\fR may be the string \fBall\fR, +If \fIItemDesc\fR is the string \fBall\fR, then the state changes are made for all items of the treectrl widget. .RE .TP @@ -1842,9 +1838,10 @@ The following forms of the command are supported: .RS .TP \fIpathName\fR \fBitem style elements\fR \fIitemDesc\fR \fIcolumn\fR -A list is returned -containing the currently defined elements of the style, -which is set for the item described by \fIitemDesc\fR in \fIcolumn\fR. +This command returns a list containing the names of elements which were +configured by the \fBitem element configure\fR command for the item +described by \fIitemDesc\fR in \fIcolumn\fR. If there is no style assigned +to \fIcolumn\fR an error is returned. .TP \fIpathName\fR \fBitem style map\fR \fIitemDesc\fR \fIcolumn\fR \fIstyle\fR \fImap\fR Like the \fBitem style set\fR command, this command may be used to assign a @@ -2139,17 +2136,17 @@ Deprecated. Use the \fBcolumn count\fR command instead. Deprecated. Use the \fBitem count\fR command instead. .TP \fIpathName\fR \fBorphans\fR -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 \fBitem remove\fR widget command. +Returns a list containing the item ids of all items +which have no parent. +When an item is created, it has no parent by default, +and can later become an orphan +by means of the \fBitem remove\fR widget command. The root item is not returned. .TP \fIpathName\fR \fBrange\fR \fIfirst\fR \fIlast\fR Deprecated. Use the \fBitem range\fR command instead. .TP \fIpathName\fR \fBstate\fR \fIoption\fR ?\fIstateName\fR? -This command is used to manipulate the list of user defined states, +This command is used to manipulate the list of user-defined states, see section \fBSTATES\fR below. The exact behavior of the command depends on the \fIoption\fR argument that follows the \fBstate\fR argument. @@ -2158,20 +2155,20 @@ The following forms of the command are supported: .TP \fIpathName\fR \fBstate define\fR \fIstateName\fR Defines a new state with the name \fIstateName\fR, -which must not be the name of a predefined or already user defined state. +which must not be the name of an existing state. .TP \fIpathName\fR \fBstate linkage\fR \fIstateName\fR Returns a string indicating -whether the specified state is user defined +whether the specified state is user-defined by means of the \fBstate define\fR widget command (\fBdynamic\fR) or predefined by the treectrl widget itself (\fBstatic\fR). .TP \fIpathName\fR \fBstate names\fR -Returns a list containing the names of all user defined states. +Returns a list containing the names of all user-defined states. .TP \fIpathName\fR \fBstate undefine\fR ?\fIstateName ...\fR? -Every \fIstateName\fR must be the name of a user defined state. -Removes this state from the list of user defined states. +Every \fIstateName\fR must be the name of a user-defined state. +Removes this state from the list of user-defined states. .RE .TP \fIpathName\fR \fBsee\fR \fIitemDesc\fR @@ -2189,13 +2186,14 @@ It has several forms, depending on \fIoption\fR: .TP \fIpathName\fR \fBselection add\fR \fIfirst\fR ?\fIlast\fR? \fIFirst\fR and \fIlast\fR (if specified) -must be the string \fBall\fR or an \fIitemDesc\fR. -Selects all of the items in the range between -\fIfirst\fR and \fIlast\fR, inclusive, +must be the string \fBall\fR or a valid \fBitem description\fR. +Adds every unselected item in the range between +\fIfirst\fR and \fIlast\fR, inclusive, to the selection without affecting the selection state of items outside that range. If one of the arguments is the string \fBall\fR, -all items of the treectrl widget are added to the selection instead. -A \fB\fR event is generated. +every unselected item in the treectrl widget is added to the selection. +A \fB\fR event is generated if any items were added to the +selection. .TP \fIpathName\fR \fBselection anchor\fR ?\fIitemDesc\fR? If \fIitemDesc\fR is specified, @@ -2208,44 +2206,42 @@ Returns the numerical id of the selection anchor item. .TP \fIpathName\fR \fBselection clear\fR ?\fIfirst\fR? ?\fIlast\fR? \fIFirst\fR and \fIlast\fR (if specified) -must be the string \fBall\fR or an \fIitemDesc\fR. +must be the string \fBall\fR or a valid \fBitem description\fR. If any of the items between \fIfirst\fR and \fIlast\fR (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 \fBall\fR, -the selection is completely cleared instead. -A \fB\fR event is generated. +If no additional arguments are given, +or if one of the arguments is the string \fBall\fR, +then all items are removed from the selection. +A \fB\fR event is generated if any items were removed from the +selection. .TP \fIpathName\fR \fBselection count\fR Returns an integer indicating the number of items in the treectrl that are currently selected. .TP \fIpathName\fR \fBselection get\fR -Returns a list containing the numerical ids of +Returns a list containing the item 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. .TP \fIpathName\fR \fBselection includes\fR \fIitemDesc\fR -Returns 1 if the item indicated by \fIitemDesc\fR is currently +Returns 1 if the item described by \fIitemDesc\fR is currently selected, 0 if it isn't. .TP \fIpathName\fR \fBselection modify\fR \fIselect\fR \fIdeselect\fR Both arguments \fIselect\fR and \fIdeselect\fR must be -the string \fBall\fR or a possibly empty list of \fIitemDesc\fRs. -Selects all of the items described by \fIselect\fR, -then deselects all items described by \fIdeselect\fR, -without affecting the selection state of any item -not mentioned in both arguments. -If one item is described in both arguments \fIselect\fR and \fIdeselect\fR, -it is added to the selection. -A \fB\fR event is generated. +the string \fBall\fR or a possibly-empty list of \fBitem descriptions\fR. +Any unselected items in \fIselect\fR are added to the selection, +and any selected items in \fIdeselect\fR are removed from the selection (except +for those items which are also in \fIselect\fR). +A \fB\fR event is generated if any items were selected or deselected. .RE .TP \fIpathName\fR \fBstyle\fR \fIoption\fR ?\fIelement\fR? ?\fIarg arg ...\fR? -This command is used to manipulate styles, which could be considered -as a geometry manager for the elements of one item. +This command is used to manipulate styles, which can be thought of +as a geometry manager for elements. The exact behavior of the command depends on the \fIoption\fR argument that follows the \fBstyle\fR argument. The following forms of the command are supported: @@ -2526,8 +2522,7 @@ do not use item state names. The following options are supported for columns: .TP \fB\fB-arrow\fR\fR \fIdirection\fR -Indicates whether or not an arrow should be drawn in the column header -to the right of the column title. +Indicates whether or not an arrow should be drawn in the column header. \fIDirection\fR must have one of the values \fBnone\fR (the default), \fBup\fR, or \fBdown\fR. .TP @@ -2541,7 +2536,7 @@ use to draw the arrow if this column's -arrow option is not \fBnone\fR. If an image is specified for a certain state, it overrides the -arrowbitmap option. .TP \fB\fB-arrowside\fR\fR \fIside\fR -Indicates on which side an arrow should be drawn, if at all. +Indicates on which side of the bitmap/image/text the arrow should be drawn. \fISide\fR must be either \fBleft\fR or \fBright\fR (the default). .TP \fB\fB-arrowgravity\fR\fR \fIside\fR @@ -2551,7 +2546,7 @@ if there is more space available for drawing the arrow then needed. .TP \fB\fB-arrowpadx\fR\fR \fIamount\fR \fIAmount\fR specifies how much padding to -leave on the left and right side of the arrow. +leave on the left and right of the arrow. \fIAmount\fR may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2597,21 +2592,21 @@ This option overrides the \fB-bitmap\fR column option. .TP \fB\fB-imagepadx\fR\fR \fIamount\fR \fIAmount\fR specifies how much padding to -leave on the left and right side of the image. +leave on the left and right of the image (or bitmap). \fIAmount\fR may be a list of two values to specify padding for left and right separately; it defaults to 6. .TP \fB\fB-imagepady\fR\fR \fIamount\fR \fIAmount\fR specifies how much padding to -leave on the top and bottom of the image. +leave on the top and bottom of the image (or bitmap). \fIAmount\fR may be a list of two values to specify padding for top and bottom separately; it defaults to 0. .TP \fB\fB-itembackground\fR\fR \fIcolorList\fR -Specifies a list of colors, which should be used as -alternating background color for the items of this column. +Specifies a list of zero or more colors, which are used as +alternating background colors for items in this column. See also the \fB-backgroundmode\fR widget option for more on this. .TP \fB\fB-justify\fR\fR \fIjustification\fR @@ -2653,7 +2648,7 @@ Defines a unique name for the column which can be used whenever a column must be specified. .TP \fB\fB-text\fR\fR \fItext\fR -Specifies a text to be displayed inside the column title. +Specifies a text string to be displayed as the column title. .TP \fB\fB-textcolor\fR\fR \fIcolor\fR Specifies a color, which should be used as foreground color @@ -2670,7 +2665,7 @@ of text. .TP \fB\fB-textpadx\fR\fR \fIamount\fR \fIAmount\fR specifies how much padding to -leave on the left and right side of the text. +leave on the left and right of the text. \fIAmount\fR may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2750,16 +2745,15 @@ is true. Use the column to the left, or the column to the left whose -visible option is true. .SH "STATES" -A state consists basically of just a string: its \fIstateName\fR. -For every item a set of these states is managed, -which means that every item can have every state switched on or off. +For every item a set of boolean states is managed. These states play an +integral role in the appearance of each item. The following states are predefined for every item: .TP \fBactive\fR -At every time this state is set for exactly one item, -which therefore is called the active item. +At all times this state is set for exactly one item. The active item is +used with keyboard navigation. When the treectrl widget is created or when the active item is deleted, -the root item will become the active element. +the root item will become the active item. This state can be modified by means of the widget command \fBactivate\fR. .TP \fBenabled\fR @@ -2768,9 +2762,9 @@ It cannot be modified. .TP \fBfocus\fR This state is set for every item, -if the treectrl widget has currently the focus. +if the treectrl widget currently has the focus. It cannot be modified by means of a widget command, -but is maintained as reaction of a or event. +but is maintained in reaction to the and events. .TP \fBopen\fR If this state is switched on, @@ -2779,28 +2773,16 @@ the descendants of the item are displayed 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 +For a new item this state is switched on by default. +This state can be modified by means of the widget commands \fBitem expand\fR, \fBitem collapse\fR, or \fBitem toggle\fR. .TP \fBselected\fR -This state is set for every item, which is included in the selection. +This state is set for every item included in the selection. It can be modified by means of the widget command \fBselection\fR. .PP By means of the \fBstate define\fR widget command -up to 27 additional \fIstateName\fRs can be defined. -.PP -Some widget commands expect a \fIstateDesc\fR argument, -which is a \fIstateName\fR -optionally preceded by an exclamation mark (\fB!\fR). -If the \fIstateName\fR has no leading \fB!\fR -it describes a currently switched on state, -if it has a leading \fB!\fR it describes a currently switched off state. -.PP -Some widget commands expect a \fIstatePattern\fR argument, -which should be a non empty list of \fIstateDesc\fRs. -The pattern matches, if for every element of the list -the \fIstateDesc\fR describes the same state as the item currently has. +up to 27 additional states can be defined. .SH "PER-STATE OPTIONS" The visual appearance of an item can change depending on the state the item is in, such as being the active item, being included in the selection, being @@ -3145,6 +3127,9 @@ Indicates the item nearest to the point given by \fIx\fR and \fIy\fR. .TP \fBrnc\fR \fIrow column\fR Indicates the item in the given \fIrow\fR and \fIcolumn\fR. +The row and column corresponds to +the on-screen arrangement of items as determined by the -orient and -wrap +options. You can memorize \fBrnc\fR as abbreviation of "row 'n' column". .TP \fBroot\fR -- cgit v0.12

treectrl pathName ?options?

pathName activate itemDesc

pathName canvasx screenx

pathName item state command itemDesc ?arg ...?

pathName item state forcolumn itemDesc column ?stateDescList?

pathName item state get itemDesc ?stateName?

pathName item state set itemDesc ?lastItem? ?stateDescList?

pathName item state set itemDesc ?lastItem? stateDescList

pathName item style command itemDesc ?arg ...?

pathName item style elements itemDesc column

pathName item style map itemDesc column style map