diff options
Diffstat (limited to 'doc/ttk_treeview.n')
| -rw-r--r-- | doc/ttk_treeview.n | 484 |
1 files changed, 484 insertions, 0 deletions
diff --git a/doc/ttk_treeview.n b/doc/ttk_treeview.n new file mode 100644 index 0000000..33cca55 --- /dev/null +++ b/doc/ttk_treeview.n @@ -0,0 +1,484 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.so man.macros +.TH ttk::treeview n 8.5.9 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::treeview \- hierarchical multicolumn data display widget +.SH SYNOPSIS +\fBttk::treeview \fIpathname \fR?\fIoptions\fR? +.BE +.SH DESCRIPTION +.PP +The \fBttk::treeview\fR widget displays a hierarchical collection of items. +Each item has a textual label, an optional image, +and an optional list of data values. +The data values are displayed in successive columns after +the tree label. +.PP +The order in which data values are displayed may be controlled +by setting the \fB\-displaycolumns\fR widget option. +The tree widget can also display column headings. +Columns may be accessed by number or by symbolic names +listed in the \fB\-columns\fR widget option; +see \fBCOLUMN IDENTIFIERS\fR. +.PP +Each item is identified by a unique name. +The widget will generate item IDs if they are not supplied by the caller. +There is a distinguished root item, named \fB{}\fR. +The root item itself is not displayed; +its children appear at the top level of the hierarchy. +.PP +Each item also has a list of \fItags\fR, +which can be used to associate event bindings with individual items +and control the appearance of the item. +.\" .PP +.\" @@@HERE: describe selection, focus item +.PP +Treeview widgets support horizontal and vertical scrolling with the +standard \fB\-\fR[\fBxy\fR]\fBscrollcommand\fR options +and [\fBxy\fR]\fBview\fR widget commands. +.SO ttk_widget +\-class \-cursor \-takefocus +\-style \-xscrollcommand \-yscrollcommand +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-columns columns Columns +A list of column identifiers, +specifying the number of columns and their names. +.\"X: This is a read-only option; it may only be set when the widget is created. +.OP \-displaycolumns displayColumns DisplayColumns +A list of column identifiers +(either symbolic names or integer indices) +specifying which data columns are displayed +and the order in which they appear, +or the string \fB#all\fP. +If set to \fB#all\fP (the default), +all columns are shown in the order given. +.OP \-height height Height +Specifies the number of rows which should be visible. +Note: +the requested width is determined from the sum of the column widths. +.OP \-padding padding Padding +Specifies the internal padding for the widget. +The padding is a list of up to four length specifications; +see \fBTtk_GetPaddingFromObj()\fR for details. +.OP \-selectmode selectMode SelectMode +Controls how the built-in class bindings manage the selection. +One of \fBextended\fR, \fBbrowse\fR, or \fBnone\fR. +.RS +.PP +If set to \fBextended\fR (the default), multiple items may be selected. +If \fBbrowse\fR, only a single item will be selected at a time. +If \fBnone\fR, the selection will not be changed. +.PP +Note that application code and tag bindings can set the selection +however they wish, regardless of the value of \fB\-selectmode\fR. +.RE +.OP \-show show Show +A list containing zero or more of the following values, specifying +which elements of the tree to display. +.RS +.IP \fBtree\fR +Display tree labels in column #0. +.IP \fBheadings\fR +Display the heading row. +.PP +The default is \fBtree headings\fR, i.e., show all elements. +.PP +\fBNOTE:\fR Column #0 always refers to the tree column, +even if \fB\-show tree\fR is not specified. +.RE +.SH "WIDGET COMMAND" +.PP +.TP +\fIpathname \fBbbox \fIitem\fR ?\fIcolumn\fR? +Returns the bounding box (relative to the treeview widget's window) +of the specified \fIitem\fR +in the form \fIx y width height\fR. +If \fIcolumn\fR is specified, returns the bounding box of that cell. +If the \fIitem\fR is not visible +(i.e., if it is a descendant of a closed item or is scrolled offscreen), +returns the empty list. +.TP +\fIpathname \fBcget \fIoption\fR +Returns the current value of the specified \fIoption\fR; see \fIttk::widget(n)\fR. +.TP +\fIpathname \fBchildren \fIitem\fR ?\fInewchildren\fR? +If \fInewchildren\fR is not specified, +returns the list of children belonging to \fIitem\fR. +.RS +.PP +If \fInewchildren\fR is specified, replaces \fIitem\fR's child list +with \fInewchildren\fR. +Items in the old child list not present in the new child list +are detached from the tree. +None of the items in \fInewchildren\fR may be an ancestor +of \fIitem\fR. +.RE +.TP +\fIpathname \fBcolumn \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? +Query or modify the options for the specified \fIcolumn\fR. +If no \fI\-option\fR is specified, +returns a dictionary of option/value pairs. +If a single \fI\-option\fR is specified, +returns the value of that option. +Otherwise, the options are updated with the specified values. +The following options may be set on each column: +.RS +.TP +\fB\-id \fIname\fR +The column name. This is a read-only option. +For example, [\fI$pathname \fBcolumn #\fIn \fB\-id\fR] +returns the data column associated with display column #\fIn\fR. +.TP +\fB\-anchor\fR +Specifies how the text in this column should be aligned +with respect to the cell. One of +\fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, +\fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. +.TP +\fB\-minwidth\fR +The minimum width of the column in pixels. +The treeview widget will not make the column any smaller than +\fB\-minwidth\fR when the widget is resized or the user drags a +column separator. +.TP +\fB\-stretch\fR +Specifies whether or not the column's width should be adjusted +when the widget is resized. +.TP +\fB\-width \fIw\fR +The width of the column in pixels. Default is something reasonable, +probably 200 or so. +.PP +Use \fIpathname column #0\fR to configure the tree column. +.RE +.TP +\fIpathname \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Modify or query widget options; see \fIttk::widget(n)\fR. +.TP +\fIpathname \fBdelete \fIitemList\fR +Deletes each of the items in \fIitemList\fR and all of their descendants. +The root item may not be deleted. +See also: \fBdetach\fR. +.TP +\fIpathname \fBdetach \fIitemList\fR +Unlinks all of the specified items in \fIitemList\fR from the tree. +The items and all of their descendants are still present +and may be reinserted at another point in the tree +with the \fBmove\fR operation, +but will not be displayed until that is done. +The root item may not be detached. +See also: \fBdelete\fR. +.TP +\fIpathname \fBexists \fIitem\fR +Returns 1 if the specified \fIitem\fR is present in the tree, +0 otherwise. +.TP +\fIpathname \fBfocus \fR?\fIitem\fR? +If \fIitem\fR is specified, sets the focus item to \fIitem\fR. +Otherwise, returns the current focus item, or \fB{}\fR if there is none. +.\" Need: way to clear the focus item. {} works for this... +.TP +\fIpathname \fBheading \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? +Query or modify the heading options for the specified \fIcolumn\fR. +Valid options are: +.RS +.TP +\fB\-text \fItext\fR +The text to display in the column heading. +.TP +\fB\-image \fIimageName\fR +Specifies an image to display to the right of the column heading. +.TP +\fB\-anchor \fIanchor\fR +Specifies how the heading text should be aligned. +One of the standard Tk anchor values. +.TP +\fB\-command \fIscript\fR +A script to evaluate when the heading label is pressed. +.PP +Use \fIpathname heading #0\fR to configure the tree column heading. +.RE +.TP +\fIpathname \fBidentify \fIcomponent x y\fR +Returns a description of the specified \fIcomponent\fR +under the point given by \fIx\fR and \fIy\fR, +or the empty string if no such \fIcomponent\fR is present at that position. +The following subcommands are supported: +.RS +.TP +\fIpathname \fBidentify region \fIx y\fR +.RS +Returns one of: +.IP heading +Tree heading area; +use [\fBpathname identify column \fIx y\fR] +to determine the heading number. +.IP separator +Space between two column headings; +[\fBpathname identify column \fIx y\fR] +will return the display column identifier +of the heading to left of the separator. +.IP tree +The tree area. +.IP cell +A data cell. +.RE +\fIpathname \fBidentify item \fIx y\fR +Returns the item ID of the item at position \fIy\fR. +.TP +\fIpathname \fBidentify column \fIx y\fR +Returns the data column identifier of the cell at position \fIx\fR. +The tree column has ID \fB#0\fR. +.TP +\fIpathname \fBidentify element \fIx y\fR +The element at position \fIx,y\fR. +.TP +\fIpathname \fBidentify row \fIx y\fR +Obsolescent synonym for \fIpathname \fBidentify item\fR. +.PP +See \fBCOLUMN IDENTIFIERS\fR for a discussion of display columns +and data columns. +.RE +.TP +\fIpathname \fBindex \fIitem\fR +Returns the integer index of \fIitem\fR within its parent's list of children. +.TP +\fIpathname \fBinsert \fIparent index\fR ?\fB\-id \fIid\fR? \fIoptions...\fR +Creates a new item. +\fIparent\fR is the item ID of the parent item, +or the empty string \fB{}\fR +to create a new top-level item. +\fIindex\fR is an integer, or the value \fBend\fR, specifying where in the +list of \fIparent\fR's children to insert the new item. +If \fIindex\fR is less than or equal to zero, +the new node is inserted at the beginning; +if \fIindex\fR is greater than or equal to the current number of children, +it is inserted at the end. +If \fB\-id\fR is specified, it is used as the item identifier; +\fIid\fR must not already exist in the tree. +Otherwise, a new unique identifier is generated. +.RS +.PP +\fIpathname \fBinsert\fR returns the item identifier of the +newly created item. +See \fBITEM OPTIONS\fR for the list of available options. +.RE +.TP +\fIpathname \fBinstate \fIstatespec\fR ?\fIscript\fR? +Test the widget state; see \fIttk::widget(n)\fR. +.TP +\fIpathname \fBitem \fIitem\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? +Query or modify the options for the specified \fIitem\fR. +If no \fI\-option\fR is specified, +returns a dictionary of option/value pairs. +If a single \fI\-option\fR is specified, +returns the value of that option. +Otherwise, the item's options are updated with the specified values. +See \fBITEM OPTIONS\fR for the list of available options. +.TP +\fIpathname \fBmove \fIitem parent index\fR +Moves \fIitem\fR to position \fIindex\fR in \fIparent\fR's list of children. +It is illegal to move an item under one of its descendants. +.RS +.PP +If \fIindex\fR is less than or equal to zero, \fIitem\fR is moved +to the beginning; if greater than or equal to the number of children, +it is moved to the end. +.RE +.TP +\fIpathname \fBnext \fIitem\fR +Returns the identifier of \fIitem\fR's next sibling, +or \fB{}\fR if \fIitem\fR is the last child of its parent. +.TP +\fIpathname \fBparent \fIitem\fR +Returns the ID of the parent of \fIitem\fR, +or \fB{}\fR if \fIitem\fR is at the top level of the hierarchy. +.TP +\fIpathname \fBprev \fIitem\fR +Returns the identifier of \fIitem\fR's previous sibling, +or \fB{}\fR if \fIitem\fR is the first child of its parent. +.TP +\fIpathname \fBsee \fIitem\fR +Ensure that \fIitem\fR is visible: +sets all of \fIitem\fR's ancestors to \fB\-open true\fR, +and scrolls the widget if necessary so that \fIitem\fR is +within the visible portion of the tree. +.TP +\fIpathname \fBselection\fR ?\fIselop itemList\fR? +If \fIselop\fR is not specified, returns the list of selected items. +Otherwise, \fIselop\fR is one of the following: +.RS +.TP +\fIpathname \fBselection set \fIitemList\fR +\fIitemList\fR becomes the new selection. +.TP +\fIpathname \fBselection add \fIitemList\fR +Add \fIitemList\fR to the selection +.TP +\fIpathname \fBselection remove \fIitemList\fR +Remove \fIitemList\fR from the selection +.TP +\fIpathname \fBselection toggle \fIitemList\fR +Toggle the selection state of each item in \fIitemList\fR. +.RE +.TP +\fIpathname \fBset \fIitem\fR ?\fIcolumn\fR? ?\fIvalue\fR? +With one argument, returns a dictionary of column/value pairs +for the specified \fIitem\fR. +With two arguments, returns the current value of the specified \fIcolumn\fR. +With three arguments, sets the value of column \fIcolumn\fR +in item \fIitem\fR to the specified \fIvalue\fR. +See also \fBCOLUMN IDENTIFIERS\fR. +.TP +\fIpathname \fBstate\fR ?\fIstateSpec\fR? +Modify or query the widget state; see \fIttk::widget(n)\fR. +.TP +\fIpathName \fBtag \fIargs...\fR +.RS +.TP +\fIpathName \fBtag bind \fItagName \fR?\fIsequence\fR? ?\fIscript\fR? +Add a Tk binding script for the event sequence \fIsequence\fR +to the tag \fItagName\fR. When an X event is delivered to an item, +binding scripts for each of the item's \fB\-tags\fR are evaluated +in order as per \fIbindtags(n)\fR. +.RS +.PP +\fB<KeyPress>\fR, \fB<KeyRelease>\fR, and virtual events +are sent to the focus item. +\fB<ButtonPress>\fR, \fB<ButtonRelease>\fR, and \fB<Motion>\fR events +are sent to the item under the mouse pointer. +No other event types are supported. +.PP +The binding \fIscript\fR undergoes \fB%\fR-substitutions before +evaluation; see \fBbind(n)\fR for details. +.RE +.TP +\fIpathName \fBtag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue option value...\fR? +Query or modify the options for the specified \fItagName\fR. +If one or more \fIoption/value\fR pairs are specified, +sets the value of those options for the specified tag. +If a single \fIoption\fR is specified, +returns the value of that option +(or the empty string if the option has not been specified for \fItagName\fR). +With no additional arguments, +returns a dictionary of the option settings for \fItagName\fR. +See \fBTAG OPTIONS\fR for the list of available options. +.TP +\fIpathName \fBtag has \fItagName\fR ?\fIitem\fR? +If \fIitem\fR is specified, returns 1 or 0 +depending on whether the specified item has the named tag. +Otherwise, returns a list of all items which have +the specified tag. +.TP +\fIpathName \fBtag names\fR +Returns a list of all tags used by the widget. +.TP +\fIpathName \fBtag add\fR \fItag\fR \fIitems\fR +Adds the specified \fItag\fR to each of the listed \fIitems\fR. +If \fItag\fR is already present for a particular item, +then the \fB-tags\fR for that item are unchanged. +.TP +\fIpathName \fBtag remove\fR \fItag\fR ?\fIitems\fR? +Removes the specified \fItag\fR from each of the listed \fIitems\fR. +If \fIitems\fR is omitted, removes \fItag\fR from each item in the tree. +If \fItag\fR is not present for a particular item, +then the \fB-tags\fR for that item are unchanged. +.RE +.TP +\fIpathName \fBxview \fIargs\fR +Standard command for horizontal scrolling; see \fIwidget(n)\fR. +.TP +\fIpathName \fByview \fIargs\fR +Standard command for vertical scrolling; see \fIttk::widget(n)\fR. +.SH "ITEM OPTIONS" +.PP +The following item options may be specified for items +in the \fBinsert\fR and \fBitem\fR widget commands. +.OP \-text text Text +The textual label to display for the item. +.OP \-image image Image +A Tk image, displayed to the left of the label. +.OP \-values values Values +The list of values associated with the item. +.RS +.PP +Each item should have the same number of values as +the \fB\-columns\fR widget option. +If there are fewer values than columns, +the remaining values are assumed empty. +If there are more values than columns, +the extra values are ignored. +.RE +.OP \-open open Open +A boolean value indicating whether the item's children +should be displayed (\fB\-open true\fR) or hidden (\fB\-open false\fR). +.OP \-tags tags Tags +A list of tags associated with this item. +.SH "TAG OPTIONS" +.PP +The following options may be specified on tags: +.IP \fB\-foreground\fR +Specifies the text foreground color. +.IP \fB\-background\fR +Specifies the cell or item background color. +.IP \fB\-font\fR +Specifies the font to use when drawing text. +.\" ??? Maybe: .IP \-anchor +.\" ??? Maybe: .IP \-padding +.\" ??? Maybe: .IP \-text +.IP \fB\-image\fR +Specifies the item image, in case the item's \fB\-image\fR option is empty. +.\" .PP +.\" \fI(@@@ TODO: sort out order of precedence for options)\fR +.SH "COLUMN IDENTIFIERS" +.PP +Column identifiers take any of the following forms: +.IP \(bu +A symbolic name from the list of \fB\-columns\fR. +.IP \(bu +An integer \fIn\fR, specifying the \fIn\fRth data column. +.IP \(bu +A string of the form \fB#\fIn\fR, where \fIn\fR is an integer, +specifying the \fIn\fRth display column. +.PP +\fBNOTE:\fR +Item \fB\-values\fR may be displayed in a different order than +the order in which they are stored. +.PP +\fBNOTE:\fR Column #0 always refers to the tree column, +even if \fB\-show tree\fR is not specified. +.PP +A \fIdata column number\fR is an index into an item's \fB\-values\fR list; +a \fIdisplay column number\fR is the column number in the tree +where the values are displayed. +Tree labels are displayed in column #0. +If \fB\-displaycolumns\fR is not set, +then data column \fIn\fR is displayed in display column \fB#\fIn+1\fR. +Again, \fBcolumn #0 always refers to the tree column\fR. +.SH "VIRTUAL EVENTS" +.PP +The treeview widget generates the following virtual events. +.IP <<TreeviewSelect>> +Generated whenever the selection changes. +.IP <<TreeviewOpen>> +Generated just before setting the focus item to \fB\-open true\fR. +.IP <<TreeviewClose>> +Generated just after setting the focus item to \fB\-open false\fR. +.PP +The \fBfocus\fR and \fBselection\fR widget commands can be used +to determine the affected item or items. +'\" Not yet: +'\" In Tk 8.5, the affected item is also passed as the \fB\-detail\fR field +'\" of the virtual event. +.SH "SEE ALSO" +ttk::widget(n), listbox(n), image(n), bind(n) +'\" Local Variables: +'\" mode: nroff +'\" End: |