From 94b54ef71ef6c2725d84a19c2c28d1ed085801fa Mon Sep 17 00:00:00 2001 From: treectrl Date: Fri, 13 May 2005 20:50:19 +0000 Subject: Bump version to 2.0 because of API changes. New "column configure all" syntax. New "column compare" command. Return value of "column create" is unique identifier. New "column delete all" syntax. Deprecated "column index". New command "column id". New command "column list". New command "column order". Deprecated "compare". Deprecated "index". New command "item compare". New command "item count". New command "item id". New command "item order" (replaces old "item index"). Deprecated "numcolumns" and "numitems". Added section COLUMN DESCRIPTION. Added section EXAMPLES with examples of column/item descriptions. --- doc/treectrl.html | 768 ++++++++++++++++++++++++++++++++---------------------- doc/treectrl.man | 229 ++++++++++++---- doc/treectrl.n | 237 +++++++++++++---- 3 files changed, 818 insertions(+), 416 deletions(-) diff --git a/doc/treectrl.html b/doc/treectrl.html index dd34d5d..90372f0 100644 --- a/doc/treectrl.html +++ b/doc/treectrl.html @@ -1,14 +1,14 @@ - treectrl - Tk Commands - -

treectrl(n) 1.2 "Tk Commands"

treectrl(n) 2.0 "Tk Commands"

NAME

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

SYNOPSIS

DESCRIPTION

@@ -674,7 +682,9 @@ for the column specified by column, This command is similar to the configure widget command except that it modifies options associated with the column specified by column instead of modifying options for the overall treectrl widget. -Column may also be the string tail to specify the tail column. +Column may be the string tail to specify the tail column. +If column is the string all, at least one option-value pair +must be given; in this case all the columns are configured. If no option is specified, the command returns a list describing all of the available options for column (see Tk_ConfigureInfo for information on the format of this list). @@ -690,30 +700,61 @@ in this case the command returns an empty string. See COLUMNS below for details on the options available for columns.

-

pathName column create ?option value ...?

pathName column compare column1 op column2

+ +From both columns the index is retrieved +(as returned from the column order widget command). +Then these indexes are compared using the operator op, which must +be either <, <=, ==, >=, >, +or !=. +The return value of this command is 1 if the comparison evaluated to true, +0 otherwise. + +

+

pathName column count

+ +Returns a decimal string giving the number of +columns created by the column create widget command which haven't been +deleted by the column delete widget command. The tail column +is not counted. + +

+

pathName column create ?option value ...?

This command creates a new column in the treectrl widget. The new column is placed to the right of all other columns (except the tail column). Any option-value arguments configure the new column according to the -column configure command. The return value is the zero-based index +column configure command. The return value is the unique identifier of the new column.

-

pathName column delete column

-Deletes the specified column from the treectrl widget. -All remaining columns of the treectrl widget will get new column numbers: -in an unchanged order, but with succesive numbers. +Deletes the specified column from the treectrl widget. If column +is the string all, all columns except the tail column are deleted.

-

pathName column index column

-This command returns a decimal string giving the column number -of the column specified by column, -which may also be the string tail to specify the tail column. +Deprecated. Use column id

-

pathName column move column before

pathName column id column

+ +This command resolves the column description column into a unique column +identifier (see COLUMN DESCRIPTION below). +If the column described by column doesn't exist, this command returns +an empty string. + +

+

pathName column list ?-visible?

+ +This command returns a list of identifiers for every column (except the tail) +from left to right. If -visible is given, only columns whose -visible +option is true are returned. + +

+

pathName column move column before

Moves the specified column to the left of the column specified by before. @@ -721,7 +762,7 @@ If before is the string tail, the column column will become the last column.

-

pathName column neededwidth column

This command returns a decimal string giving the needed width of the column specified by column. @@ -729,7 +770,16 @@ The needed width is the maximum of the width of the column header and the width of the widest currently visible item.

-

pathName column width column

pathName column order column ?-visible?

+ +This command returns a decimal string giving the position of column +in the list of columns starting from zero for the leftmost column. +If -visible is given, only columns whose -visible +option is true are considered, and -1 is returned if column's -visible +option is false. + +

+

pathName column width column

This command returns a decimal string giving the width in pixels of the column specified by column, @@ -737,18 +787,12 @@ even if the treectrl is configured to not display the column headers by means of the -showheader option. -

pathName compare itemDesc1 op itemDesc2

-From both items described by the itemDescs the index is retrieved -(as returned from the item index widget command). -Then these indexes are compared using the operator op, which must -be either <, <=, ==, >=, >, -or !=. -The return value of this command is 1 if the comparison evaulated to true, -0 otherwise. +Deprecated. Use the item compare command instead.

-

pathName configure ?option? ?value option value ...?

Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of @@ -764,7 +808,7 @@ this case the command returns an empty string. 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, @@ -772,7 +816,7 @@ i.e. the space of the treectrl widget without the surrounding borders and the column headers.

-

pathName debug option ?arg arg ...?

This command is used to facilitate debugging of the treectrl widget. The exact behavior of the command depends on the option argument @@ -781,7 +825,7 @@ The following forms of the command are supported:

pathName debug cget element option: +
pathName debug cget element option: This command returns the current value of the debugging option named option. @@ -789,7 +833,7 @@ named option. debug configure widget command.

-
pathName debug configure element ?option? ?value? ?option value ...?: +
pathName debug configure element ?option? ?value? ?option value ...?: This command is similar to the configure widget command except that it modifies debugging options @@ -845,7 +889,7 @@ Setting this option has only an effect, if the debugging options -enable and -display are switched on.

pathName debug dinfo

For every of the treectrl widget a line with some internal valuess info about all items @@ -853,12 +897,12 @@ is printed to stdout. The command returns the empty string.

-

pathName debug scroll

Returns a string useful for debugging vertical scrolling. -

pathName depth ?itemDesc?

If the additional argument itemDesc is specified, returns a decimal string giving the depth of @@ -868,7 +912,7 @@ If no itemDesc is specified, the maximum depth of all items in the treectrl widget is returned instead.

-

pathName dragimage option ?arg ...?

This command is used to manipulate the dragimage, one or more dotted lines around rectangular regions of the treectrl widget. @@ -878,7 +922,7 @@ The following forms of the command are supported:

pathName dragimage add itemDesc ?column? ?element?: +
pathName dragimage add itemDesc ?column? ?element?: Adds the shapes of the item described by itemDesc to the shapes of the dragimage. @@ -891,7 +935,7 @@ If also element is specified, only a rectangle for this one e of the specified item in the given column is added.

-
pathName dragimage cget option: +
pathName dragimage cget option: This command returns the current value of the dragimage option named option. @@ -899,13 +943,13 @@ named option. dragimage configure widget command.

-
pathName dragimage clear: +
pathName dragimage clear: Removes all shapes (if there are any) from the dragimage. This command does not modify the dragimage offset.

-
pathName dragimage configure ?option? ?value? ?option value ...?: +
pathName dragimage configure ?option? ?value? ?option value ...?: This command is similar to the configure widget command except that it modifies the dragimage options @@ -931,7 +975,7 @@ Specifies a boolean value which determines whether the dragimage should currently be visible.

pathName dragimage offset ?x y?

Returns a list containing the x and y offsets of the dragimage, if no additional arguments are specified. @@ -942,7 +986,7 @@ sets the dragimage offset to the given coordinates x and -

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

This command is used to manipulate elements (see ELEMENTS below). The exact behavior of the command depends on the option argument @@ -951,7 +995,7 @@ The following forms of the command are supported:

-
pathName element cget element option
+
pathName element cget element option
This command returns the current value of the option named option associated with the element given by element. @@ -959,7 +1003,7 @@ associated with the element given by element. element configure widget command.

-
pathName element configure element ?option? ?value? ?option value ...?
+
pathName element configure element ?option? ?value? ?option value ...?
This command is similar to the configure widget command except that it modifies options associated with the element given by element @@ -977,7 +1021,7 @@ in this case the command returns an empty string. See ELEMENTS below for details on the options available for elements.

-
pathName element create element type ?option value ...?
+
pathName element create element type ?option value ...?
Create a new elememt in pathName of type type with name element. @@ -988,7 +1032,7 @@ on the syntax of this command. This command returns the name for the new element.

-
pathName element delete ?element ...?
+
pathName element delete ?element ...?
Deletes each of the named elements and returns an empty string. If an element is deleted while it is still configured @@ -997,23 +1041,23 @@ by means of the style elements widget command, it is also removed from the element lists of these styles.

-
pathName element names
+
pathName element names
Returns a list containing the names of all existing elements.

-
pathName element type element
+
pathName element type element
Returns the type of the elements given by element, such as rect or text.
-

pathName expand ?-recurse? ?itemDesc ...?

Use item expand instead.

-

pathName identify x y

Returns a list containing some diagnostics about what is displayed at the given windows coordinates x and y. @@ -1050,14 +1094,12 @@ if the x coordinate is to the right of the elements; nothing otherwise.

-

pathName index itemDesc

-This command returns a decimal string giving the numerical id -of the item specified by itemDesc -(see ITEM DESCRIPTION below). +Deprecated. Use item id instead.

-

pathName item option ?arg ...?

This command is used to manipulate items. The exact behavior of the command depends on the option argument @@ -1066,14 +1108,14 @@ The following forms of the command are supported:

-
pathName item ancestors itemDesc
+
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.

-
pathName item bbox itemDesc ?column? ?element?
+
pathName item bbox itemDesc ?column? ?element?
Returns a list with four elements giving an approximate bounding box for the item described by itemDesc. @@ -1084,21 +1126,21 @@ the area of this element in column of the returned.

-
pathName item cget itemDesc option
+
pathName item cget itemDesc option
Returns the current value of the configuration option for the item specified by itemDesc whose name is option. Option may have any of the values accepted by the item create command when the item was created.

-
pathName item children itemDesc
+
pathName item children itemDesc
Returns a list containing the numerical indexes of all children of the item specified by itemDesc in the correct order from the first child to the last child.

-
pathName item collapse itemDesc ?-recurse?
+
pathName item collapse itemDesc ?-recurse?
Switches off the open state of the item(s) described by itemDesc. @@ -1118,7 +1160,18 @@ a <Collapse-before> event before the item state is change and a <Collapse-after> event after the item state was changed.

-
pathName item complex itemDesc list ...
+
pathName item compare itemDesc1 op itemDesc2
+ +From both items described by the itemDescs the index is retrieved +(as returned from the item order widget command). +Then these indexes are compared using the operator op, which must +be either <, <=, ==, >=, >, +or !=. +The return value of this command is 1 if the comparison evaluated to true, +0 otherwise. + +

+
pathName item complex itemDesc list ...
Modifies the elements of the item described by itemDesc. For every column of the treectrl there may be specified one list, @@ -1130,7 +1183,7 @@ The corresponding value will overwrite the value of the eleme one column in this item.

-
pathName item configure itemDesc ?option? ?value? ?option value ...?
+
pathName item configure itemDesc ?option? ?value? ?option value ...?
If no option is specified, returns a list describing all of the available options for the item given by itemDesc (see Tk_ConfigureInfo for @@ -1144,7 +1197,15 @@ and values are the same as those permissible in the item create
-
pathName item create ?option value ...?
+
pathName item count
+ +Returns a decimal string giving the number of +items created by the item create widget command which haven't been +deleted by the item delete widget command, plus 1 for the ever-present +root item. + +

+
pathName item create ?option value ...?
Creates a new item and returns its unique identifier. The new item has the states open and enabled set by default. @@ -1177,7 +1238,7 @@ 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. @@ -1195,14 +1256,14 @@ There is no way to delete the root item of the treectrl widget; in all cases the specification of the root item is ignored.

-

pathName item dump itemDesc

Returns a list with six elements in the form index index indexVis indexVis neededHeight neededHeight.

-

pathName item element command itemDesc column element ?arg ...?

This command is used to manipulate elements of the item. The exact behavior of the command depends on the command argument @@ -1211,7 +1272,7 @@ The following forms of the command are supported:

-
pathName item element actual itemDesc column element option
+
pathName item element actual itemDesc column element option
This command returns the current value of the configuration option named option associated with element inside column of the item described by @@ -1223,7 +1284,7 @@ was used. Otherwise the value of the configuration option of the underlying elem specified element (see ELEMENTS below)

-
pathName item element cget itemDesc column element option
+
pathName item element cget itemDesc column element option
This command returns the value of the option named option associated with element inside column of the item described by @@ -1232,7 +1293,7 @@ associated with element inside column of t specified element (see ELEMENTS below)

-
pathName item element configure itemDesc column element ?option? ?value? ?option value ...?
+
pathName item element configure itemDesc column element ?option? ?value? ?option value ...?
This command is similar to the configure widget command except that it modifies options associated with @@ -1251,7 +1312,7 @@ modifies the given option(s) to have the given value(s) in the in this case the command returns an empty string.
-

pathName item expand itemDesc ?-recurse?

Switches on the open state of the item(s) described by itemDesc. If the item has descendants, they are now displayed. @@ -1270,7 +1331,7 @@ an <Expand-before> event before the item state is changed and an <Expand-after> event after the item state was changed.

-

pathName item firstchild parent ?child?

If child is not specified, returns the numerical index of the first child of the item described by parent. @@ -1279,29 +1340,26 @@ that is not an ancestor of parent. Then it will become the new first child of parent.

-

pathName item index itemDesc

pathName item id itemDesc

-Returns a list of two integers, which corresponds to the row -of the item described by itemDesc, -if all items above are counted and if only the displayed items are counted. -This command should not be confused with the index widget command, -which return the invariable item id. -The index here is basically the row of the item. +This command resolves the item description itemDesc into a unique item +identifier (see ITEM DESCRIPTION below). If the item described by +itemDesc doesn't exist, this command returns an empty string.

-

pathName item isancestor itemDesc descendant

Returns 1 if the item described by itemDesc is a direct or indirect parent of the item decribed by descendant, 0 otherwise.

-

pathName item isopen itemDesc

Returns 1, if the item described by itemDesc has cuurently the state open switched on, 0 otherwise.

-

pathName item lastchild parent ?child?

If child is not specified, returns the numerical index of the last child of the item described by parent. @@ -1310,7 +1368,7 @@ 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 sibling of the item described by sibling. @@ -1319,18 +1377,29 @@ that is not an ancestor of sibling. Then it will become the new next sibling of sibling.

-

pathName item numchildren itemDesc

Returns the number of children of the item described by itemDesc.

-

pathName item parent itemDesc

pathName item order itemDesc ?-visible?

+ +This command returns the position of the item itemDesc relative to +its toplevel ancestor (usually the root item, unless the ancestor is an +orphan). If you imagine all the items flattened into a vertical list, the +result of this command is the row the item falls in. If the optional argument +-visible is given, only the items whose ancestors are expanded, and whose +-visible option is true, get counted; in this case -1 is returned if the item +is not visible. + +

+

pathName item parent itemDesc

Returns the numerical index 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 sibling of the item described by sibling. @@ -1339,19 +1408,19 @@ that is not an ancestor of sibling. Then it will become the new previous sibling of sibling.

-

pathName item remove itemDesc

Removes the item described by itemDesc from the children list of its father, 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.

-

pathName item sort itemDesc ?option ...?

Sorts the children of the item described by itemDesc, and redisplays the tree with the items in the new order. @@ -1364,7 +1433,7 @@ the order between these two limiting items doesn't matter.

The sort column can be specified by means of the -column option; -this option can be used repeatedly to define a multi column sort. +this option can be used repeatedly to define a multicolumn sort. The sorting is done by looking at the text of the element specified by the -element option, which must be a text element defined in the style of the sorting column, @@ -1422,7 +1491,7 @@ Convert to integers and use integer comparison. Convert to floating-point values and use floating comparison. -

pathName item state command itemDesc ?arg ...?

This command is used to manipulate the states of an item. The exact behavior of the command depends on the command argument @@ -1432,13 +1501,13 @@ The following forms of the command are supported:

-
pathName item state forcolumn itemDesc column ?stateDescList?
+
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.

-
pathName item state get itemDesc ?stateName ...?
+
pathName item state get itemDesc ?stateName ...?
If no stateName is specified, returns a list containing the names of all (predefined and user defined) states @@ -1448,7 +1517,7 @@ If a stateName is specified, 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), @@ -1464,7 +1533,7 @@ then the state changes are made for all items of the treectrl widget.
-

pathName item style command itemDesc ?arg ...?

This command is used to manipulate the styles of an item. The exact behavior of the command depends on the command argument @@ -1473,14 +1542,14 @@ The following forms of the command are supported:

-
pathName item style elements itemDesc column
+
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.

-
pathName item style map itemDesc column style map
+
pathName item style map itemDesc column style map
Like the item style set command, this command may be used to assign a style to a specific column of an item. Unlike item style set, this @@ -1493,7 +1562,7 @@ an element in the style specified by style. Both elementNew must be of the same type (bitmap, text etc).

-
pathName item style set itemDesc ?column? ?style? ?column style ...?
+
pathName item style set itemDesc ?column? ?style? ?column style ...?
If no column is specified, returns a list containing the names of the styles set for all columns of the item described by itemDesc. @@ -1505,7 +1574,7 @@ it must be column-style pairs; then the style(s) of item in column will be set to style.
-

pathName item text itemDesc column ?text? ?column text ...?

If no text argument is specified, returns the text of the first text element in column for the item @@ -1518,7 +1587,7 @@ this command is provided as a convenience. Use the specific text element.

-

pathName item toggle itemDesc ?-recurse?

Changes the open state of the item(s) described by itemDesc. If the state is currently switched off, @@ -1531,7 +1600,7 @@ If -recurse is specified, the state of all descendants of -

pathName marquee option ?arg ...?

This command is used to manipulate the marquee, a rectangular region of the treectrl widget @@ -1548,7 +1617,7 @@ The following forms of the command are supported:

-
pathName marquee anchor ?x y?
+
pathName marquee anchor ?x y?
Returns a list containing the x and y coordinates of the anchor, if no additional arguments are specified. @@ -1556,7 +1625,7 @@ If two coordinates are specified, sets the anchor to the given coordinates x and y.

-
pathName marquee cget option
+
pathName marquee cget option
This command returns the current value of the marquee option named option. @@ -1564,7 +1633,7 @@ named option. marquee configure widget command.

-
pathName marquee configure ?option? ?value? ?option value ...?
+
pathName marquee configure ?option? ?value? ?option value ...?
This command is similar to the configure widget command except that it modifies the marquee options @@ -1591,7 +1660,7 @@ whether the dotted line surrounding the region of the marquee should currently be visible.
-

pathName marquee coords ?x1 y1 x2 y2?

Returns a list containing the x and y coordinates of the anchor followed by the x and y coordinates of the corner, @@ -1601,7 +1670,7 @@ sets the anchor to the given coordinates x1 and x2 and y2.

-

pathName marquee corner ?x y?

Returns a list containing the x and y coordinates of the corner, if no additional arguments are specified. @@ -1609,7 +1678,7 @@ If two coordinates are specified, sets the corner to the given coordinates x and y.

-

pathName marquee identify

Returns a list with information about the items inside the marquee. The list has as elements a list itself @@ -1623,7 +1692,7 @@ if there are any. -

pathName notify option ?arg ...?

Many Tk widgets communicate with the outside world via -command callbacks and/or virtual events. For example, the Text widget @@ -1639,7 +1708,7 @@ The following forms of the command are supported:

-
pathName notify bind ?object? ?pattern? ?+??script?
+
pathName notify bind ?object? ?pattern? ?+??script?
This command associates Tcl scripts with events generated by a treectrl widget. @@ -1668,7 +1737,7 @@ for a window; otherwise it may be an arbitrary string. Unlike the regular that window is destroyed.

-
pathName notify configure object pattern ?option? ?value? ?option value ...?
+
pathName notify configure object pattern ?option? ?value? ?option value ...?
This command sets and retrieves options for bindings created by the notify bind command. @@ -1693,7 +1762,7 @@ a binding script will not be evaluated when the corresponding event is generated.
-

pathName notify detailnames eventName

Returns a list containing the names of all details, which are installed for the event with the name eventName @@ -1701,14 +1770,14 @@ by means of the notify install widget command or by the treectrl widget itself.

-

pathName notify eventnames

Returns a list containing the names of all events, which are installed by means of the notify install widget command or by the treectrl widget itself.

-

pathName notify generate pattern ?charMap? ?percentsCommand?

This command causes the treectrl widget to generate an event. This command is typically used to generate dynamic events created by the notify install @@ -1734,7 +1803,7 @@ command is available, then all %-substitution is done using charM See notify install for a description of percentsCommand.

-

pathName notify install pattern ?percentsCommand?

This command installs a new event or detail specified by pattern. Events created by this command are called dynamic, @@ -1769,19 +1838,19 @@ by itself. or an error if the event is not dynamic.

-

pathName notify install detail eventName detail ?percentsCommand?

This command is for backward compatibility only. Use notify install with a pattern of <eventName-detail> instead.

-

pathName notify install event eventName ?percentsCommand?

This command is for backward compatibility only. Use notify install with a pattern of <eventName> instead.

-

pathName notify linkage pattern

Returns a string indicating whether the specified event or detail is created @@ -1789,51 +1858,43 @@ by means of the notify install widget command (dynami or by the treectrl widget itself (static).

-

pathName notify linkage eventName ?detail?

This form of this command is for backward compatibility only. Use notify linkage with a pattern of <eventName> or <eventName-detail> instead.

-

pathName notify uninstall pattern

If the event or detail specified by pattern is static (i.e. created by the treectrl widget itself), an error is generated. Otherwise the dynamic event or detail is removed.

-

pathName notify uninstall detail eventName detail

This command is for backward compatibility only. Use notify uninstall with a pattern of <eventName-detail> instead.

-

pathName notify uninstall event eventName

This command is for backward compatibility only. Use notify uninstall with a pattern of <eventName> instead. -

pathName numcolumns

-Returns a decimal string giving the number of -columns created by the column create widget command which haven't been -deleted by the column delete widget command. The tail column -is not counted. +Deprecated. Use the column count command instead.

-

pathName numitems

-Returns a decimal string giving the number of -items created by the item create widget command which haven't been -deleted by the item delete widget command. -This number is always positive, -since a newly created treectrl widget has already the root item, -which cannot be deleted. +Deprecated. Use the item count command instead.

-

pathName orphans

Returns a list containing the numerical ids of all items which has no parent item. @@ -1842,7 +1903,7 @@ and can later become an orphan again by means of the item remove widget command.

-

pathName range first last

First and last must be an itemDesc. Returns a list containing the numerical ids of all items @@ -1851,7 +1912,7 @@ The order between first and last doesn't m and the result is always ordered by the increasing index of the items.

-

pathName state option ?stateName?

This command is used to manipulate the list of user defined states, see section STATES below. @@ -1861,13 +1922,13 @@ The following forms of the command are supported:

-
pathName state define stateName
+
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.

-
pathName state linkage stateName
+
pathName state linkage stateName
Returns a string indicating whether the specified state is user defined @@ -1875,18 +1936,18 @@ by means of the state define widget command (dynamic< or predefined by the treectrl widget itself (static).

-
pathName state names
+
pathName state names
Returns a list containing the names of all user defined states.

-
pathName state undefine ?stateName ...?
+
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.
-

pathName see itemDesc

Adjust the view in the treectrl so that the item described by itemDesc is visible. @@ -1896,14 +1957,14 @@ and the corresponding <Scroll-x> and/or <Scrol events are generated.

-

pathName selection option arg

This command is used to adjust the selection within a treectrl. It has several forms, depending on option:

-
pathName selection add first ?last?
+
pathName selection add first ?last?
First and last (if specified) must be the string all or an itemDesc. @@ -1915,7 +1976,7 @@ all items of the treectrl widget are added to the selection instead. A <Selection> event is generated.

-
pathName selection anchor ?itemDesc?
+
pathName selection anchor ?itemDesc?
If itemDesc is specified, the selection anchor is set to the described item. @@ -1926,7 +1987,7 @@ This command doesn't modify the selection state of any item. Returns the numerical id of the selection anchor item.

-
pathName selection clear ?first? ?last?
+
pathName selection clear ?first? ?last?
First and last (if specified) must be the string all or an itemDesc. @@ -1939,13 +2000,13 @@ the selection is completely cleared instead. A <Selection> event is generated.

-
pathName selection count
+
pathName selection count
Returns an integer indicating the number of items in the treectrl that are currently selected.

-
pathName selection get
+
pathName selection get
Returns a list containing the numerical ids of all of the items in the treectrl that are currently selected. @@ -1953,13 +2014,13 @@ If there are no items selected in the treectrl then an empty string is returned.

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

-
pathName selection modify select deselect
+
pathName selection modify select deselect
Both arguments select and deselect must be the string all or a possibly empty list of itemDescs. @@ -1972,7 +2033,7 @@ it is added to the selection. A <Selection> event is generated.
-

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. @@ -1982,7 +2043,7 @@ The following forms of the command are supported:

-
pathName style cget style option
+
pathName style cget style option
This command returns the current value of the option named option associated with the style given by style. @@ -1990,7 +2051,7 @@ associated with the style given by style. style configure widget command.

-
pathName style configure style ?option? ?value? ?option value ...?
+
pathName style configure style ?option? ?value? ?option value ...?
This command is similar to the configure widget command except that it modifies options associated with the style given by style @@ -2019,7 +2080,7 @@ Must be either horizontal (the default) or vertical or an abbreviation of one of these.
-

pathName style create style ?option value ...?

Create a new style in pathName with name style. After style there may be any number of option-value @@ -2030,7 +2091,7 @@ configuration. Returns the name of the new style.

-

pathName style delete ?style ...?

Deletes each of the named styles and returns an empty string. If a style is deleted while it is still used to display @@ -2038,7 +2099,7 @@ one or more items, it is also removed from the style list of these items.

-

pathName style elements style ?elementList?

Specifies the elements which should be layed out by this style. Each element of elementList must be the name of an element @@ -2053,7 +2114,7 @@ If the elementList argument is not specified, a list is retur containing the currently defined elements of style.

-

pathName style layout style element ?option? ?value? ?option value ...?

This command is similar to the configure widget command except that it modifies options used by style for laying out element @@ -2123,17 +2184,17 @@ Specifies whether the element should be positioned by themselves, i.e. independent from the other elements. -

pathName style names

Returns a list containing the names of all existing styles. -

pathName toggle ?-recurse? ?itemDesc ...?

Use item toggle instead.

-

pathName xview ?args?

This command is used to query and change the horizontal position of the information displayed in the treectrl's window. @@ -2141,7 +2202,7 @@ It can take any of the following forms:

-
pathName xview
+
pathName xview
Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe @@ -2154,7 +2215,7 @@ These are the same values passed to scrollbars via the -xscrollcommand
-
pathName xview moveto fraction
+
pathName xview moveto fraction
Adjusts the view in the window so that fraction of the total width of the tree is off-screen to the left. @@ -2162,7 +2223,7 @@ total width of the tree is off-screen to the left. A <Scroll-x> event is generated.

-
pathName xview scroll number what
+
pathName xview scroll number what
This command shifts the view in the window left or right according to number and what. @@ -2180,7 +2241,7 @@ becomes visible. A <Scroll-x> event is generated.
-

pathName yview ?args?

This command is used to query and change the vertical position of the information displayed in the treectrl's window. @@ -2188,7 +2249,7 @@ It can take any of the following forms:

-
pathName yview
+
pathName yview
Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe @@ -2199,7 +2260,7 @@ These are the same values passed to scrollbars via the -yscrollcommand
-
pathName yview moveto fraction
+
pathName yview moveto fraction
Adjusts the view in the window so that fraction of the tree's area is off-screen to the top. @@ -2207,7 +2268,7 @@ area is off-screen to the top. A <Scroll-y> event is generated.

-
pathName yview scroll number what
+
pathName yview scroll number what
This command adjusts the view in the window up or down according to number and what. @@ -2232,11 +2293,8 @@ other. An item can be considered as a row, which reaches over all columns.
-Columns in a treectrl may be named in either of two ways: by number or by tag. -If a number is given it must be an integer from zero to N, where N -is one less than the result of the numcolumns widget command. -A column may also be named by the value of its -tag configuration -option. +Columns in a treectrl may be specified in a number of ways. +See COLUMN DESCRIPTION below.
There is always one special column, the tail column, which fills @@ -2263,12 +2321,12 @@ to the right of the column title.

-arrowbitmap bitmap
Specifies as a per-state option the bitmap to use to draw the arrow if -this columns -arrow option is not none. +this column's -arrow option is not none.

-arrowimage image
Specifies as a per-state option the image to use to draw the arrow if -this columns -arrow option is not none. If an image is specified for +this column's -arrow option is not none. If an image is specified for a certain state, it overrides the -arrowbitmap option.

@@ -2454,6 +2512,68 @@ d) and the tree -wrap option results in wrapping.
+
COLUMN DESCRIPTION
+
+Many of the commands and options for a treectrl take as an argument a +description of which column to operate on. +See the EXAMPLES section for examples. +The initial part of a column description must begin with one of the following terms: + +
+
id
+Specifies the unique column identifier, where id should be +the return value of a prior call of the column create widget command. + +

+
tag
+Specifies the value of a column's -tag option. + +

+
all
+Indicates every column, including the tail column. Not all commands accept this. + +

+
first ?visible?
+Indicates the leftmost column of the treectrl. +If visible is specified, the leftmost column whose -visible option +is true is used. + +

+
last ?visible?
+Indicates the rightmost column of the treectrl (but not the tail column). +If visible is specified, the rightmost column whose -visible option +is true is used. + +

+
order n ?visible?
+Indicates the nth column in the list of columns as returned by the +column order command. + +

+
tail
+Indicates the ever-present tail column of the treectrl. +
+ +
+The initial part of the column description (matching any of the values above) +may be followed by one or more modifiers. +A modifier changes the column used relative to +the description up to this point. +It may be specified in any of the following forms: + +
+ +
next ?visible?
+Use the column to the right, or the column to the right whose -visible option +is true. + +

+
prev ?visible?
+Use the column to the left, or the column to the left whose -visible option +is true. + +
+
STATES

A state consists basically of just a string: its stateName. @@ -2536,7 +2656,7 @@ However, to use a different font when the item is selected you could write:

$T element configure MyTextElement -font {{Courier 10} selected {Times 12 bold} {}}
-In the second example above the -font option reads "value stateList value stateList". +In the example above, the -font option reads "value stateList value stateList". If stateList is an empty list, the preceding value is used regardless of the item state. A non-empty stateList specifies a list of states which must be set for the item in order to use the preceding value. Each stateList can also @@ -2795,16 +2915,16 @@ with a particular item.
ITEM DESCRIPTION

-Many of the widget commands for a treectrl take as one argument an -indicator of which item of the treectrl to operate on. These -indicators are called itemDescs and may be specified in -any of the following forms: +Many of the commands and options for a treectrl take as an argument a +description of which item to operate on. +See the EXAMPLES section for examples. +The initial part of an item description must begin with one of the following terms:
-
number
-Specifies the item numerically, where number should be +
id
+Specifies the unique item identifier, where id should be the return value of a prior call of the item create widget command, -or 0 to specify the root item. +or 0 to specify the ever-present root item.

active
@@ -2847,8 +2967,9 @@ Indicates the root item of the treectrl.

-The itemDesc may be followed by one or more modifiers. -A modifier changes the item described by the itemDesc relative to +The initial part of the column description (matching any of the values above) +may be followed by one or more modifiers. +A modifier changes the item used relative to the description up to this point. It may be specified in any of the following forms: @@ -3145,6 +3266,41 @@ depending on the direction, the wheel was turned. The active cursor or the selection is not affected. +
EXAMPLES
+
+ +Get the unique identifier for the leftmost visible column: +

+set id [$T column index "first visible"] +
+ +Delete the leftmost column: +

+$T column delete "order 0" +
+ +Take the visible column that is to the left of the last column, and move that +column in front of the tail column: +

+$T column move "last prev visible" tail +
+ + +Get the unique identifier for the first visible item: +

+set id [$T item index "first visible"] +
+ +Delete the parent of the item that is under the point x,y: +

+$T item delete "nearest $x $y parent" +
+ +Add the 10th child of the second child of the root item to the selection: +

+$T selection add "root firstchild nextsibling child 10" +
+
SEE ALSO
diff --git a/doc/treectrl.man b/doc/treectrl.man index b1a0bef..8b2bcf1 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.13 2005/05/11 03:31:32 treectrl Exp $} -][manpage_begin treectrl n 1.2] + $Id: treectrl.man,v 1.14 2005/05/13 20:50:20 treectrl Exp $} +][manpage_begin treectrl n 2.0] [moddesc {Tk Commands}] [titledesc {Create and manipulate hierarchical multicolumn widgets}] -[require treectrl 1.2] +[require treectrl 2.0] [description] [list_begin definitions] @@ -378,7 +378,9 @@ for the column specified by [arg column], This command is similar to the [cmd configure] widget command except that it modifies options associated with the column specified by [arg column] instead of modifying options for the overall treectrl widget. -[arg Column] may also be the string [const tail] to specify the tail column. +[arg Column] may be the string [const tail] to specify the tail column. +If [arg column] is the string [const all], at least one option-value pair +must be given; in this case all the columns are configured. If no [arg option] is specified, the command returns a list describing all of the available options for [arg column] (see [fun Tk_ConfigureInfo] for information on the format of this list). @@ -393,22 +395,45 @@ in this case the command returns an empty string. See [sectref COLUMNS] below for details on the options available for columns. +[call [arg pathName] [cmd {column compare}] [arg column1] [arg op] [arg column2]] +From both [arg column]s the index is retrieved +(as returned from the [cmd {column order}] widget command). +Then these indexes are compared using the operator [arg op], which must +be either [const <], [const <=], [const ==], [const >=], [const >], +or [const !=]. +The return value of this command is 1 if the comparison evaluated to true, +0 otherwise. + +[call [arg pathName] [cmd {column count}]] +Returns a decimal string giving the number of +columns created by the [cmd "column create"] widget command which haven't been +deleted by the [cmd "column delete"] widget command. The [const tail] column +is not counted. + [call [arg pathName] [cmd {column create}] [opt [arg {option value ...}]]] This command creates a new column in the treectrl widget. The new column is placed to the right of all other columns (except the [const tail] column). Any [arg option]-[arg value] arguments configure the new column according to the -[cmd "column configure"] command. The return value is the zero-based index +[cmd "column configure"] command. The return value is the unique identifier of the new column. [call [arg pathName] [cmd {column delete}] [arg column]] -Deletes the specified [arg column] from the treectrl widget. -All remaining columns of the treectrl widget will get new column numbers: -in an unchanged order, but with succesive numbers. +Deletes the specified [arg column] from the treectrl widget. If [arg column] +is the string [const all], all columns except the tail column are deleted. [call [arg pathName] [cmd {column index}] [arg column]] -This command returns a decimal string giving the column number -of the column specified by [arg column], -which may also be the string [const tail] to specify the tail column. +Deprecated. Use [cmd {column id}] + +[call [arg pathName] [cmd {column id}] [arg column]] +This command resolves the column description [arg column] into a unique column +identifier (see [sectref {COLUMN DESCRIPTION}] below). +If the column described by [arg column] doesn't exist, this command returns +an empty string. + +[call [arg pathName] [cmd {column list}] [opt [arg -visible]]] +This command returns a list of identifiers for every column (except the tail) +from left to right. If [arg -visible] is given, only columns whose -visible +option is true are returned. [call [arg pathName] [cmd {column move}] [arg column] [arg before]] Moves the specified [arg column] to the left of the column @@ -422,6 +447,13 @@ of the column specified by [arg column]. The needed width is the maximum of the width of the column header and the width of the [emph widest] currently visible item. +[call [arg pathName] [cmd {column order}] [arg column] [opt [arg -visible]]] +This command returns a decimal string giving the position of [arg column] +in the list of columns starting from zero for the leftmost column. +If [arg -visible] is given, only columns whose -visible +option is true are considered, and -1 is returned if [arg column]'s -visible +option is false. + [call [arg pathName] [cmd {column width}] [arg column]] This command returns a decimal string giving the width in pixels of the column specified by [arg column], @@ -430,13 +462,7 @@ by means of the [option -showheader] option. [list_end] [call [arg pathName] [cmd compare] [arg itemDesc1] [arg op] [arg itemDesc2]] -From both items described by the [arg itemDesc]s the index is retrieved -(as returned from the [cmd {item index}] widget command). -Then these indexes are compared using the operator [arg op], which must -be either [const <], [const <=], [const ==], [const >=], [const >], -or [const !=]. -The return value of this command is 1 if the comparison evaulated to true, -0 otherwise. +Deprecated. Use the [cmd {item compare}] command instead. [call [arg pathName] [cmd configure] [opt [arg option]] \ [opt [arg {value option value ...}]]] @@ -702,9 +728,7 @@ if the x coordinate is to the right of the elements; nothing otherwise. [call [arg pathName] [cmd index] [arg itemDesc]] -This command returns a decimal string giving the numerical id -of the item specified by [arg itemDesc] -(see [sectref {ITEM DESCRIPTION}] below). +Deprecated. Use [cmd {item id}] instead. [call [arg pathName] [cmd item] [arg option] [opt [arg {arg ...}]]] This command is used to manipulate items. @@ -756,6 +780,15 @@ two events are generated: a [const ] event before the item state is changed, and a [const ] event after the item state was changed. +[call [arg pathName] [cmd {item compare}] [arg itemDesc1] [arg op] [arg itemDesc2]] +From both items described by the [arg itemDesc]s the index is retrieved +(as returned from the [cmd {item order}] widget command). +Then these indexes are compared using the operator [arg op], which must +be either [const <], [const <=], [const ==], [const >=], [const >], +or [const !=]. +The return value of this command is 1 if the comparison evaluated to true, +0 otherwise. + [call [arg pathName] [cmd {item complex}] [arg itemDesc] [arg list] [arg ...]] Modifies the elements of the item described by [arg itemDesc]. For every column of the treectrl there may be specified one [arg list], @@ -778,6 +811,12 @@ given value(s); in this case the command returns an empty string. The options and values are the same as those permissible in the [cmd "item create"] command when the item was created. +[call [arg pathName] [cmd {item count}]] +Returns a decimal string giving the number of +items created by the [cmd "item create"] widget command which haven't been +deleted by the [cmd "item delete"] widget command, plus 1 for the ever-present +root item. + [call [arg pathName] [cmd {item create}] [opt [arg {option value ...}]]] Creates a new item and returns its unique identifier. The new item has the states [const open] and [const enabled] set by default. @@ -900,13 +939,10 @@ 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 index}] [arg itemDesc]] -Returns a list of two integers, which corresponds to the row -of the item described by [arg itemDesc], -if all items above are counted and if only the displayed items are counted. -This command should not be confused with the [cmd index] widget command, -which return the invariable item id. -The index here is basically the row of the item. +[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 +[arg itemDesc] doesn't exist, this command returns an empty string. [call [arg pathName] [cmd {item isancestor}] [arg itemDesc] [arg descendant]] Returns 1 if the item described by [arg itemDesc] is a direct or indirect @@ -933,6 +969,15 @@ Then it will become the new next sibling of [arg sibling]. [call [arg pathName] [cmd {item numchildren}] [arg itemDesc]] Returns the number of children of the item described by [arg itemDesc]. +[call [arg pathName] [cmd {item order}] [arg itemDesc] [opt [arg -visible]]] +This command returns the position of the item [arg itemDesc] relative to +its toplevel ancestor (usually the root item, unless the ancestor is an +orphan). If you imagine all the items flattened into a vertical list, the +result of this command is the row the item falls in. If the optional argument +[arg -visible] is given, only the items whose ancestors are expanded, and whose +-visible option is true, get counted; in this case -1 is returned if the item +is not visible. + [call [arg pathName] [cmd {item parent}] [arg itemDesc]] Returns the numerical index of the parent of the item described by [arg itemDesc]. @@ -964,7 +1009,7 @@ the order between these two limiting items doesn't matter. [nl] The sort column can be specified by means of the [option -column] option; -this option can be used repeatedly to define a multi column sort. +this option can be used repeatedly to define a multicolumn sort. The sorting is done by looking at the [arg text] of the element specified by the [option -element] option, which must be a text element defined in the style of the sorting column, @@ -1368,18 +1413,10 @@ Use [cmd {notify uninstall}] with a [arg pattern] of <[arg eventName]> instead. [list_end] [call [arg pathName] [cmd numcolumns]] -Returns a decimal string giving the number of -columns created by the [cmd "column create"] widget command which haven't been -deleted by the [cmd "column delete"] widget command. The [const tail] column -is not counted. +Deprecated. Use the [cmd {column count}] command instead. [call [arg pathName] [cmd numitems]] -Returns a decimal string giving the number of -items created by the [cmd "item create"] widget command which haven't been -deleted by the [cmd "item delete"] widget command. -This number is always positive, -since a newly created treectrl widget has already the root item, -which cannot be deleted. +Deprecated. Use the [cmd {item count}] command instead. [call [arg pathName] [cmd orphans]] Returns a list containing the numerical ids of all items @@ -1720,11 +1757,8 @@ other. An item can be considered as a row, which reaches over all columns. [para] -Columns in a treectrl may be named in either of two ways: by number or by tag. -If a number is given it must be an integer from zero to [arg N], where [arg N] -is one less than the result of the [cmd numcolumns] widget command. -A column may also be named by the value of its [option -tag] configuration -option. +Columns in a treectrl may be specified in a number of ways. +See [sectref {COLUMN DESCRIPTION}] below. [para] There is always one special column, the [const tail] column, which fills @@ -1912,6 +1946,60 @@ d) and the tree [option -wrap] option results in wrapping. [list_end] +[section {COLUMN DESCRIPTION}] +Many of the commands and options for a treectrl take as an argument a +description of which column to operate on. +See the [sectref EXAMPLES] section for examples. +The initial part of a column description must begin with one of the following terms: + +[list_begin definitions] +[lst_item [arg id]] +Specifies the unique column identifier, where [arg id] should be +the return value of a prior call of the [cmd {column create}] widget command. + +[lst_item [arg tag]] +Specifies the value of a column's -tag option. + +[lst_item [const all]] +Indicates every column, including the tail column. Not all commands accept this. + +[lst_item "[const first] [opt [const visible]]"] +Indicates the leftmost column of the treectrl. +If [const visible] is specified, the leftmost column whose -visible option +is true is used. + +[lst_item "[const last] [opt [const visible]]"] +Indicates the rightmost column of the treectrl (but not the tail column). +If [const visible] is specified, the rightmost column whose -visible option +is true is used. + +[lst_item "[const order] [arg n] [opt [const visible]]"] +Indicates the [arg n]th column in the list of columns as returned by the +[cmd {column order}] command. + +[lst_item [const tail]] +Indicates the ever-present tail column of the treectrl. +[list_end] + +[para] +The initial part of the column description (matching any of the values above) +may be followed by one or more [arg modifier]s. +A modifier changes the column used relative to +the description up to this point. +It may be specified in any of the following forms: + +[list_begin definitions] + +[lst_item "[const next] [opt [const visible]]"] +Use the column to the right, or the column to the right whose -visible option +is true. + +[lst_item "[const prev] [opt [const visible]]"] +Use the column to the left, or the column to the left whose -visible option +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, @@ -2215,16 +2303,16 @@ with a particular item. [list_end] [section {ITEM DESCRIPTION}] -Many of the widget commands for a treectrl take as one argument an -indicator of which item of the treectrl to operate on. These -indicators are called [arg itemDesc]s and may be specified in -any of the following forms: +Many of the commands and options for a treectrl take as an argument a +description of which item to operate on. +See the [sectref EXAMPLES] section for examples. +The initial part of an item description must begin with one of the following terms: [list_begin definitions] -[lst_item [arg number]] -Specifies the item numerically, where [arg number] should be +[lst_item [arg id]] +Specifies the unique item identifier, where [arg id] should be the return value of a prior call of the [cmd {item create}] widget command, -or [const 0] to specify the root item. +or [const 0] to specify the ever-present root item. [lst_item [const active]] Indicates the item that is currently active, i.e. normally @@ -2260,8 +2348,9 @@ Indicates the root item of the treectrl. [list_end] [para] -The [arg itemDesc] may be followed by one or more [arg modifier]s. -A modifier changes the item described by the [arg itemDesc] relative to +The initial part of the item description (matching any of the values above) +may be followed by one or more [arg modifier]s. +A modifier changes the item used relative to the description up to this point. It may be specified in any of the following forms: @@ -2506,6 +2595,40 @@ depending on the direction, the wheel was turned. The active cursor or the selection is not affected. [list_end] +[section EXAMPLES] + +Get the unique identifier for the leftmost visible column: +[example_begin] +set id [lb]$T column index "first visible"[rb] +[example_end] + +Delete the leftmost column: +[example_begin] +$T column delete "order 0" +[example_end] + +Take the visible column that is to the left of the last column, and move that +column in front of the tail column: +[example_begin] +$T column move "last prev visible" tail +[example_end] + + +Get the unique identifier for the first visible item: +[example_begin] +set id [lb]$T item index "first visible"[rb] +[example_end] + +Delete the parent of the item that is under the point x,y: +[example_begin] +$T item delete "nearest $x $y parent" +[example_end] + +Add the 10th child of the second child of the root item to the selection: +[example_begin] +$T selection add "root firstchild nextsibling child 10" +[example_end] + [see_also listbox(n) image(n) bitmap(n) bind(n) options(n)] [keywords tree widget] [manpage_end] diff --git a/doc/treectrl.n b/doc/treectrl.n index 0ed1b33..897de51 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.29 2005/05/11 03:31:33 treectrl Exp $ +'\" $Id: treectrl.n,v 1.30 2005/05/13 20:50:20 treectrl Exp $ .so man.macros -.TH "treectrl" n 1.2 "Tk Commands" +.TH "treectrl" n 2.0 "Tk Commands" .BS .SH "NAME" treectrl \- Create and manipulate hierarchical multicolumn widgets .SH "SYNOPSIS" -package require \fBtreectrl 1.2\fR +package require \fBtreectrl 2.0\fR .sp \fBtreectrl\fR \fIpathName\fR ?\fIoptions\fR?\fR .sp @@ -35,16 +35,26 @@ package require \fBtreectrl 1.2\fR .sp \fIpathName\fR \fBcolumn configure\fR \fIcolumn\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?\fR .sp +\fIpathName\fR \fBcolumn compare\fR \fIcolumn1\fR \fIop\fR \fIcolumn2\fR\fR +.sp +\fIpathName\fR \fBcolumn count\fR\fR +.sp \fIpathName\fR \fBcolumn create\fR ?\fIoption value ...\fR?\fR .sp \fIpathName\fR \fBcolumn delete\fR \fIcolumn\fR\fR .sp \fIpathName\fR \fBcolumn index\fR \fIcolumn\fR\fR .sp +\fIpathName\fR \fBcolumn id\fR \fIcolumn\fR\fR +.sp +\fIpathName\fR \fBcolumn list\fR ?\fI-visible\fR?\fR +.sp \fIpathName\fR \fBcolumn move\fR \fIcolumn\fR \fIbefore\fR\fR .sp \fIpathName\fR \fBcolumn neededwidth\fR \fIcolumn\fR\fR .sp +\fIpathName\fR \fBcolumn order\fR \fIcolumn\fR ?\fI-visible\fR?\fR +.sp \fIpathName\fR \fBcolumn width\fR \fIcolumn\fR\fR .sp \fIpathName\fR \fBcompare\fR \fIitemDesc1\fR \fIop\fR \fIitemDesc2\fR\fR @@ -109,10 +119,14 @@ package require \fBtreectrl 1.2\fR .sp \fIpathName\fR \fBitem collapse\fR \fIitemDesc\fR ?\fB-recurse\fR?\fR .sp +\fIpathName\fR \fBitem compare\fR \fIitemDesc1\fR \fIop\fR \fIitemDesc2\fR\fR +.sp \fIpathName\fR \fBitem complex\fR \fIitemDesc\fR \fIlist\fR \fI...\fR\fR .sp \fIpathName\fR \fBitem configure\fR \fIitemDesc\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?\fR .sp +\fIpathName\fR \fBitem count\fR\fR +.sp \fIpathName\fR \fBitem create\fR ?\fIoption value ...\fR?\fR .sp \fIpathName\fR \fBitem delete\fR \fIfirst\fR ?\fIlast\fR?\fR @@ -131,7 +145,7 @@ package require \fBtreectrl 1.2\fR .sp \fIpathName\fR \fBitem firstchild\fR \fIparent\fR ?\fIchild\fR?\fR .sp -\fIpathName\fR \fBitem index\fR \fIitemDesc\fR\fR +\fIpathName\fR \fBitem id\fR \fIitemDesc\fR\fR .sp \fIpathName\fR \fBitem isancestor\fR \fIitemDesc\fR \fIdescendant\fR\fR .sp @@ -143,6 +157,8 @@ package require \fBtreectrl 1.2\fR .sp \fIpathName\fR \fBitem numchildren\fR \fIitemDesc\fR\fR .sp +\fIpathName\fR \fBitem order\fR \fIitemDesc\fR ?\fI-visible\fR?\fR +.sp \fIpathName\fR \fBitem parent\fR \fIitemDesc\fR\fR .sp \fIpathName\fR \fBitem prevsibling\fR \fIsibling\fR ?\fIprev\fR?\fR @@ -848,7 +864,9 @@ for the column specified by \fIcolumn\fR, This command is similar to the \fBconfigure\fR widget command except that it modifies options associated with the column specified by \fIcolumn\fR instead of modifying options for the overall treectrl widget. -\fIColumn\fR may also be the string \fBtail\fR to specify the tail column. +\fIColumn\fR may be the string \fBtail\fR to specify the tail column. +If \fIcolumn\fR is the string \fBall\fR, at least one option-value pair +must be given; in this case all the columns are configured. If no \fIoption\fR is specified, the command returns a list describing all of the available options for \fIcolumn\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). @@ -862,22 +880,45 @@ in this case the command returns an empty string. .sp See \fBCOLUMNS\fR below for details on the options available for columns. .TP +\fIpathName\fR \fBcolumn compare\fR \fIcolumn1\fR \fIop\fR \fIcolumn2\fR\fR +From both \fIcolumn\fRs the index is retrieved +(as returned from the \fBcolumn order\fR widget command). +Then these indexes are compared using the operator \fIop\fR, which must +be either \fB<\fR, \fB<=\fR, \fB==\fR, \fB>=\fR, \fB>\fR, +or \fB!=\fR. +The return value of this command is 1 if the comparison evaluated to true, +0 otherwise. +.TP +\fIpathName\fR \fBcolumn count\fR\fR +Returns a decimal string giving the number of +columns created by the \fBcolumn create\fR widget command which haven't been +deleted by the \fBcolumn delete\fR widget command. The \fBtail\fR column +is not counted. +.TP \fIpathName\fR \fBcolumn create\fR ?\fIoption value ...\fR?\fR This command creates a new column in the treectrl widget. The new column is placed to the right of all other columns (except the \fBtail\fR column). Any \fIoption\fR-\fIvalue\fR arguments configure the new column according to the -\fBcolumn configure\fR command. The return value is the zero-based index +\fBcolumn configure\fR command. The return value is the unique identifier of the new column. .TP \fIpathName\fR \fBcolumn delete\fR \fIcolumn\fR\fR -Deletes the specified \fIcolumn\fR from the treectrl widget. -All remaining columns of the treectrl widget will get new column numbers: -in an unchanged order, but with succesive numbers. +Deletes the specified \fIcolumn\fR from the treectrl widget. If \fIcolumn\fR +is the string \fBall\fR, all columns except the tail column are deleted. .TP \fIpathName\fR \fBcolumn index\fR \fIcolumn\fR\fR -This command returns a decimal string giving the column number -of the column specified by \fIcolumn\fR, -which may also be the string \fBtail\fR to specify the tail column. +Deprecated. Use \fBcolumn id\fR +.TP +\fIpathName\fR \fBcolumn id\fR \fIcolumn\fR\fR +This command resolves the column description \fIcolumn\fR into a unique column +identifier (see \fBCOLUMN DESCRIPTION\fR below). +If the column described by \fIcolumn\fR doesn't exist, this command returns +an empty string. +.TP +\fIpathName\fR \fBcolumn list\fR ?\fI-visible\fR?\fR +This command returns a list of identifiers for every column (except the tail) +from left to right. If \fI-visible\fR is given, only columns whose -visible +option is true are returned. .TP \fIpathName\fR \fBcolumn move\fR \fIcolumn\fR \fIbefore\fR\fR Moves the specified \fIcolumn\fR to the left of the column @@ -891,6 +932,13 @@ of the column specified by \fIcolumn\fR. The needed width is the maximum of the width of the column header and the width of the \fIwidest\fR currently visible item. .TP +\fIpathName\fR \fBcolumn order\fR \fIcolumn\fR ?\fI-visible\fR?\fR +This command returns a decimal string giving the position of \fIcolumn\fR +in the list of columns starting from zero for the leftmost column. +If \fI-visible\fR is given, only columns whose -visible +option is true are considered, and -1 is returned if \fIcolumn\fR's -visible +option is false. +.TP \fIpathName\fR \fBcolumn width\fR \fIcolumn\fR\fR This command returns a decimal string giving the width in pixels of the column specified by \fIcolumn\fR, @@ -899,13 +947,7 @@ by means of the \fB-showheader\fR option. .RE .TP \fIpathName\fR \fBcompare\fR \fIitemDesc1\fR \fIop\fR \fIitemDesc2\fR\fR -From both items described by the \fIitemDesc\fRs the index is retrieved -(as returned from the \fBitem index\fR widget command). -Then these indexes are compared using the operator \fIop\fR, which must -be either \fB<\fR, \fB<=\fR, \fB==\fR, \fB>=\fR, \fB>\fR, -or \fB!=\fR. -The return value of this command is 1 if the comparison evaulated to true, -0 otherwise. +Deprecated. Use the \fBitem compare\fR command instead. .TP \fIpathName\fR \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?\fR Query or modify the configuration options of the widget. @@ -1159,9 +1201,7 @@ if the x coordinate is to the right of the elements; nothing otherwise. .TP \fIpathName\fR \fBindex\fR \fIitemDesc\fR\fR -This command returns a decimal string giving the numerical id -of the item specified by \fIitemDesc\fR -(see \fBITEM DESCRIPTION\fR below). +Deprecated. Use \fBitem id\fR instead. .TP \fIpathName\fR \fBitem\fR \fIoption\fR ?\fIarg ...\fR?\fR This command is used to manipulate items. @@ -1212,6 +1252,15 @@ two events are generated: a \fB\fR event before the item state is changed, and a \fB\fR event after the item state was changed. .TP +\fIpathName\fR \fBitem compare\fR \fIitemDesc1\fR \fIop\fR \fIitemDesc2\fR\fR +From both items described by the \fIitemDesc\fRs the index is retrieved +(as returned from the \fBitem order\fR widget command). +Then these indexes are compared using the operator \fIop\fR, which must +be either \fB<\fR, \fB<=\fR, \fB==\fR, \fB>=\fR, \fB>\fR, +or \fB!=\fR. +The return value of this command is 1 if the comparison evaluated to true, +0 otherwise. +.TP \fIpathName\fR \fBitem complex\fR \fIitemDesc\fR \fIlist\fR \fI...\fR\fR Modifies the elements of the item described by \fIitemDesc\fR. For every column of the treectrl there may be specified one \fIlist\fR, @@ -1234,6 +1283,12 @@ given value(s); in this case the command returns an empty string. The options and values are the same as those permissible in the \fBitem create\fR command when the item was created. .TP +\fIpathName\fR \fBitem count\fR\fR +Returns a decimal string giving the number of +items created by the \fBitem create\fR widget command which haven't been +deleted by the \fBitem delete\fR widget command, plus 1 for the ever-present +root item. +.TP \fIpathName\fR \fBitem create\fR ?\fIoption value ...\fR?\fR Creates a new item and returns its unique identifier. The new item has the states \fBopen\fR and \fBenabled\fR set by default. @@ -1349,13 +1404,10 @@ 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 index\fR \fIitemDesc\fR\fR -Returns a list of two integers, which corresponds to the row -of the item described by \fIitemDesc\fR, -if all items above are counted and if only the displayed items are counted. -This command should not be confused with the \fBindex\fR widget command, -which return the invariable item id. -The index here is basically the row of the item. +\fIpathName\fR \fBitem id\fR \fIitemDesc\fR\fR +This command resolves the item description \fIitemDesc\fR into a unique item +identifier (see \fBITEM DESCRIPTION\fR below). If the item described by +\fIitemDesc\fR doesn't exist, this command returns an empty string. .TP \fIpathName\fR \fBitem isancestor\fR \fIitemDesc\fR \fIdescendant\fR\fR Returns 1 if the item described by \fIitemDesc\fR is a direct or indirect @@ -1382,6 +1434,15 @@ Then it will become the new next sibling of \fIsibling\fR. \fIpathName\fR \fBitem numchildren\fR \fIitemDesc\fR\fR Returns the number of children of the item described by \fIitemDesc\fR. .TP +\fIpathName\fR \fBitem order\fR \fIitemDesc\fR ?\fI-visible\fR?\fR +This command returns the position of the item \fIitemDesc\fR relative to +its toplevel ancestor (usually the root item, unless the ancestor is an +orphan). If you imagine all the items flattened into a vertical list, the +result of this command is the row the item falls in. If the optional argument +\fI-visible\fR is given, only the items whose ancestors are expanded, and whose +-visible option is true, get counted; in this case -1 is returned if the item +is not visible. +.TP \fIpathName\fR \fBitem parent\fR \fIitemDesc\fR\fR Returns the numerical index of the parent of the item described by \fIitemDesc\fR. @@ -1411,7 +1472,7 @@ which should be children of the item described by \fIitemDesc\fR; the order between these two limiting items doesn't matter. .sp The sort column can be specified by means of the \fB-column\fR option; -this option can be used repeatedly to define a multi column sort. +this option can be used repeatedly to define a multicolumn sort. The sorting is done by looking at the \fItext\fR of the element specified by the \fB-element\fR option, which must be a text element defined in the style of the sorting column, @@ -1783,18 +1844,10 @@ Use \fBnotify uninstall\fR with a \fIpattern\fR of <\fIeventName\fR> instead. .RE .TP \fIpathName\fR \fBnumcolumns\fR\fR -Returns a decimal string giving the number of -columns created by the \fBcolumn create\fR widget command which haven't been -deleted by the \fBcolumn delete\fR widget command. The \fBtail\fR column -is not counted. +Deprecated. Use the \fBcolumn count\fR command instead. .TP \fIpathName\fR \fBnumitems\fR\fR -Returns a decimal string giving the number of -items created by the \fBitem create\fR widget command which haven't been -deleted by the \fBitem delete\fR widget command. -This number is always positive, -since a newly created treectrl widget has already the root item, -which cannot be deleted. +Deprecated. Use the \fBitem count\fR command instead. .TP \fIpathName\fR \fBorphans\fR\fR Returns a list containing the numerical ids of all items @@ -2125,11 +2178,8 @@ A treectrl widget is capable of displaying multiple columns next to each other. An item can be considered as a row, which reaches over all columns. .PP -Columns in a treectrl may be named in either of two ways: by number or by tag. -If a number is given it must be an integer from zero to \fIN\fR, where \fIN\fR -is one less than the result of the \fBnumcolumns\fR widget command. -A column may also be named by the value of its \fB-tag\fR configuration -option. +Columns in a treectrl may be specified in a number of ways. +See \fBCOLUMN DESCRIPTION\fR below. .PP There is always one special column, the \fBtail\fR column, which fills all space to the right of the last ordinary column. @@ -2151,11 +2201,11 @@ to the right of the column title. .TP \fB\fB-arrowbitmap\fR\fR \fIbitmap\fR Specifies as a per-state option the bitmap to use to draw the arrow if -this columns -arrow option is not \fBnone\fR. +this column's -arrow option is not \fBnone\fR. .TP \fB\fB-arrowimage\fR\fR \fIimage\fR Specifies as a per-state option the image to use to draw the arrow if -this columns -arrow option is not \fBnone\fR. If an image is specified for +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 @@ -2310,6 +2360,52 @@ a) the tree \fB-orientation\fR option is \fBvertical\fR; b) only a single tree column is visible; c) the single visible tree column \fB-width\fR option is zero; d) and the tree \fB-wrap\fR option results in wrapping. +.SH "COLUMN DESCRIPTION" +Many of the commands and options for a treectrl take as an argument a +description of which column to operate on. +See the \fBEXAMPLES\fR section for examples. +The initial part of a column description must begin with one of the following terms: +.TP +\fIid\fR +Specifies the unique column identifier, where \fIid\fR should be +the return value of a prior call of the \fBcolumn create\fR widget command. +.TP +\fItag\fR +Specifies the value of a column's -tag option. +.TP +\fBall\fR +Indicates every column, including the tail column. Not all commands accept this. +.TP +\fBfirst\fR ?\fBvisible\fR? +Indicates the leftmost column of the treectrl. +If \fBvisible\fR is specified, the leftmost column whose -visible option +is true is used. +.TP +\fBlast\fR ?\fBvisible\fR? +Indicates the rightmost column of the treectrl (but not the tail column). +If \fBvisible\fR is specified, the rightmost column whose -visible option +is true is used. +.TP +\fBorder\fR \fIn\fR ?\fBvisible\fR? +Indicates the \fIn\fRth column in the list of columns as returned by the +\fBcolumn order\fR command. +.TP +\fBtail\fR +Indicates the ever-present tail column of the treectrl. +.PP +The initial part of the column description (matching any of the values above) +may be followed by one or more \fImodifier\fRs. +A modifier changes the column used relative to +the description up to this point. +It may be specified in any of the following forms: +.TP +\fBnext\fR ?\fBvisible\fR? +Use the column to the right, or the column to the right whose -visible option +is true. +.TP +\fBprev\fR ?\fBvisible\fR? +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, @@ -2379,7 +2475,7 @@ However, to use a different font when the item is selected you could write: .nf $T element configure MyTextElement -font {{Courier 10} selected {Times 12 bold} {}} .fi -In the second example above the -font option reads "value stateList value stateList". +In the example above, the -font option reads "value stateList value stateList". If \fIstateList\fR is an empty list, the preceding \fIvalue\fR is used regardless of the item state. A non-empty stateList specifies a list of states which must be set for the item in order to use the preceding value. Each stateList can also @@ -2585,15 +2681,15 @@ the \fBelement create\fR or \fBelement configure\fR commands, only by the \fBitem element configure\fR command; i.e., the element must be associated with a particular item. .SH "ITEM DESCRIPTION" -Many of the widget commands for a treectrl take as one argument an -indicator of which item of the treectrl to operate on. These -indicators are called \fIitemDesc\fRs and may be specified in -any of the following forms: +Many of the commands and options for a treectrl take as an argument a +description of which item to operate on. +See the \fBEXAMPLES\fR section for examples. +The initial part of an item description must begin with one of the following terms: .TP -\fInumber\fR -Specifies the item numerically, where \fInumber\fR should be +\fIid\fR +Specifies the unique item identifier, where \fIid\fR should be the return value of a prior call of the \fBitem create\fR widget command, -or \fB0\fR to specify the root item. +or \fB0\fR to specify the ever-present root item. .TP \fBactive\fR Indicates the item that is currently active, i.e. normally @@ -2627,8 +2723,9 @@ You can memorize \fBrnc\fR as abbreviation of "row 'n' column". \fBroot\fR Indicates the root item of the treectrl. .PP -The \fIitemDesc\fR may be followed by one or more \fImodifier\fRs. -A modifier changes the item described by the \fIitemDesc\fR relative to +The initial part of the column description (matching any of the values above) +may be followed by one or more \fImodifier\fRs. +A modifier changes the item used relative to the description up to this point. It may be specified in any of the following forms: .TP @@ -2879,6 +2976,32 @@ the Return key toggles the active item. The mousewheel scrolls the view of the widget four lines up or down depending on the direction, the wheel was turned. The active cursor or the selection is not affected. +.SH "EXAMPLES" +Get the unique identifier for the leftmost visible column: +.nf +set id [$T column index "first visible"] +.fi +Delete the leftmost column: +.nf +$T column delete "order 0" +.fi +Take the visible column that is to the left of the last column, and move that +column in front of the tail column: +.nf +$T column move "last prev visible" tail +.fi +Get the unique identifier for the first visible item: +.nf +set id [$T item index "first visible"] +.fi +Delete the parent of the item that is under the point x,y: +.nf +$T item delete "nearest $x $y parent" +.fi +Add the 10th child of the second child of the root item to the selection: +.nf +$T selection add "root firstchild nextsibling child 10" +.fi .SH "SEE ALSO" bind(n), bitmap(n), image(n), listbox(n), options(n) .SH "KEYWORDS" -- cgit v0.12