Manual Pages for UNIX Darwin command on man iwidgets

Manual Pages for UNIX Darwin command on man iwidgets_hierarchy

iwidgets::hierarchy(1) [incr Widgets] iwidgets::hierarchy(1)

NAME

iwidgets::hierarchy - Create and manipulate a hierarchy widget

SYNOPSIS

iiwwiiddggeettss::::hhiieerraarrcchhyy pathName ?options? IINNHHEERRIITTAANNCCEE

itk::Widget <- iwidgets::Labeledwidget <- iwidgets::Scrolledwidget <-

iwidgets::Hierarchy SSTTAANNDDAARRDD OOPPTTIIOONNSS aaccttiivveeBBaacckkggrroouunndd aaccttiivveeFFoorreeggrroouunndd bbaacckkggrroouunndd bboorrddeerrWWiiddtthh ccuurrssoorr ddiissaabblleeddFFoorreeggrroouunndd ffoorreeggrroouunndd hhiigghhlliigghhttCCoolloorr hhiigghhlliigghhttTThhiicckknneessss rreelliieeff sseelleeccttBBaacckkggrroouunndd sseelleeccttFFoorreeggrroouunndd See the "options" manual entry for details on the standard options. AASSSSOOCCIIAATTEEDD OOPPTTIIOONNSS aaccttiivveeRReelliieeff eelleemmeennttBBoorrddeerrWWiiddtthh jjuummppttrroouugghhCCoolloorr

See the "scrollbar" widget manual entry for details on the above asso-

ciated options. ssppaacciinngg11 ssppaacciinngg22 ssppaacciinngg33 ttaabbss See the "text" widget manual entry for details on the above associated options. IINNHHEERRIITTEEDD OOPPTTIIOONNSS llaabbeellBBiittmmaapp llaabbeellFFoonntt llaabbeellIImmaaggee llaabbeellMMaarrggiinn llaabbeellPPooss llaabbeellTTeexxtt llaabbeellVVaarriiaabbllee ssttiicckkyy See the "labeledwidget" class manual entry for details on the inherited options.

WWIIDDGGEETT-SSPPEECCIIFFIICC OOPPTTIIOONNSS

Name: aallwwaayyssQQuueerryy Class: AAllwwaayyssQQuueerryy

Command-Line Switch: -aallwwaayyssqquueerryy

Boolean flag which tells the hierarchy widget weather or not each refresh of the display should be via a new query using the

command value of the -querycommand option or use the values pre-

vious found the last time the query was made. The default is no. Name: cclloosseeddIIccoonn Class: IIccoonn

Command-Line Switch: -cclloosseeddiiccoonn

Specifies the name of an existing closed icon image to be used in the hierarchy before those nodes that are collapsed. Should one not be provided, then a folder icon will be generated, pixmap if possible, bitmap otherwise. Name: ddbbllCClliicckkCCoommmmaanndd Class: CCoommmmaanndd

Command-Line Switch: -ddbbllcclliicckkccoommmmaanndd

Specifies a command to be executed upon user double clicking via mouse button one of the text label of an entry. If this command

contains "%n", it is replaced with the name of the selected

node. Should it contain "%s" then a boolean indicator of the

node's current selection status is substituted. Name: eexxppaannddeedd Class: EExxppaannddeedd

Command-Line Switch: -eexxppaannddeedd

When true, the hierarchy will be completely expanded when it is first displayed. A fresh display can be triggered by resetting

the -querycommand option. The default is false.

Name: ffiilltteerr Class: FFiilltteerr

Command-Line Switch: -ffiilltteerr

When true only the branch nodes and selected items are dis-

played. This gives a compact view of important items. The default is false. Name: hheeiigghhtt Class: HHeeiigghhtt

Command-Line Switch: -hheeiigghhtt

Specifies the height of the hierarchy as an entire unit. The

value may be specified in any of the forms acceptable to TTkkGGeett-

PPiixxeellss. Any additional space needed to display the other compo-

nents such as labels, margins, and scrollbars force the hierar-

chy to be compressed. A value of zero along with the same value for the width causes the value given for the visibleitems option

to be applied which administers geometry constraints in a dif-

ferent manner. The default height is zero. Name: iiccoonnCCoommmmaanndd Class: CCoommmmaanndd

Command-Line Switch: -iiccoonnccoommmmaanndd

Specifies a command to be executed upon user selection via mouse button one of any additional icons given in the values returned

by the command associated with the -querycommand option. If

this command contains "%n", it is replaced with the name of the

node the icon belongs to. Should it contain "%i" then the icon

name is substituted. Name: iiccoonnDDbbllCCoommmmaanndd Class: CCoommmmaanndd

Command-Line Switch: -iiccoonnddbbllccoommmmaanndd

Specifies a command to be executed upon user double clicking via

mouse button one of the icon of an entry. If this command con-

tains "%n", it is replaced with the name of the node the icon

belongs to. Should it contain "%i" then the icon name is substi-

tuted. Name: iimmaaggeeCCoommmmaanndd Class: CCoommmmaanndd

Command-Line Switch: -iimmaaggeeccoommmmaanndd

Specifies a command to be executed upon user selecting an image

of an entry. If this command contains "%n", it is replaced with

the name of the selected node. Should it contain "%s" then a

boolean indicator of the node's current selection status is sub-

stituted. Name: iimmaaggeeDDbbllCCoommmmaanndd Class: CCoommmmaanndd

Command-Line Switch: -iimmaaggeeddbbllccoommmmaanndd

Specifies a command to be executed upon user double clicking via

mouse button one of the image of an entry. If this command con-

tains "%n", it is replaced with the name of the node the icon

belongs to. Should it contain "%i" then the icon name is substi-

tuted. Name: iimmaaggeeMMeennuuLLooaaddCCoommmmaanndd Class: CCoommmmaanndd

Command-Line Switch: -iimmaaggeemmeennuullooaaddccoommmmaanndd

Specifies a command to be executed upon user selection via mouse button three, on the image or icon, that will dynamically load the itemMenu for the widget. Name: mmaarrkkBBaacckkggrroouunndd Class: FFoorreeggrroouunndd

Command-Line Switch: -mmaarrkkbbaacckkggrroouunndd

Specifies the background color to use when displaying marked nodes. Name: mmaarrkkFFoorreeggrroouunndd Class: BBaacckkggrroouunndd

Command-Line Switch: -mmaarrkkffoorreeggrroouunndd

Specifies the foreground color to use when displaying marked nodes. Name: mmeennuuCCuurrssoorr Class: CCuurrssoorr

Command-Line Switch: -mmeennuuccuurrssoorr

Specifies the mouse cursor to be used for the item and back-

ground menus. The value may have any of the forms accept able to TkGetCursor. Name: nnooddeeIIccoonn Class: IIccoonn

Command-Line Switch: -nnooddeeiiccoonn

Specifies the name of an existing node icon image to be used in the hierarchy before those nodes that are leafs. Should one not

be provided, then a dog-eared page icon will be generated,

pixmap if possible, bitmap otherwise. Name: ooppeennIIccoonn Class: IIccoonn

Command-Line Switch: -ooppeenniiccoonn

Specifies the name of an existing open icon image to be used in the hierarchy before those nodes that are expanded. Should one not be provided, then an open folder icon will be generated, pixmap if possible, bitmap otherwise. Name: qquueerryyCCoommmmaanndd Class: CCoommmmaanndd

Command-Line Switch: -qquueerryyccoommmmaanndd

Specifies the command executed to query the contents of each

node. If this command contains "%n", it is replaced with the

name of the desired node. In its simpilest form it should return the children of the given node as a list which will be depicted in the display. Since the names of the children are used as tags in the underlying text widget, each child must be unique in the hierarchy. Due to the unique requirement, the nodes shall be reffered to as uids or uid in the singular sense. The format of returned list is {uid [uid ...]} where uid is a unique id and primary key for the hierarchy entry Should the unique requirement pose a problem, the list returned

can take on another more extended form which enables the associ-

ation of text to be displayed with the uids. The uid must still be unique, but the text does not have to obey the unique rule.

In addition, the format also allows the specification of addi-

tional tags to be used on the same entry in the hierarchy as the uid and additional icons to be displayed just before the node. The tags and icons are considered to be the property of the user in that the hierarchy widget will not depend on any of their values. The extended format is {{uid [text [tags [icons]]]} {uid [text [tags [icons]]]} ...} where uid is a unique id and primary key for the hierarchy entry text is the text to be displayed for this uid tags is a list of user tags to be applied to the entry icons is a list of icons to be displayed in front of the text

The hierarchy widget does a look ahead from each node to deter-

mine if the node has a children. This can be cost some perfor-

mace with large hierarchies. User's can avoid this by providing a hint in the user tags. A tag of "leaf" or "branch" tells the

hierarchy widget the information it needs to know thereby avoid-

ing the look ahead operation. Name: hhssccrroollllMMooddee Class: SSccrroollllMMooddee

Command-Line Switch: -hhssccrroollllmmooddee

Specifies the the display mode to be used for the horizontal scrollbar: ssttaattiicc,, ddyynnaammiicc,, or nnoonnee. In static mode, the scroll bar is displayed at all times. Dynamic mode displays the scroll bar as required, and none disables the scroll bar display. The default is static. Name: ssbbWWiiddtthh Class: WWiiddtthh

Command-Line Switch: -ssbbwwiiddtthh

Specifies the width of the scrollbar in any of the forms accept-

able to TTkkGGeettPPiixxeellss. Name: ssccrroollllMMaarrggiinn Class: MMaarrggiinn

Command-Line Switch: -ssccrroollllmmaarrggiinn

Specifies the distance between the text portion of the hierarchy

and the scrollbars in any of the forms acceptable to TTkkGGeettPPiixx-

eellss. The default is 3 pixels. Name: sseelleeccttCCoommmmaanndd Class: CCoommmmaanndd

Command-Line Switch: -sseelleeccttccoommmmaanndd

Specifies a Tcl command to be evaluated when you select a node

in the hierarchy via left mouse click. If "%n" is included in

the command, it is substituted with the node name. Similarly,

"%s" is substituted with the node's current selection status: 1

for selected, 0 otherwise.

Name: tteexxttBBaacckkggrroouunndd Class: BBaacckkggrroouunndd Command-Line

Switch: -tteexxttbbaacckkggrroouunndd

Specifies the background color for the text portion of the hier-

archy in any of the forms acceptable to TTkkGGeettCCoolloorr. Name: tteexxttFFoonntt Class: FFoonntt

Command-Line Switch: -tteexxttffoonntt

Specifies the font to be used in the text portion of the hierar-

chy. Name: tteexxttMMeennuuLLooaaddCCoommmmaanndd Class: CCoommmmaanndd

Command-Line Switch: -tteexxttmmeennuullooaaddccoommmmaanndd

Specifies a command to be executed upon user selection via mouse button three, that will dynamically load the itemMenu for the widget. Name: vviissiibblleeiitteemmss Class: VViissiibblleeIItteemmss

Command-Line Switch: -vviissiibblleeiitteemmss

Specifies the widthxheight in characters and lines for the hier-

archy. This option is only administered if the width and height options are both set to zero, otherwise they take precedence. The default value is 80x24. With the visibleitems option engaged, geometry constraints are maintained only on the text portion of the hierarchy. The size of the other components such

as labels, margins, and scroll bars, are additive and indepen-

dent, effecting the overall size of the hierarchy. In contrast, should the width and height options have non zero values, they

are applied to the hierarchy as a whole. The hierarchy is com-

pressed or expanded to maintain the geometry constraints. Name: vvssccrroollllMMooddee Class: SSccrroollllMMooddee

Command-Line Switch: -vvssccrroollllmmooddee

Specifies the the display mode to be used for the vertical scrollbar: ssttaattiicc,, ddyynnaammiicc,, or nnoonnee. In static mode, the scroll bar is displayed at all times. Dynamic mode displays the scroll bar as required, and none disables the scroll bar display. The default is static. Name: wwiiddtthh Class: WWiiddtthh

Command-Line Switch: -wwiiddtthh

Specifies the width of the hierarchy as an entire unit. The

value may be specified in any of the forms acceptable to TTkkGGeett-

PPiixxeellss. Any additional space needed to display the other compo-

nents such as labels, margins, and scrollbars force the text portion of the hierarchy to be compressed. A value of zero along with the same value for the height causes the value given for the visibleitems option to be applied which administers geometry constraints in a different manner. The default width is zero.

DESCRIPTION

The iiwwiiddggeettss::::hhiieerraarrcchhyy command creates a hierarchical data view wid-

get. It allows the graphical management of a a list of nodes that can

be expanded or collapsed. Individual nodes can be highlighted. Click-

ing with the right mouse button on any item brings up a special item menu. Clicking on the background area brings up a different popup menu. Options exist to provide user control over the loading of the nodes and actions associated with node selection. Since the hierarchy is based on the scrolledtext widget, it includes options to control the method in which the scrollbars are displayed, i.e. statically or dynamically. Options also exist for adding a label to the hierarchy and controlling its position. MMEETTHHOODDSS The iiwwiiddggeettss::::hhiieerraarrcchhyy command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget. It has the following general form: pathName option ?arg arg ...? Option and the args determine the exact behavior of the command. The following commands are possible for hierarchy widgets: AASSSSOOCCIIAATTEEDD MMEETTHHOODDSS bbbbooxx ccoommppaarree ddeebbuugg ddeelleettee ddlliinneeiinnffoo dduummpp ggeett iinnddeexx iinnsseerrtt ssccaann sseeaarrcchh sseeee ttaagg wwiinnddooww xxvviieeww yyvviieeww See the "text" manual entry for details on the standard methods.

WWIIDDGGEETT-SSPPEECCIIFFIICC MMEETTHHOODDSS

pathName ccggeett option Returns the current value of the configuration option given by

option. Option may have any of the values accepted by the iiwwiidd-

ggeettss::::hhiieerraarrcchhyy command. pathName cclleeaarr Removes all items from the hierarchy display including all tags

and icons. The display will remain empty until the -filter or

-querycommand options are set.

pathName ccoollllaappssee uid Collapses the hierarchy beneath the node with the specified unique id by one level. Since this can take a moment for large hierarchies, the cursor will be changed to a watch during the

collapse. Also, if any of the nodes beneath the node being col-

lapsed are selected, their status is changed to unselected. pathName ccoonnffiigguurree ?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 avail-

able options for pathName (see TTkkCCoonnffiigguurreeIInnffoo 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 iiwwiiddggeettss::::hhiieerraarrcchhyy command. pathName ccuurrrreenntt Returns the tags for the node that was most recently selected by the right mouse button when the item menu was posted. Usually used by the code in the item menu to figure out what item is being manipulated. pathName ddrraaww ?when? Performs a complete redraw of the entire hierarchy. When may be

either -now or -eventually where the latter means the draw can

be performed after idle. pathName eexxppaanndd uid Expands the hierarchy beneath the node with the specified unique

id by one level. Since this can take a moment for large hierar-

chies, the cursor will be changed to a watch during the expan-

sion. pathName eexxppaannddeedd uid Returns the current state of expansion for the node with the specified unique id. pathName eexxppSSttaattee Returns a list of all expanded nodes in the tree. pathName mmaarrkk option ?arg arg ...? This command is used to manipulate marks which is quite similar to selection, adding a secondary means of hilighting an item in the hierarchy. The exact behavior of the command depends on the option argument that follows the mmaarrkk argument. The following forms of the command are currently supported: pathName mmaarrkk cclleeaarr Clears all the currently marked nodes in the hierarchy. pathName mmaarrkk aadddd uid ?uid uid ...? Marks the nodes with the specified uids in the hierarchy

using the -mmaarrkkbbaacckkggrroouunndd and -mmaarrkkffoorreeggrroouunndd options and

without affecting the mark state of any other nodes that were already marked. pathName mmaarrkk rreemmoovvee uid ?uid uid ...?

Unmarks the nodes with the specified uids in the hierar-

chy without affecting the mark state of any other nodes that were already marked. pathName mmaarrkk ggeett Returns a list of the unique ids that are currently marked. pathName rreeffrreesshh uid Performs a redraw of a specific node that has the given uid. If the node is not currently visible or in other words already drawn on the text, then no action is taken. pathName pprruunnee uid Removes the node specified by the given uid from the hierarchy. Should the node have children, then all of its children will be removed as well. pathName sseelleeccttiioonn option ?arg arg ...? This command is used to manipulate the selection of nodes in the hierarchy. The exact behavior of the command depends on the

option argument that follows the sseelleeccttiioonn argument. The fol-

lowing forms of the command are currently supported: pathName sseelleeccttiioonn cclleeaarr Clears all the currently selected nodes in the hierarchy. pathName sseelleeccttiioonn aadddd uid ?uid uid ...?

Selects the nodes with the specified uids in the hierar-

chy using the -sseelleeccttiioonnbbaacckkggrroouunndd and -sseelleeccttiioonnffoorree-

ggrroouunndd options and without affecting the selection state of any other nodes that were already selected. pathName sseelleeccttiioonn rreemmoovvee uid ?uid uid ...?

Deselects the nodes with the specified uids in the hier-

archy without affecting the selection state of any other nodes that were already selected. pathName sseelleeccttiioonn ggeett Returns a list of the unique ids that are currently selected. A nodes selection status is also dependent on it being visible. If a node is selected and its parent is then collapsed making the selected node not visible, then its selection status is changed to unselected. pathName ttooggggllee uid Toggles the hierarchy beneath the node with the specified unique

id. If the hierarchy is currently expanded, then it is col-

lapsed, and vice-versa.

CCOOMMPPOONNEENNTTSS Name: lliisstt Class: TTeexxtt The list component is the text widget in which the hierarchy is displayed. See the "text" widget manual entry for details on the text component item. Name: bbggMMeennuu Class: MMeennuu The bgMenu component is the popup menu which is displayed upon pressing the right mouse button in the background, i.e. not over

a specific node. Menu items can be added along with their com-

mands via the component command. See the "menu" widget manual entry for details on the bgMenu component item. Name: hhoorriizzssbb Class: SSccrroollllbbaarr The horizsb component is the horizontal scroll bar. See the

"scrollbar" widget manual entry for details on the horizsb com-

ponent item. Name: iitteemmMMeennuu Class: MMeennuu The itemMenu component is the popup menu which is displayed upon selection of a hierarchy node with the right mouse button. Menu items can be added along with their commands via the component command. See the "menu" widget manual entry for details on the itemMenu component item. Name: vveerrttssbb Class: SSccrroollllbbaarr The vertsb component is the vertical scroll bar. See the

"scrollbar" widget manual entry for details on the vertsb compo-

nent item. EEXXAAMMPPLLEE package require Iwidgets 4.0 proc getfiles {file} { global env

if {$file == ""} {

set dir $env(HOME)

} else {

set dir $file

}

if {[catch {cd $dir}] != 0} {

return "" } set rlist ""

foreach file [lsort [glob -nocomplain *]] {

lappend rlist [list [file join $dir $file] $file]

}

return $rlist

}

iwidgets::hierarchy .h -querycommand "getfiles %n" -visibleitems 30x15 -labeltext $env(HOME)

pack .h -side left -expand yes -fill both

AUTHOR Mark L. Ulferts Michael J. McLennan KKEEYYWWOORRDDSS hierarchy, text, widget Tk iwidgets::hierarchy(1)