treectrl - Tk Commands

DESCRIPTION

@@ -1436,14 +1438,7 @@ The following forms of the command are supported:

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 -itemDesc. If option was configured using the -item element configure command, the -return value is the same as if the item element cget command -was used. Otherwise the value of the configuration option of the underlying element is returned. -Option may have any of the values accepted by the type of the -specified element (see ELEMENTS below) +Deprecated. Use item element perstate instead.

pathName item element cget itemDesc column element option

@@ -1473,11 +1468,11 @@ modifies the given option(s) to have the given value(s) in the element inside column of the item described by itemDesc; in this case the command returns an empty string.

-It is possible to configure multiple elements in more than one column with +It is possible to configure multiple elements in multiple columns with a single call. To configure another element in the same column, append a -+ argument followed by the element name followed by one or more -option-value pairs. To configure elements in another column, append a , -argument followed by the column. For example: +'+' argument followed by the element name. To configure elements in +another column, append a ',' argument followed by the column. +For example:

.t item element configure $I \ $C1 $E1 -text "hello" + $E2 -text "world" , \ @@ -1485,9 +1480,18 @@ argument followed by the column. For example: $C3 $E1 -text "apples and oranges"

+

+

pathName item element perstate itemDesc column element option ?stateList?

+ +This command returns the current value of the per-state option named option +for element inside column of the item described by +itemDesc. If stateList is specified, the list of state names (static +and dynamic, see STATES) is used in place of the current state for +item and column. +

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. @@ -1506,7 +1510,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. @@ -1515,26 +1519,45 @@ that is not an ancestor of parent. 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 itemDesc doesn't exist, this command returns an empty string.

-

pathName item isancestor itemDesc descendant

pathName item image itemDesc ?column? ?image? ?column image ...?

+ +This command sets or retrieves the value of the -image option for the first +image element in one or more columns. Keep in mind that the -image option is a +per-state option (see PER-STATE OPTIONS below). + +If no column is specified, this command returns a list of values, +one per column. + +If no image is specified, this command returns the value for column. + +If one or more column-image pairs is specified, +then the value of the -image option in each column is set to image. + +Note that this command is provided as a convenience. Use the +item element configure or item element cget commands if you want +to set or retrieve the value of the -image option for a specific image element. + +

+

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. @@ -1543,7 +1566,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. @@ -1552,12 +1575,12 @@ 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 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 @@ -1568,13 +1591,13 @@ result of this command is the row the item falls in. If the optional argument 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. @@ -1583,7 +1606,7 @@ 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 in the range between first and last, inclusive. @@ -1593,19 +1616,19 @@ The items specified by first and last must 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.

-

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. @@ -1676,7 +1699,7 @@ Convert to integers and use integer comparison. Convert to floating-point values and use floating comparison. -

pathName item span itemDesc ?column? ?numColumns? ?column numColumns ...?

This command sets or retrieves the number of columns that a style covers. If no column is specified, the return value is a list of spans, one per column. @@ -1685,7 +1708,7 @@ If one or more column-numColumns pairs is span for each column is set to numColumns.

-

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 @@ -1695,13 +1718,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 @@ -1711,7 +1734,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), @@ -1727,7 +1750,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 @@ -1736,14 +1759,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 @@ -1756,9 +1779,9 @@ 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 ...?: -This command sets or retrieves the style assigned to a column. +This command sets or retrieves the style assigned to one or more columns. If no column is specified, this command returns a list containing the names of the styles set for all columns of the item described by itemDesc. @@ -1771,25 +1794,25 @@ If one or more column-style pairs is speci then the style in each column is set to style.

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

-This command sets or retrieves the value of the -text option of the first -text element in a column. +This command sets or retrieves the value of the -text option for the first +text element in one or more columns. -If no column is specified, this command returns a list of strings, +If no column is specified, this command returns a list of values, one per column. -If no text is specified, this command returns the string for column. +If no text is specified, this command returns the value for column. If one or more column-text pairs is specified, -then the string in each column is set to text. +then the value of the -text option in each column is set to text. Note that this command is provided as a convenience. Use the -item element configure command if you want to set the text of a -specific text element. +item element configure or item element cget commands if you +want to set or retrieve the value of the -text option for a 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, @@ -1802,7 +1825,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 @@ -1819,7 +1842,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. @@ -1827,7 +1850,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. @@ -1835,7 +1858,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 @@ -1862,7 +1885,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, @@ -1872,7 +1895,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. @@ -1880,7 +1903,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 @@ -1894,7 +1917,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 @@ -1910,7 +1933,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. @@ -1939,7 +1962,7 @@ for a window; otherwise it may be an arbitrary string. Like 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. @@ -1964,7 +1987,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 @@ -1972,14 +1995,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 @@ -2005,7 +2028,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, @@ -2040,19 +2063,19 @@ by itself. or an error if the event is not dynamic.

-

pathName notify install detail eventName detail ?percentsCommand?

Deprecated. Use notify install with a pattern of <eventName-detail> instead.

-

pathName notify install event eventName ?percentsCommand?

Deprecated. 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 @@ -2060,21 +2083,21 @@ by means of the notify install widget command (dynami or by the treectrl widget itself (static).

-

pathName notify linkage eventName ?detail?

Deprecated. Use notify linkage with a pattern of <eventName> or <eventName-detail> instead.

-

pathName notify unbind object ?pattern?

If no pattern is specified, all bindings on object are removed. If pattern is specified, then the current binding for pattern is destroyed, leaving pattern unbound.

-

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. @@ -2082,29 +2105,29 @@ Otherwise the dynamic event or detail is removed. If an event name is specified without a detail, all details for that event are also removed.

-

pathName notify uninstall detail eventName detail

Deprecated. Use notify uninstall with a pattern of <eventName-detail> instead.

-

pathName notify uninstall event eventName

Deprecated. Use notify uninstall with a pattern of <eventName> instead. -

pathName numcolumns

Deprecated. Use the column count command instead.

-

pathName numitems

Deprecated. Use the item count command instead.

-

pathName orphans

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

-

pathName range first last

Deprecated. Use the item range command instead.

-

pathName state option ?stateName?

This command is used to manipulate the list of user defined states, see section STATES below. @@ -2128,13 +2151,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 @@ -2142,18 +2165,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. @@ -2163,14 +2186,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. @@ -2182,7 +2205,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. @@ -2193,7 +2216,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. @@ -2206,13 +2229,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. @@ -2220,13 +2243,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. @@ -2239,7 +2262,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. @@ -2249,7 +2272,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. @@ -2257,7 +2280,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 @@ -2286,7 +2309,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 @@ -2297,7 +2320,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 @@ -2305,7 +2328,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 @@ -2320,7 +2343,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 @@ -2441,17 +2464,17 @@ around a piece of text. -

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. @@ -2459,7 +2482,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 @@ -2472,7 +2495,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. @@ -2480,7 +2503,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. @@ -2498,7 +2521,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. @@ -2506,7 +2529,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 @@ -2517,7 +2540,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. @@ -2525,7 +2548,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. diff --git a/doc/treectrl.man b/doc/treectrl.man index f551675..a381c6f 100644 --- a/doc/treectrl.man +++ b/doc/treectrl.man @@ -3,7 +3,7 @@ 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.28 2005/07/11 01:53:56 treectrl Exp $} + $Id: treectrl.man,v 1.29 2005/07/12 02:54:20 treectrl Exp $} ][manpage_begin treectrl n 2.0] [moddesc {Tk Commands}] [titledesc {Create and manipulate hierarchical multicolumn widgets}] @@ -983,14 +983,7 @@ The following forms of the command are supported: [list_begin definitions] [call [arg pathName] [cmd {item element actual}] [arg itemDesc] [arg column] \ [arg element] [arg option]] -This command returns the current value of the configuration option named [arg option] -associated with [arg element] inside [arg column] of the item described by -[arg itemDesc]. If [arg option] was configured using the -[cmd "item element configure"] command, the -return value is the same as if the [cmd {item element cget}] command -was used. Otherwise the value of the configuration option of the underlying element is returned. -[arg Option] may have any of the values accepted by the type of the -specified element (see [sectref ELEMENTS] below) +Deprecated. Use [cmd {item element perstate}] instead. [call [arg pathName] [cmd {item element cget}] [arg itemDesc] [arg column] \ [arg element] [arg option]] @@ -1019,11 +1012,11 @@ modifies the given option(s) to have the given value(s) in the [arg element] inside [arg column] of the item described by [arg itemDesc]; in this case the command returns an empty string. [nl] -It is possible to configure multiple elements in more than one column with +It is possible to configure multiple elements in multiple columns with a single call. To configure another element in the same column, append a -'[const +]' argument followed by the element name followed by one or more -option-value pairs. To configure elements in another column, append a '[const ,]' -argument followed by the column. For example: +'[const +]' argument followed by the element name. To configure elements in +another column, append a '[const ,]' argument followed by the column. +For example: [example_begin] .t item element configure $I \ $C1 $E1 -text "hello" + $E2 -text "world" , \ @@ -1031,6 +1024,14 @@ argument followed by the column. For example: $C3 $E1 -text "apples and oranges" [example_end] +[call [arg pathName] [cmd {item element perstate}] [arg itemDesc] [arg column] \ + [arg element] [arg option] [opt [arg stateList]]] +This command returns the current value of the per-state option named [arg option] +for [arg element] inside [arg column] of the item described by +[arg itemDesc]. If [arg stateList] is specified, the list of state names (static +and dynamic, see [sectref STATES]) is used in place of the current state for +[arg item] and [arg column.] + [list_end] [call [arg pathName] [cmd {item expand}] [arg itemDesc] [opt [option -recurse]]] @@ -1062,6 +1063,24 @@ 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 image}] [arg itemDesc] [opt [arg column]] \ + [opt [arg image]] [opt [arg {column image ...}]]] +This command sets or retrieves the value of the -image option for the first +image element in one or more columns. Keep in mind that the -image option is a +per-state option (see [sectref {PER-STATE OPTIONS}] below). + +If no [arg column] is specified, this command returns a list of values, +one per column. + +If no [arg image] is specified, this command returns the value for [arg column]. + +If one or more [arg column]-[arg image] pairs is specified, +then the value of the -image option in each [arg column] is set to [arg image]. + +Note that this command is provided as a convenience. Use the +[cmd "item element configure"] or [cmd "item element cget"] commands if you want +to set or retrieve the value of the -image option for a specific image element. + [call [arg pathName] [cmd {item isancestor}] [arg itemDesc] [arg descendant]] Returns 1 if the item described by [arg itemDesc] is a direct or indirect parent of the item decribed by [arg descendant], 0 otherwise. @@ -1260,7 +1279,7 @@ an element in the style specified by [arg style]. Both [arg elementOld] and [call [arg pathName] [cmd {item style set}] [arg itemDesc] [opt [arg column]] \ [opt [arg style]] [opt [arg {column style ...}]]] -This command sets or retrieves the style assigned to a column. +This command sets or retrieves the style assigned to one or more columns. If no [arg column] is specified, this command returns a list containing the names of the styles set for all columns of the item described by [arg itemDesc]. @@ -1275,20 +1294,20 @@ then the style in each [arg column] is set to [arg style]. [call [arg pathName] [cmd {item text}] [arg itemDesc] [opt [arg column]] \ [opt [arg text]] [opt [arg {column text ...}]]] -This command sets or retrieves the value of the -text option of the first -text element in a column. +This command sets or retrieves the value of the -text option for the first +text element in one or more columns. -If no [arg column] is specified, this command returns a list of strings, +If no [arg column] is specified, this command returns a list of values, one per column. -If no [arg text] is specified, this command returns the string for [arg column]. +If no [arg text] is specified, this command returns the value for [arg column]. If one or more [arg column]-[arg text] pairs is specified, -then the string in each [arg column] is set to [arg text]. +then the value of the -text option in each [arg column] is set to [arg text]. Note that this command is provided as a convenience. Use the -[cmd "item element configure"] command if you want to set the text of a -specific text element. +[cmd "item element configure"] or [cmd "item element cget"] commands if you +want to set or retrieve the value of the -text option for a specific text element. [call [arg pathName] [cmd {item toggle}] [arg itemDesc] [opt [option -recurse]]] Changes the [const open] state of the item(s) described by [arg itemDesc]. diff --git a/doc/treectrl.n b/doc/treectrl.n index d0425d3..51fcaf5 100644 --- a/doc/treectrl.n +++ b/doc/treectrl.n @@ -6,7 +6,7 @@ '\" 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.44 2005/07/11 01:53:56 treectrl Exp $ +'\" $Id: treectrl.n,v 1.45 2005/07/12 02:54:20 treectrl Exp $ .so man.macros .TH "treectrl" n 2.0 treectrl "Tk Commands" .BS @@ -145,12 +145,16 @@ package require \fBtreectrl 2.0\fR .sp \fIpathName\fR \fBitem element configure\fR \fIitemDesc\fR \fIcolumn\fR \fIelement\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? .sp +\fIpathName\fR \fBitem element perstate\fR \fIitemDesc\fR \fIcolumn\fR \fIelement\fR \fIoption\fR ?\fIstateList\fR? +.sp \fIpathName\fR \fBitem expand\fR \fIitemDesc\fR ?\fB-recurse\fR? .sp \fIpathName\fR \fBitem firstchild\fR \fIparent\fR ?\fIchild\fR? .sp \fIpathName\fR \fBitem id\fR \fIitemDesc\fR .sp +\fIpathName\fR \fBitem image\fR \fIitemDesc\fR ?\fIcolumn\fR? ?\fIimage\fR? ?\fIcolumn image ...\fR? +.sp \fIpathName\fR \fBitem isancestor\fR \fIitemDesc\fR \fIdescendant\fR .sp \fIpathName\fR \fBitem isopen\fR \fIitemDesc\fR @@ -1515,14 +1519,7 @@ The following forms of the command are supported: .RS .TP \fIpathName\fR \fBitem element actual\fR \fIitemDesc\fR \fIcolumn\fR \fIelement\fR \fIoption\fR -This command returns the current value of the configuration option named \fIoption\fR -associated with \fIelement\fR inside \fIcolumn\fR of the item described by -\fIitemDesc\fR. If \fIoption\fR was configured using the -\fBitem element configure\fR command, the -return value is the same as if the \fBitem element cget\fR command -was used. Otherwise the value of the configuration option of the underlying element is returned. -\fIOption\fR may have any of the values accepted by the type of the -specified element (see \fBELEMENTS\fR below) +Deprecated. Use \fBitem element perstate\fR instead. .TP \fIpathName\fR \fBitem element cget\fR \fIitemDesc\fR \fIcolumn\fR \fIelement\fR \fIoption\fR This command returns the value of the option named \fIoption\fR @@ -1548,11 +1545,11 @@ modifies the given option(s) to have the given value(s) in the \fIelement\fR inside \fIcolumn\fR of the item described by \fIitemDesc\fR; in this case the command returns an empty string. .sp -It is possible to configure multiple elements in more than one column with +It is possible to configure multiple elements in multiple columns with a single call. To configure another element in the same column, append a -\fB+\fR argument followed by the element name followed by one or more -option-value pairs. To configure elements in another column, append a \fB,\fR -argument followed by the column. For example: +\'\fB+\fR' argument followed by the element name. To configure elements in +another column, append a '\fB,\fR' argument followed by the column. +For example: .nf .t item element configure $I \\ @@ -1561,6 +1558,13 @@ argument followed by the column. For example: $C3 $E1 -text "apples and oranges" .fi +.TP +\fIpathName\fR \fBitem element perstate\fR \fIitemDesc\fR \fIcolumn\fR \fIelement\fR \fIoption\fR ?\fIstateList\fR? +This command returns the current value of the per-state option named \fIoption\fR +for \fIelement\fR inside \fIcolumn\fR of the item described by +\fIitemDesc\fR. If \fIstateList\fR is specified, the list of state names (static +and dynamic, see \fBSTATES\fR) is used in place of the current state for +\fIitem\fR and \fIcolumn.\fR .RE .TP \fIpathName\fR \fBitem expand\fR \fIitemDesc\fR ?\fB-recurse\fR? @@ -1592,6 +1596,19 @@ 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 image\fR \fIitemDesc\fR ?\fIcolumn\fR? ?\fIimage\fR? ?\fIcolumn image ...\fR? +This command sets or retrieves the value of the -image option for the first +image element in one or more columns. Keep in mind that the -image option is a +per-state option (see \fBPER-STATE OPTIONS\fR below). +If no \fIcolumn\fR is specified, this command returns a list of values, +one per column. +If no \fIimage\fR is specified, this command returns the value for \fIcolumn\fR. +If one or more \fIcolumn\fR-\fIimage\fR pairs is specified, +then the value of the -image option in each \fIcolumn\fR is set to \fIimage\fR. +Note that this command is provided as a convenience. Use the +\fBitem element configure\fR or \fBitem element cget\fR commands if you want +to set or retrieve the value of the -image option for a specific image element. +.TP \fIpathName\fR \fBitem isancestor\fR \fIitemDesc\fR \fIdescendant\fR Returns 1 if the item described by \fIitemDesc\fR is a direct or indirect parent of the item decribed by \fIdescendant\fR, 0 otherwise. @@ -1775,7 +1792,7 @@ an element in the style specified by \fIstyle\fR. Both \fIelementOld\fR and \fIelementNew\fR must be of the same type (\fBbitmap\fR, \fBtext\fR etc). .TP \fIpathName\fR \fBitem style set\fR \fIitemDesc\fR ?\fIcolumn\fR? ?\fIstyle\fR? ?\fIcolumn style ...\fR? -This command sets or retrieves the style assigned to a column. +This command sets or retrieves the style assigned to one or more columns. If no \fIcolumn\fR is specified, this command returns a list containing the names of the styles set for all columns of the item described by \fIitemDesc\fR. If no \fIstyle\fR is specified, this command @@ -1786,16 +1803,16 @@ then the style in each \fIcolumn\fR is set to \fIstyle\fR. .RE .TP \fIpathName\fR \fBitem text\fR \fIitemDesc\fR ?\fIcolumn\fR? ?\fItext\fR? ?\fIcolumn text ...\fR? -This command sets or retrieves the value of the -text option of the first -text element in a column. -If no \fIcolumn\fR is specified, this command returns a list of strings, +This command sets or retrieves the value of the -text option for the first +text element in one or more columns. +If no \fIcolumn\fR is specified, this command returns a list of values, one per column. -If no \fItext\fR is specified, this command returns the string for \fIcolumn\fR. +If no \fItext\fR is specified, this command returns the value for \fIcolumn\fR. If one or more \fIcolumn\fR-\fItext\fR pairs is specified, -then the string in each \fIcolumn\fR is set to \fItext\fR. +then the value of the -text option in each \fIcolumn\fR is set to \fItext\fR. Note that this command is provided as a convenience. Use the -\fBitem element configure\fR command if you want to set the text of a -specific text element. +\fBitem element configure\fR or \fBitem element cget\fR commands if you +want to set or retrieve the value of the -text option for a specific text element. .TP \fIpathName\fR \fBitem toggle\fR \fIitemDesc\fR ?\fB-recurse\fR? Changes the \fBopen\fR state of the item(s) described by \fIitemDesc\fR. -- cgit v0.12