tixHList - Create and manipulate Tix Hierarchial List widgets

SYNOPSIS

tixHList pathName ?options?

SUPER-CLASS

None.

STANDARD OPTIONS


background	borderWidth	cursor	foreground
font	height	highlightColor highlightThickness	
relief	selectBackground	selectForeground
xScrollCommand	yScrollCommand	width

See the options(n) manual entry for details on the standard options.

WIDGET-SPECIFIC OPTIONS


Name:		browsecmd
Class:		BrowseCmd
Switch:		-browsecmd



Name:		columns
Class:		Columns
Switch:		-columns



Name:		command
Class:		Command
Switch:		-command



Name:		drawBranch
Class:		DrawBranch
Switch:		-drawbranch



Name:		foreground
Class:		Foreground
Switch:		-foreground
Alias:		-fg



Name:		gap
Class:		Gap
Switch:		-gap



Name:		header
Class:		Header
Switch:		-header



Name:		height
Class:		Height
Switch:		-height



Name:		indent
Class:		Indent
Switch:		-indent



Name:		indicator
Class:		Indicator
Switch:		-indicator



Name:		indicatorCmd
Class:		IndicatorCmd
Switch:		-indicatorcmd



Name:		itemType
Class:		ItemType
Switch:		-itemtype



Name:		padX
Class:		Pad
Switch:		-padx



Name:		padY
Class:		Pad
Switch:		-padx



Name:		selectBackground
Class:		SelectBackground
Switch:		-selectbackground



Name:		selectBorderWidth
Class:		BorderWidth
Switch:		-selectborderwidth



Name:		selectForeground
Class:		SelectForeground
Switch:		-selectforeground



Name:		selectMode
Class:		SelectMode
Switch:		-selectmode



Name:		sizeCmd
Class:		SizeCmd
Switch:		-sizecmd



Name:		separator
Class:		Separator
Switch:		-separator



Name:		width
Class:		Width
Switch:		-width

DESCRIPTION

The tixHList command creates a new window (given by the pathName argument) and makes it into a HList widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the HList widget such as its cursor and relief.

The HList widget can be used to display any data that have a hierarchical structure, for example, file system directory trees. The list entries are indented and connected by branch lines according to their places in the hierachy.

Each list entry is identified by an entryPath. The entryPath is a sequence of entry names separated by the separator charactor (specified by the -separator option). An entry name can be any string that does not contain the separator charactor, or it can be the a string that contains only one separator charactor.

For example, when "." is used as the separator charactor, "one.two.three" is the entryPath for a list entry whose parent is "one.two", whose parent is "one", which is a toplevel entry (has no parents).

Another examples: ".two.three" is the entryPath for a list entry whose parent is ".two", whose parent is ".", which is a toplevel entry.

DISPLAY ITEMS

Each list entry in an HList widget is associated with a display item. The display item determines what visual information should be displayed for this list entry. Please see the DItem(n) manual page for a list of all display items. When a list entry is created by the add or addchild widget commands, the type of its display item is determined by the -itemtype option passed to these commands. If the -itemtype is omitted, then by default the type specified by

WIDGET COMMAND

The tixHList command creates a new Tcl command whose name is the may be used to invoke various operations on the widget. It has the following general form: 

pathName option ?arg arg ...?
PathName is the name of the command, which is the same as determine the exact behavior of the command. The following commands are possible for HList widgets:
pathName add entryPath ?option value ...?
Creates a new list entry with the pathname entryPath. A list entry must be created after its parent is created (unless this entry is a top-level entry, which has no parent). This command returns the entryPath of the newly created list entry. The following configuration options can be given to configure the list entry:
The add widget command accepts additional configuration options to configure the display item associated with this list entry. The set of additional configuration options depends on the type of the display item given by the -itemtype option. Please see the DItem(n) manual page for a list of the configuration options for each of the display item types.
pathName addchild parentPath ?option value ... ?
Adds a new child entry to the children list of the list entry identified by parentPath. Or, if parentPath is set to be the empty string, then creates a new toplevel entry. The name of the new list entry will be a unique name automatically generated by the HList widget. Usually if parentPath is foo, then the entryPath of the new entry will be foo.1, foo.2, ... etc. This command returns the entryPath of the newly created list entry. option can be any option for the add widget command.
pathName anchor set entryPath
Sets the anchor to the list entry identified by entryPath. The anchor is the end of the selection that is fixed while the user is dragging out a selection with the mouse.
pathName anchor clear
Removes the anchor, if any, from this HList widget. This only removes the surrounding highlights of the anchor entry and does not affect its selection status.
pathName cget option
Returns the current value of the configuration option given by option. Option may have any of the values accepted by the tixHList command.
pathName column width col ?-char? ?width?
Querys or sets the width of a the column col in the HList widget. The value of col is zero-based: 0 stands for the first column, 1 stands for the second, and so on. If no further parameters are given, returns the current width of this column (in number of pixels). Additional parameters can be given to set the width of this column:

pathName configure ?option? ?value option value ...?
Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the tixHList command.
pathName delete option ?entryPath?
Delete one or more list entries. option may be one of the following:
pathName dragsite set entryPath
Sets the dragsite to the list entry identified by entryPath. The dragsite is used to indicate the source of a drag-and-drop action. Currently drag-and-drop functionality has not been implemented in Tix yet.
pathName dragsite clear
Remove the dragsite, if any, from the this HList widget. This only removes the surrounding highlights of the dragsite entry and does not affect its selection status.
pathName dropsite set entryPath
Sets the dropsite to the list entry identified by entryPath. The dropsite is used to indicate the target of a grag-and-drop action. Currently drag-and-drop functionality has not been implemented in Tix yet.
pathName dropsite clear
Remove the dropsite, if any, from the this HList widget. This only removes the surrounding highlights of the dropsite entry and does not affect its selection status.
pathName entrycget entryPath option
Returns the current value of the configuration option given by option for the entry indentfied by entryPath. Option may have any of the values accepted by the add widget command.
pathName entryconfigure entryPath ?option? ?value option value ...?
Query or modify the configuration options of the list entry indentfied by entryPath. If no option is specified, returns a list describing all of the available options for entryPath (see Tk_ConfigureInfo for information on the format of this list.) If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the add or addchild widget command. The exact set of options depends on the value of the -itemtype option passed to the the add or addchild widget command when this list entry is created.
pathName header option col ?args ...?
Manipulates the header items of this HList widget. If the -header option of this HList widget is set to true, then a header item is displayed at the top of each column. The col argument for this command must be a valid integer. 0 indicates the first column, 1 the second column, ... and so on. This command supports the following options:
pathName hide option ?entryPath?
Makes some of entries invisible invisible without deleting them. Option can be one of the following:
pathName indicator option entryPath ?args ...?
Manipulates the indicator on the list entries. An indicator is usually a small display item (such as an image) that is displayed to the left to an entry to indicate the status of the entry. For example, it may be used to indicator whether a directory is opened or closed. option can be one of the following:
pathName info option arg ...
Query information about the HList widget. option can be one of the following:
pathName item option ?args ...?
Creates and configures the display items at individual columns the entries. The form of additional of arguments depends on the choice of option:
pathName nearest y
Given a y-coordinate within the HList window, this command returns the entryPath of the (visible) HList element nearest to that y-coordinate.
pathName see entryPath
Adjust the view in the HList so that the entry given by entryPath is visible. If the entry is already visible then the command has no effect; if the entry is near one edge of the window then the HList scrolls to bring the element into view at the edge; otherwise the HList widget scrolls to center the entry.
pathName selection option arg ...
This command is used to adjust the selection within a HList widget. It has several forms, depending on option:
pathName show option ?entryPath?
Show the entries that are hidden by the hide command, option can be one of the following:
pathName xview args
This command is used to query and change the horizontal position of the forms:
pathName yview ?args?
This command is used to query and change the vertical position of the

BINDINGS

EXAMPLE

This example demonstrates how to use an HList to store a file

\fC 


 tixHList .h -separator "/" -browsecmd browse -selectmode single \\
    -itemtype text
 .h add /         -text /
 .h add /home     -text /home
 .h add /home/ioi -text /home/ioi
 .h add /home/foo -text /home/foo
 .h add /usr      -text /usr
 .h add /usr/lib  -text /usr/lib
 pack .h

 proc browse {file} {
     puts "$file browsed"
 }

BUGS

The fact that the display item at column 0 is implicitly associated with the whole entry is probably a design bug. This was done for backward compatibility purposes. The result is that there is a large overlap between the item command and the add, addchild, entrycget and entryconfigure commands. Whenever multiple columns exist, the programmer should use ONLY the item command to create and configure the display items in each column; the add, addchild, entrycget and entryconfigure should be used ONLY to create and configure entries.

KEYWORDS

Tix(n), Hierarchical Listbox
Last modified Sun Jan 19 22:34:30 EST 1997 --- Serial 853731301