treectrl - Tk Commands

DESCRIPTION

@@ -539,11 +543,10 @@ Database Name: showButtons
Database Class: ShowButtons

Specifies a boolean value that determines whether this widget -displays a button to the left of any item. -If the button is actually drawn can be configured for every item -with the item hasbutton widget command, but if this option is -set to false, the configuration of an item has no effect. +leaves indentation space to display the expand/collapse buttons next to items. The default value is true. +The item option -button determines whether any item has a button. +See also the treectrl option -showrootbutton.

Command-Line Switch: -showheader
@@ -580,8 +583,9 @@ Database Name: showRootButton
Database Class: ShowRootButton

Specifies a boolean value that determines whether this widget -should draw a button before the root item. -The default value is false. +leaves indentation space to display the expand/collapse button next to the +root item. The default value is false. +The item option -button determines whether the root item has a button.

Command-Line Switch: -showrootlines
@@ -1561,7 +1565,14 @@ and dynamic, see STATES) is used in place of the current s -

pathName item expand itemDesc ?-recurse?

pathName item enabled itemDesc ?boolean?

+ +Returns 1 if the item described by itemDesc has the +state enabled switched on, 0 otherwise. If boolean is specified, +the enabled state is set accordingly. + +

+

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. @@ -1580,7 +1591,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 item id of the first child of the item described by parent. @@ -1589,14 +1600,14 @@ 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. If the item described by itemDesc doesn't exist, this command returns an empty string.

-

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

This command sets or retrieves the value of the per-state -image option for the first image element in one or more columns. @@ -1614,19 +1625,19 @@ Note that this command is provided as a convenience. Use the 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 the state open switched on, 0 otherwise.

-

pathName item lastchild parent ?child?

If child is not specified, returns the item id of the last child of the item described by parent. @@ -1635,7 +1646,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 item id of the next sibling of the item described by sibling. @@ -1644,12 +1655,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 @@ -1660,13 +1671,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 item id of the parent of the item described by itemDesc.

-

pathName item prevsibling sibling ?prev?

If prev is not specified, returns the item id of the previous sibling of the item described by sibling. @@ -1675,7 +1686,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 item ids of all items in the range between first and last, inclusive. @@ -1686,13 +1697,13 @@ The items specified by first and last must ancestor.

-

pathName item remove itemDesc

Removes the item described by itemDesc from the list of children of its parent, so that it will become an orphan.

-

pathName item rnc itemDesc

Returns a list of two integers, which corresponds to the row and column of the item described by itemDesc. The row and column corresponds to @@ -1700,7 +1711,7 @@ the on-screen arrangement of items as determined by the -orient and -wrap options. If the item is not displayed, this command returns an empty string.

-

pathName item sort itemDesc ?option ...?

Sorts the children of the item described by itemDesc, and redisplays the tree with the items in the new order. @@ -1771,7 +1782,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. @@ -1780,7 +1791,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 @@ -1790,7 +1801,7 @@ 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 dynamic states for a single item column, not the item as a whole. If stateDescList is unspecified, @@ -1798,7 +1809,7 @@ this command returns a list containing the names of all the dynamic states which are switched on in column.

-
pathName item state get itemDesc ?stateName?: +
pathName item state get itemDesc ?stateName?: If no stateName is specified, returns a list containing the names of all (static and dynamic) states @@ -1808,7 +1819,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 be the name of a dynamic state (see STATES below), @@ -1824,7 +1835,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 @@ -1833,7 +1844,7 @@ The following forms of the command are supported:

pathName item style elements itemDesc column: +
pathName item style elements itemDesc column: This command returns a list containing the names of elements which were configured by the item element configure command for the item @@ -1841,7 +1852,7 @@ described by itemDesc in column. If there to column an error is returned.

-
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 @@ -1854,7 +1865,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 ...?: This command sets or retrieves the style assigned to one or more columns. @@ -1869,7 +1880,7 @@ 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 for the first text element in one or more columns. @@ -1887,7 +1898,7 @@ Note that this command is provided as a convenience. Use the 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, @@ -1900,7 +1911,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 @@ -1917,7 +1928,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. @@ -1925,7 +1936,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. @@ -1933,7 +1944,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 @@ -1960,7 +1971,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, @@ -1970,7 +1981,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. @@ -1978,7 +1989,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 @@ -1992,7 +2003,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 @@ -2008,7 +2019,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. @@ -2037,7 +2048,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. @@ -2062,7 +2073,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 @@ -2070,14 +2081,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 @@ -2103,7 +2114,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, @@ -2138,19 +2149,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 @@ -2158,21 +2169,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. @@ -2180,29 +2191,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 item ids of all items which have no parent. @@ -2211,12 +2222,40 @@ and can later become an orphan by means of the item remove widget command. The root item is not returned.

-

pathName range first last

Deprecated. Use the item range command instead.

-

pathName state option ?stateName?

pathName scan option args

+ +This command is used to implement scanning on treectrls. It has two forms, +depending on option: +

+
+ +
pathName scan mark x y
+ +Records x and y and the treectrl's current view; used in conjunction with +later scan dragto commands. Typically this command is associated with a +mouse button press in the widget and x and y are the coordinates of the +mouse. It returns an empty string. + +

+
pathName scan dragto x y ?gain?
+ +This command computes the difference between its x and y arguments (which +are typically mouse coordinates) and the x and y arguments to the last +scan mark command for the widget. It then adjusts the view by gain +times the difference in coordinates, where gain defaults to 10. This +command is typically associated with mouse motion events in the widget, +to produce the effect of dragging the treectrl at high speed through its window. +The return value is an empty string. +
+ + + +

pathName state option ?stateName?

This command is used to manipulate the list of user-defined states, see section STATES below. @@ -2226,13 +2265,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 an existing state.

-
pathName state linkage stateName
+
pathName state linkage stateName
Returns a string indicating whether the specified state is user-defined @@ -2240,18 +2279,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. @@ -2261,14 +2300,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 a valid item description. @@ -2281,7 +2320,7 @@ A <Selection> event is generated if any items were added selection.

-
pathName selection anchor ?itemDesc?
+
pathName selection anchor ?itemDesc?
If itemDesc is specified, the selection anchor is set to the described item. @@ -2292,7 +2331,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 a valid item description. @@ -2306,13 +2345,13 @@ A <Selection> event is generated if any items were remove selection.

-
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 item ids of all of the items in the treectrl that are currently selected. @@ -2320,13 +2359,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 described 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 item descriptions. @@ -2336,7 +2375,7 @@ for those items which are also in select). A <Selection> event is generated if any items were selected or deselected.
-

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

This command is used to manipulate styles, which can be thought of as a geometry manager for elements. @@ -2346,7 +2385,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. @@ -2354,7 +2393,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 @@ -2383,7 +2422,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 @@ -2394,7 +2433,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 @@ -2402,7 +2441,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 @@ -2417,7 +2456,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 @@ -2538,17 +2577,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. @@ -2556,7 +2595,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 @@ -2569,7 +2608,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. @@ -2577,7 +2616,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. @@ -2595,7 +2634,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. @@ -2603,7 +2642,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 @@ -2614,7 +2653,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. @@ -2622,7 +2661,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. @@ -2955,8 +2994,10 @@ This state can be modified by means of the widget command activat

enabled
-This state is set for every item, when it is created. -It cannot be modified. +This state is set for every item when it is created. +Disabled items can not be selected and are ignored by the default bindings +when navigating via the keyboard. +This state can be modified by means of the widget command item enabled.

focus
@@ -3379,19 +3420,15 @@ the item specified as argument of the last successful selection a widget command, or the root item if no such call happened yet.

-
first ?visible?
-Indicates the first item of the treectrl, i.e. the root item. -If visible is specified and the widget is configured with --showroot no, the first visible child of the root node -is specified instead. +
first QUALIFIERS
+Indicates the first item of the treectrl (the root item), +or the first item matching QUALIFIERS.

-
end ?visible?
-
last ?visible?
-Indicates the last item of the treectrl. -If visible is specified and the last item is currently not visible, -i.e. one of its father nodes is collapsed, -the last visible item is specified instead. +
end QUALIFIERS
+
last QUALIFIERS
+Indicates the last item of the treectrl, +or the last item matching QUALIFIERS.

nearest x y
@@ -3403,7 +3440,7 @@ Indicates the item in the given row and column The row and column corresponds to the on-screen arrangement of items as determined by the -orient and -wrap options. -You can memorize rnc as abbreviation of "row 'n' column". +You can memorize rnc as an abbreviation of "row 'n' column".

root
@@ -3430,15 +3467,15 @@ Use the item one row below in this column. Use the item in the last row of this column.

-
child n ?visible?
+
child n QUALIFIERS
Use the nth child of the item.

-
firstchild ?visible?
+
firstchild QUALIFIERS
Use the first child of the item.

-
lastchild ?visible?
+
lastchild QUALIFIERS
Use the last child of the item.

@@ -3450,13 +3487,13 @@ Use the item one column to the left in the same row. Use the item of the first column in the same row.

-
next ?visible?
-Use the next item, which is the first existant (or visible) item of the +
next QUALIFIERS
+Use the next item, which is the first item from the following list: the first child, the next sibling or the next sibling of -the nearest parent which has one. +the nearest ancestor which has one.

-
nextsibling ?visible?
+
nextsibling QUALIFIERS
Use the next sibling of the item.

@@ -3464,12 +3501,12 @@ Use the next sibling of the item. Use the parent of the item.

-
prev ?visible?
+
prev QUALIFIERS
Use the last child of the previous sibling, -or the parent if there is no previos sibling. +or the parent if there is no previous sibling.

-
prevsibling ?visible?
+
prevsibling QUALIFIERS
Use the previous sibling of the item.

@@ -3481,7 +3518,7 @@ Use the item one column to the right in the same row. Use the item of the last column in the same row.

-
sibling n ?visible?
+
sibling n QUALIFIERS
Use the nth child of the item's parent.

@@ -3489,6 +3526,34 @@ Use the nth child of the item's parent. Use the item in the first row of this column.
+The word QUALIFIERS above represents a list of zero or more of the +following terms that changes which item is chosen: + +
+
state stateList
+StateList is a list of item state names (static and dynamic, see STATES). +Only items that have the given states set (or unset if the '!' prefix is used) +are considered. +

+To get the first item in the list that is enabled: +

+$T item id "first state enabled" +
+To get the first item in the list that is not open: +

+$T item id "first state !open" +
+ +

+
visible
+When this qualifier is given, only items that are displayed are considered. +

+To get the first item in the list that is displayed: +

+$T item id "first visible" +
+
+
EVENTS AND SCRIPT SUBSTITUTIONS

diff --git a/doc/treectrl.man b/doc/treectrl.man index 6dc91cb..f146735 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.34 2006/09/08 22:10:04 treectrl Exp $} + $Id: treectrl.man,v 1.35 2006/09/16 20:04:52 treectrl Exp $} ][manpage_begin treectrl n 2.1.1] [moddesc {Tk Commands}] [titledesc {Create and manipulate hierarchical multicolumn widgets}] @@ -245,11 +245,10 @@ or [const extended]; the default value is [const browse]. [tkoption_def -showbuttons showButtons ShowButtons] Specifies a boolean value that determines whether this widget -displays a button to the left of any item. -If the button is actually drawn can be configured for every item -with the [cmd {item hasbutton}] widget command, but if this option is -set to false, the configuration of an item has no effect. +leaves indentation space to display the expand/collapse buttons next to items. The default value is true. +The item option [option -button] determines whether any item has a button. +See also the treectrl option [option -showrootbutton]. [tkoption_def -showheader showHeader ShowHeader] Specifies a boolean value that determines whether this widget @@ -270,8 +269,9 @@ The default value is true. [tkoption_def -showrootbutton showRootButton ShowRootButton] Specifies a boolean value that determines whether this widget -should draw a button before the root item. -The default value is false. +leaves indentation space to display the expand/collapse button next to the +root item. The default value is false. +The item option [option -button] determines whether the root item has a button. [tkoption_def -showrootlines showRootLines ShowRootLines] Specifies a boolean value that determines whether this widget @@ -1089,6 +1089,11 @@ and dynamic, see [sectref STATES]) is used in place of the current state for [list_end] +[call [arg pathName] [cmd {item enabled}] [arg itemDesc] [opt [arg boolean]]] +Returns 1 if the item described by [arg itemDesc] has the +state [const enabled] switched on, 0 otherwise. If [arg boolean] is specified, +the [const enabled] state is set accordingly. + [call [arg pathName] [cmd {item expand}] [arg itemDesc] [opt [option -recurse]]] Switches on the [const open] state of the item(s) described by [arg itemDesc]. If the item has descendants, they are now displayed. @@ -1655,6 +1660,29 @@ by means of the [cmd {item remove}] widget command. The root item is not returne [call [arg pathName] [cmd range] [arg first] [arg last]] Deprecated. Use the [cmd {item range}] command instead. +[call [arg pathName] [cmd scan] [arg option] [arg args]] +This command is used to implement scanning on treectrls. It has two forms, +depending on [arg option]: +[list_begin definitions] + +[call [arg pathName] [cmd {scan mark}] [arg x] [arg y]] +Records [arg x] and [arg y] and the treectrl's current view; used in conjunction with +later [cmd {scan dragto}] commands. Typically this command is associated with a +mouse button press in the widget and [arg x] and [arg y] are the coordinates of the +mouse. It returns an empty string. + +[call [arg pathName] [cmd {scan dragto}] [arg x] [arg y] [opt [arg gain]]] +This command computes the difference between its [arg x] and [arg y] arguments (which +are typically mouse coordinates) and the [arg x] and [arg y] arguments to the last +[cmd {scan mark}] command for the widget. It then adjusts the view by [arg gain] +times the difference in coordinates, where [arg gain] defaults to 10. This +command is typically associated with mouse motion events in the widget, +to produce the effect of dragging the treectrl at high speed through its window. +The return value is an empty string. +[list_end] + + + [call [arg pathName] [cmd state] [arg option] [opt [arg stateName]]] This command is used to manipulate the list of user-defined states, see section [sectref STATES] below. @@ -2290,8 +2318,10 @@ the root item will become the active item. This state can be modified by means of the widget command [cmd activate]. [lst_item [const enabled]] -This state is set for every item, when it is created. -It cannot be modified. +This state is set for every item when it is created. +Disabled items cannot be selected and are ignored by the default bindings +when navigating via the keyboard. +This state can be modified by means of the widget command [cmd {item enabled}]. [lst_item [const focus]] This state is set for every item, @@ -2667,18 +2697,14 @@ Indicates the anchor item of the selection, i.e. normally the item specified as argument of the last successful [cmd {selection anchor}] widget command, or the root item if no such call happened yet. -[lst_item "[const first] [opt [const visible]]"] -Indicates the first item of the treectrl, i.e. the root item. -If [const visible] is specified and the widget is configured with -[option -showroot] [const no], the first visible child of the root node -is specified instead. +[lst_item "[const first] [arg QUALIFIERS]"] +Indicates the first item of the treectrl (the root item), +or the first item matching [arg QUALIFIERS]. -[lst_item "[const end] [opt [const visible]]"] -[lst_item "[const last] [opt [const visible]]"] -Indicates the last item of the treectrl. -If [const visible] is specified and the last item is currently not visible, -i.e. one of its father nodes is collapsed, -the last visible item is specified instead. +[lst_item "[const end] [arg QUALIFIERS]"] +[lst_item "[const last] [arg QUALIFIERS]"] +Indicates the last item of the treectrl, +or the last item matching [arg QUALIFIERS]. [lst_item "[const nearest] [arg {x y}]"] Indicates the item nearest to the point given by [arg x] and [arg y]. @@ -2688,7 +2714,7 @@ Indicates the item in the given [arg row] and [arg column]. The row and column corresponds to the on-screen arrangement of items as determined by the -orient and -wrap options. -You can memorize [const rnc] as abbreviation of "row 'n' column". +You can memorize [const rnc] as an abbreviation of "row 'n' column". [lst_item [const root]] Indicates the root item of the treectrl. @@ -2711,13 +2737,13 @@ Use the item one row below in this column. [lst_item [const bottom]] Use the item in the last row of this column. -[lst_item "[const child] [arg n] [opt [const visible]]"] +[lst_item "[const child] [arg n] [arg QUALIFIERS]"] Use the [arg n]th child of the item. -[lst_item "[const firstchild] [opt [const visible]]"] +[lst_item "[const firstchild] [arg QUALIFIERS]"] Use the first child of the item. -[lst_item "[const lastchild] [opt [const visible]]"] +[lst_item "[const lastchild] [arg QUALIFIERS]"] Use the last child of the item. [lst_item [const left]] @@ -2726,22 +2752,22 @@ Use the item one column to the left in the same row. [lst_item [const leftmost]] Use the item of the first column in the same row. -[lst_item "[const next] [opt [const visible]]"] -Use the next item, which is the first existant (or visible) item of the +[lst_item "[const next] [arg QUALIFIERS]"] +Use the next item, which is the first item from the following list: the first child, the next sibling or the next sibling of -the nearest parent which has one. +the nearest ancestor which has one. -[lst_item "[const nextsibling] [opt [const visible]]"] +[lst_item "[const nextsibling] [arg QUALIFIERS]"] Use the next sibling of the item. [lst_item [const parent]] Use the parent of the item. -[lst_item "[const prev] [opt [const visible]]"] +[lst_item "[const prev] [arg QUALIFIERS]"] Use the last child of the previous sibling, or the parent if there is no previous sibling. -[lst_item "[const prevsibling] [opt [const visible]]"] +[lst_item "[const prevsibling] [arg QUALIFIERS]"] Use the previous sibling of the item. [lst_item [const right]] @@ -2750,13 +2776,40 @@ Use the item one column to the right in the same row. [lst_item [const rightmost]] Use the item of the last column in the same row. -[lst_item "[const sibling] [arg n] [opt [const visible]]"] +[lst_item "[const sibling] [arg n] [arg QUALIFIERS]"] Use the [arg n]th child of the item's parent. [lst_item [const top]] Use the item in the first row of this column. [list_end] +The word [arg QUALIFIERS] above represents a list of zero or more of the +following terms that changes which item is chosen: + +[list_begin definitions] +[lst_item "[const state] [arg stateList]"] +[arg StateList] is a list of item state names (static and dynamic, see [sectref STATES]). +Only items that have the given states set (or unset if the '!' prefix is used) +are considered. +[nl] +To get the first item in the list that is enabled: +[example_begin] +$T item id "first state enabled" +[example_end] +To get the first item in the list that is not open: +[example_begin] +$T item id "first state !open" +[example_end] + +[lst_item [const visible]] +When this qualifier is given, only items that are displayed are considered. +[nl] +To get the first item in the list that is displayed: +[example_begin] +$T item id "first visible" +[example_end] +[list_end] + [section {EVENTS AND SCRIPT SUBSTITUTIONS}] The [arg script] argument to [cmd {notify bind}] is a Tcl script, which will be diff --git a/doc/treectrl.n b/doc/treectrl.n index e39e5a6..06c5ea8 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.50 2006/09/08 22:10:04 treectrl Exp $ +'\" $Id: treectrl.n,v 1.51 2006/09/16 20:04:52 treectrl Exp $ .so man.macros .TH "treectrl" n 2.1.1 treectrl "Tk Commands" .BS @@ -149,6 +149,8 @@ package require \fBtreectrl 2.1.1\fR .sp \fIpathName\fR \fBitem element perstate\fR \fIitemDesc\fR \fIcolumn\fR \fIelement\fR \fIoption\fR ?\fIstateList\fR? .sp +\fIpathName\fR \fBitem enabled\fR \fIitemDesc\fR ?\fIboolean\fR? +.sp \fIpathName\fR \fBitem expand\fR \fIitemDesc\fR ?\fB-recurse\fR? .sp \fIpathName\fR \fBitem firstchild\fR \fIparent\fR ?\fIchild\fR? @@ -255,6 +257,12 @@ package require \fBtreectrl 2.1.1\fR .sp \fIpathName\fR \fBrange\fR \fIfirst\fR \fIlast\fR .sp +\fIpathName\fR \fBscan\fR \fIoption\fR \fIargs\fR +.sp +\fIpathName\fR \fBscan mark\fR \fIx\fR \fIy\fR +.sp +\fIpathName\fR \fBscan dragto\fR \fIx\fR \fIy\fR ?\fIgain\fR? +.sp \fIpathName\fR \fBstate\fR \fIoption\fR ?\fIstateName\fR? .sp \fIpathName\fR \fBstate define\fR \fIstateName\fR @@ -740,11 +748,10 @@ Database Class: \fBShowButtons\fR .fi .IP Specifies a boolean value that determines whether this widget -displays a button to the left of any item. -If the button is actually drawn can be configured for every item -with the \fBitem hasbutton\fR widget command, but if this option is -set to false, the configuration of an item has no effect. +leaves indentation space to display the expand/collapse buttons next to items. The default value is true. +The item option \fB-button\fR determines whether any item has a button. +See also the treectrl option \fB-showrootbutton\fR. .LP .nf .ta 6c @@ -793,8 +800,9 @@ Database Class: \fBShowRootButton\fR .fi .IP Specifies a boolean value that determines whether this widget -should draw a button before the root item. -The default value is false. +leaves indentation space to display the expand/collapse button next to the +root item. The default value is false. +The item option \fB-button\fR determines whether the root item has a button. .LP .nf .ta 6c @@ -1641,6 +1649,11 @@ and dynamic, see \fBSTATES\fR) is used in place of the current state for \fIitem\fR and \fIcolumn.\fR .RE .TP +\fIpathName\fR \fBitem enabled\fR \fIitemDesc\fR ?\fIboolean\fR? +Returns 1 if the item described by \fIitemDesc\fR has the +state \fBenabled\fR switched on, 0 otherwise. If \fIboolean\fR is specified, +the \fBenabled\fR state is set accordingly. +.TP \fIpathName\fR \fBitem expand\fR \fIitemDesc\fR ?\fB-recurse\fR? Switches on the \fBopen\fR state of the item(s) described by \fIitemDesc\fR. If the item has descendants, they are now displayed. @@ -2162,6 +2175,27 @@ by means of the \fBitem remove\fR widget command. The root item is not returned. \fIpathName\fR \fBrange\fR \fIfirst\fR \fIlast\fR Deprecated. Use the \fBitem range\fR command instead. .TP +\fIpathName\fR \fBscan\fR \fIoption\fR \fIargs\fR +This command is used to implement scanning on treectrls. It has two forms, +depending on \fIoption\fR: +.RS +.TP +\fIpathName\fR \fBscan mark\fR \fIx\fR \fIy\fR +Records \fIx\fR and \fIy\fR and the treectrl's current view; used in conjunction with +later \fBscan dragto\fR commands. Typically this command is associated with a +mouse button press in the widget and \fIx\fR and \fIy\fR are the coordinates of the +mouse. It returns an empty string. +.TP +\fIpathName\fR \fBscan dragto\fR \fIx\fR \fIy\fR ?\fIgain\fR? +This command computes the difference between its \fIx\fR and \fIy\fR arguments (which +are typically mouse coordinates) and the \fIx\fR and \fIy\fR arguments to the last +\fBscan mark\fR command for the widget. It then adjusts the view by \fIgain\fR +times the difference in coordinates, where \fIgain\fR defaults to 10. This +command is typically associated with mouse motion events in the widget, +to produce the effect of dragging the treectrl at high speed through its window. +The return value is an empty string. +.RE +.TP \fIpathName\fR \fBstate\fR \fIoption\fR ?\fIstateName\fR? This command is used to manipulate the list of user-defined states, see section \fBSTATES\fR below. @@ -2774,8 +2808,10 @@ the root item will become the active item. This state can be modified by means of the widget command \fBactivate\fR. .TP \fBenabled\fR -This state is set for every item, when it is created. -It cannot be modified. +This state is set for every item when it is created. +Disabled items can not be selected and are ignored by the default bindings +when navigating via the keyboard. +This state can be modified by means of the widget command \fBitem enabled\fR. .TP \fBfocus\fR This state is set for every item, @@ -3125,19 +3161,15 @@ Indicates the anchor item of the selection, i.e. normally the item specified as argument of the last successful \fBselection anchor\fR widget command, or the root item if no such call happened yet. .TP -\fBfirst\fR ?\fBvisible\fR? -Indicates the first item of the treectrl, i.e. the root item. -If \fBvisible\fR is specified and the widget is configured with -\fB-showroot\fR \fBno\fR, the first visible child of the root node -is specified instead. +\fBfirst\fR \fIQUALIFIERS\fR +Indicates the first item of the treectrl (the root item), +or the first item matching \fIQUALIFIERS\fR. .TP -\fBend\fR ?\fBvisible\fR? +\fBend\fR \fIQUALIFIERS\fR .TP -\fBlast\fR ?\fBvisible\fR? -Indicates the last item of the treectrl. -If \fBvisible\fR is specified and the last item is currently not visible, -i.e. one of its father nodes is collapsed, -the last visible item is specified instead. +\fBlast\fR \fIQUALIFIERS\fR +Indicates the last item of the treectrl, +or the last item matching \fIQUALIFIERS\fR. .TP \fBnearest\fR \fIx y\fR Indicates the item nearest to the point given by \fIx\fR and \fIy\fR. @@ -3147,7 +3179,7 @@ Indicates the item in the given \fIrow\fR and \fIcolumn\fR. The row and column corresponds to the on-screen arrangement of items as determined by the -orient and -wrap options. -You can memorize \fBrnc\fR as abbreviation of "row 'n' column". +You can memorize \fBrnc\fR as an abbreviation of "row 'n' column". .TP \fBroot\fR Indicates the root item of the treectrl. @@ -3167,13 +3199,13 @@ Use the item one row below in this column. \fBbottom\fR Use the item in the last row of this column. .TP -\fBchild\fR \fIn\fR ?\fBvisible\fR? +\fBchild\fR \fIn\fR \fIQUALIFIERS\fR Use the \fIn\fRth child of the item. .TP -\fBfirstchild\fR ?\fBvisible\fR? +\fBfirstchild\fR \fIQUALIFIERS\fR Use the first child of the item. .TP -\fBlastchild\fR ?\fBvisible\fR? +\fBlastchild\fR \fIQUALIFIERS\fR Use the last child of the item. .TP \fBleft\fR @@ -3182,22 +3214,22 @@ Use the item one column to the left in the same row. \fBleftmost\fR Use the item of the first column in the same row. .TP -\fBnext\fR ?\fBvisible\fR? -Use the next item, which is the first existant (or visible) item of the +\fBnext\fR \fIQUALIFIERS\fR +Use the next item, which is the first item from the following list: the first child, the next sibling or the next sibling of -the nearest parent which has one. +the nearest ancestor which has one. .TP -\fBnextsibling\fR ?\fBvisible\fR? +\fBnextsibling\fR \fIQUALIFIERS\fR Use the next sibling of the item. .TP \fBparent\fR Use the parent of the item. .TP -\fBprev\fR ?\fBvisible\fR? +\fBprev\fR \fIQUALIFIERS\fR Use the last child of the previous sibling, -or the parent if there is no previos sibling. +or the parent if there is no previous sibling. .TP -\fBprevsibling\fR ?\fBvisible\fR? +\fBprevsibling\fR \fIQUALIFIERS\fR Use the previous sibling of the item. .TP \fBright\fR @@ -3206,11 +3238,41 @@ Use the item one column to the right in the same row. \fBrightmost\fR Use the item of the last column in the same row. .TP -\fBsibling\fR \fIn\fR ?\fBvisible\fR? +\fBsibling\fR \fIn\fR \fIQUALIFIERS\fR Use the \fIn\fRth child of the item's parent. .TP \fBtop\fR Use the item in the first row of this column. +The word \fIQUALIFIERS\fR above represents a list of zero or more of the +following terms that changes which item is chosen: +.TP +\fBstate\fR \fIstateList\fR +\fIStateList\fR is a list of item state names (static and dynamic, see \fBSTATES\fR). +Only items that have the given states set (or unset if the '!' prefix is used) +are considered. +.sp +To get the first item in the list that is enabled: +.nf + +$T item id "first state enabled" + +.fi +To get the first item in the list that is not open: +.nf + +$T item id "first state !open" + +.fi +.TP +\fBvisible\fR +When this qualifier is given, only items that are displayed are considered. +.sp +To get the first item in the list that is displayed: +.nf + +$T item id "first visible" + +.fi .SH "EVENTS AND SCRIPT SUBSTITUTIONS" The \fIscript\fR argument to \fBnotify bind\fR is a Tcl script, which will be evaluated whenever the given event is generated. \fIScript\fR will be executed -- cgit v0.12