1iwidgets::hierarchy  −  Create  and manipulate a hierarchy widget

iwidgets::hierarchy pathName ?options? itk::Widget <‐ iwid‐

3gets::Labeledwidget  <‐ iwidgets::Scrolledwidget <‐ iwidgets::Hi‐
4erarchy

activeBackground activeForeground background borderWidth

cursor disabledForeground foreground highlightColor

highlightThickness relief selectBackground selectForeground

8See the "options" manual entry for details on  the  standard  op‐
9tions.

activeRelief elementBorderWidth jumptroughColor

11See  the "scrollbar" widget manual entry for details on the above
12associated options.

spacing1 spacing2 spacing3 tabs

14See the "text" widget manual entry for details on the above asso‐
15ciated options.

labelBitmap labelFont labelImage labelMargin

labelPos labelText labelVariable sticky

18See the "labeledwidget" class manual entry for details on the in‐
19herited options.
20Name:           alwaysQuery
21Class:          AlwaysQuery
22Command‐Line Switch:           ‐alwaysquery
23Boolean flag which tells the hierarchy widget weather or not each
24refresh  of  the display should be via a new query using the com‐
25mand value of the ‐querycommand option or use the values previous
26found the last time the query was made.  The default is no.
27Name:           closedIcon
28Class:          Icon
29Command‐Line Switch:           ‐closedicon
30Specifies the name of an existing closed icon image to be used in
31the hierarchy before those nodes that are collapsed.  Should  one
32not  be provided, then a folder icon will be generated, pixmap if
33possible, bitmap otherwise.
34Name:           dblClickCommand
35Class:          Command
36Command‐Line Switch:           ‐dblclickcommand
37Specifies a command to be executed upon user double clicking  via
38mouse  button  one of the text label of an entry. If this command
39contains "%n", it is replaced with the name of the selected node.
40Should  it  contain  "%s"  then a boolean indicator of the node’s
41current selection status is substituted.
42Name:           expanded
43Class:          Expanded
44Command‐Line Switch:           ‐expanded
45When true, the hierarchy will be completely expanded when  it  is
46first  displayed.   A fresh display can be triggered by resetting
47the ‐querycommand option.  The default is false.
48Name:           filter
49Class:          Filter
50Command‐Line Switch:           ‐filter
51When true only the branch nodes and selected items are displayed.
52This  gives  a  compact  view of important items.  The default is
53false.
54Name:           height
55Class:          Height
56Command‐Line Switch:           ‐height
57Specifies the height of the hierarchy as  an  entire  unit.   The
58value  may be specified in any of the forms acceptable to Tk_Get‐

Pixels. Any additional space needed to display the other compo‐

60nents such as labels, margins, and scrollbars force the hierarchy
61to be compressed.  A value of zero along with the same value  for
62the  width  causes the value given for the visibleitems option to
63be applied which administers geometry constraints in a  different
64manner.  The default height is zero.
65Name:           iconCommand
66Class:          Command
67Command‐Line Switch:           ‐iconcommand
68Specifies  a command to be executed upon user selection via mouse
69button one of any additional icons given in the  values  returned
70by the command associated with the ‐querycommand option.  If this
71command contains "%n", it is replaced with the name of  the  node
72the  icon  belongs to.  Should it contain "%i" then the icon name
73is  substituted.
74Name:           iconDblCommand
75Class:          Command
76Command‐Line Switch:           ‐icondblcommand
77Specifies a command to be executed upon user double clicking  via
78mouse  button  one  of the icon of an entry. If this command con‐
79tains "%n", it is replaced with the name of the node the icon be‐
80longs to. Should it contain "%i" then the icon name is substitut‐
81ed.
82Name:           imageCommand
83Class:          Command
84Command‐Line Switch:           ‐imagecommand
85Specifies a command to be executed upon user selecting  an  image
86of  an entry.  If this command contains "%n", it is replaced with
87the name of the selected node. Should  it  contain  "%s"  then  a
88boolean  indicator of the node’s current selection status is sub‐
89stituted.
90Name:           imageDblCommand
91Class:          Command
92Command‐Line Switch:           ‐imagedblcommand
93Specifies a command to be executed upon user double clicking  via
94mouse  button  one of the image of an entry. If this command con‐
95tains "%n", it is replaced with the name of the node the icon be‐
96longs to. Should it contain "%i" then the icon name is substitut‐
97ed.
98Name:           imageMenuLoadCommand
99Class:          Command
100Command‐Line Switch:           ‐imagemenuloadcommand
101Specifies a command to be executed upon user selection via  mouse
102button  three,  on  the image or icon, that will dynamically load
103the itemMenu for the widget.
104Name:           markBackground
105Class:          Foreground
106Command‐Line Switch:           ‐markbackground
107Specifies the background color  to  use  when  displaying  marked
108nodes.
109Name:           markForeground
110Class:          Background
111Command‐Line Switch:           ‐markforeground
112Specifies  the  foreground  color  to  use when displaying marked
113nodes.
114Name:           menuCursor
115Class:          Cursor
116Command‐Line Switch:           ‐menucursor
117Specifies the mouse cursor to be used for the item and background
118menus.   The  value  may  have  any  of  the forms accept able to
119Tk_GetCursor.
120Name:           nodeIcon
121Class:          Icon
122Command‐Line Switch:           ‐nodeicon
123Specifies the name of an existing node icon image to be  used  in
124the  hierarchy before those nodes that are leafs.  Should one not
125be provided, then a dog‐eared page icon will be generated, pixmap
126if possible, bitmap otherwise.
127Name:           openIcon
128Class:          Icon
129Command‐Line Switch:           ‐openicon
130Specifies  the  name of an existing open icon image to be used in
131the hierarchy before those nodes that are expanded.   Should  one
132not  be  provided,  then  an  open folder icon will be generated,
133pixmap if possible, bitmap otherwise.
134Name:           queryCommand
135Class:          Command
136Command‐Line Switch:           ‐querycommand
137Specifies the command executed to  query  the  contents  of  each
138node.   If  this  command  contains "%n", it is replaced with the
139name of the desired node.  In its simpilest form it should return
140the  children  of the given node as a list which will be depicted
141in the display.  Since the names of the children are used as tags
142in  the  underlying text widget, each child must be unique in the
143hierarchy.  Due to the unique requirement,  the  nodes  shall  be
144reffered  to as uids or uid in the singular sense.  The format of
145returned list is
146  {uid [uid ...]}
147  where uid is a unique id and primary key for the hierarchy  en‐
148try  Should  the  unique requirement pose a problem, the list re‐
149turned can take on another more extended form which  enables  the
150association  of text to be displayed with the uids.  The uid must
151still be unique, but the text does not have to  obey  the  unique
152rule.   In  addition, the format also allows the specification of
153additional tags to be used on the same entry in the hierarchy  as
154the  uid  and  additional  icons  to be displayed just before the
155node.  The tags and icons are considered to be  the  property  of
156the  user  in that the hierarchy widget will not depend on any of
157their values.  The extended format is
158  {{uid [text [tags [icons]]]} {uid [text [tags [icons]]]} ...}
159  where uid is a unique id and primary key for the hierarchy  en‐
160try
161        text is the text to be displayed for this uid
162        tags is a list of user tags to be applied to the entry
163        icons  is a list of icons to be displayed in front of the
164text The hierarchy widget does a look ahead from each node to de‐
165termine  if  the node has a children.  This can be cost some per‐
166formace with large hierarchies.  User’s can avoid this by provid‐
167ing  a  hint in the user tags.  A tag of "leaf" or "branch" tells
168the hierarchy widget the information it  needs  to  know  thereby
169avoiding the look ahead operation.
170Name:           hscrollMode
171Class:          ScrollMode
172Command‐Line Switch:           ‐hscrollmode
173Specifies  the  the  display  mode  to be used for the horizontal
174scrollbar: static, dynamic, or none.  In static mode, the  scroll
175bar  is displayed at all times.  Dynamic mode displays the scroll
176bar as required, and none disables the scroll bar  display.   The
177default is static.
178Name:           sbWidth
179Class:          Width
180Command‐Line Switch:           ‐sbwidth
181Specifies  the width of the scrollbar in any of the forms accept‐
182able to Tk_GetPixels.
183Name:           scrollMargin
184Class:          Margin
185Command‐Line Switch:           ‐scrollmargin
186Specifies the distance between the text portion of the  hierarchy
187and  the  scrollbars in any of the forms acceptable to Tk_GetPix‐

els. The default is 3 pixels.

189Name:           selectCommand
190Class:          Command
191Command‐Line Switch:           ‐selectcommand
192Specifies a Tcl command to be evaluated when you select a node in
193the  hierarchy  via left mouse click.  If "%n" is included in the
194command, it is substituted with the node name.   Similarly,  "%s"
195is  substituted  with  the node’s current selection status: 1 for
196selected,    0     otherwise.      Name:           textBackground
197Class:          Background                           Command‐Line
198Switch:           ‐textbackground
199Specifies the background color for the text portion of the  hier‐
200archy in any of the forms acceptable to Tk_GetColor.
201Name:           textFont
202Class:          Font
203Command‐Line Switch:           ‐textfont
204Specifies  the font to be used in the text portion of the hierar‐
205chy.
206Name:           textMenuLoadCommand
207Class:          Command
208Command‐Line Switch:           ‐textmenuloadcommand
209Specifies a command to be executed upon user selection via  mouse
210button  three,  that  will  dynamically load the itemMenu for the
211widget.
212Name:           visibleitems
213Class:          VisibleItems
214Command‐Line Switch:           ‐visibleitems
215Specifies the widthxheight in characters and lines for the  hier‐
216archy.   This option is only administered if the width and height
217options are both set to zero,  otherwise  they  take  precedence.
218The  default  value  is  80x24.  With the visibleitems option en‐
219gaged, geometry constraints are maintained only on the text  por‐
220tion  of the hierarchy.  The size of the other components such as
221labels, margins, and scroll bars, are additive  and  independent,
222effecting the overall size of the hierarchy.  In contrast, should
223the width and height options have non zero values, they  are  ap‐
224plied  to  the hierarchy as a whole.  The hierarchy is compressed
225or expanded to maintain the geometry constraints.
226Name:           vscrollMode
227Class:          ScrollMode
228Command‐Line Switch:           ‐vscrollmode
229Specifies the the display  mode  to  be  used  for  the  vertical
230scrollbar:  static, dynamic, or none.  In static mode, the scroll
231bar is displayed at all times.  Dynamic mode displays the  scroll
232bar  as  required, and none disables the scroll bar display.  The
233default is static.
234Name:           width
235Class:          Width
236Command‐Line Switch:           ‐width
237Specifies the width of the hierarchy as an entire unit.  The val‐
238ue  may be specified in any of the forms acceptable to Tk_GetPix‐

els. Any additional space needed to display the other components

240such as labels, margins, and scrollbars force the text portion of
241the hierarchy to be compressed.  A value of zero along  with  the
242same  value  for  the height causes the value given for the visi‐
243bleitems option to be applied  which  administers  geometry  con‐
244straints in a different manner.  The default width is zero.
245
246
247
248The  iwidgets::hierarchy command creates a hierarchical data view
249widget.  It allows the graphical management of a a list of  nodes
250that can be expanded or collapsed.  Individual nodes can be high‐
251lighted.  Clicking with the right mouse button on any item brings
252up  a  special item menu.  Clicking on the background area brings
253up a different popup menu.  Options exist to provide user control
254over  the  loading  of the nodes and actions associated with node
255selection.  Since the hierarchy is based on the scrolledtext wid‐
256get,  it  includes  options  to  control  the method in which the
257scrollbars are displayed, i.e. statically or   dynamically.   Op‐
258tions also exist for adding a label to the hierarchy and control‐
259ling its position.
260
261The iwidgets::hierarchy command creates a new Tcl  command  whose
262name is pathName.  This command may be used to invoke various op‐
263erations on the widget.  It has the following general form: path‐

Name option ?arg arg ...? Option and the args determine the ex‐

265act behavior of the command.  The following commands are possible
266for hierarchy widgets:

bbox compare debug delete

dlineinfo dump get index

insert scan search see

tag window xview yview

271See the "text" manual entry for details on the standard methods.
272

pathName cget option Returns the current value of the configura‐

274tion option given by option.  Option may have any of  the  values
275accepted  by the iwidgets::hierarchy command.  pathName clear Re‐
276moves all items from the hierarchy display including all tags and
277icons.   The  display  will  remain  empty  until  the ‐filter or
278‐querycommand options are set.  pathName collapse  uid  Collapses
279the  hierarchy  beneath  the node with the specified unique id by
280one level.  Since this can take a moment for  large  hierarchies,
281the cursor will be changed to a watch during the collapse.  Also,
282if any of the nodes beneath the node being collapsed are  select‐
283ed,  their  status  is changed to unselected.  pathName configure
284?option? ?value option value ...?  Query or modify the configura‐
285tion options of the widget.  If no option is specified, returns a
286list 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

289list describing the one named option (this list will be identical
290to the corresponding sublist of the value returned if  no  option
291is  specified).  If one or more option−value pairs are specified,
292then the command modifies the given widget option(s) to have  the
293given  value(s);   in  this  case  the  command  returns an empty
294string.  Option may have any of the values accepted by the  iwid‐

gets::hierarchy command. pathName current Returns the tags for

296the node that was most recently selected by the right mouse  but‐
297ton  when  the item menu was posted.  Usually used by the code in
298the item menu to figure  out  what  item  is  being  manipulated.

pathName draw ?when? Performs a complete redraw of the entire

300hierarchy.  When may be either ‐now or ‐eventually where the lat‐
301ter  means the draw can be performed after idle.  pathName expand

uid Expands the hierarchy beneath the node with the specified

303unique  id  by one level.  Since this can take a moment for large
304hierarchies, the cursor will be changed to a watch during the ex‐
305pansion.   pathName expanded uid Returns the current state of ex‐
306pansion for the node with the specified unique id.  pathName exp‐

State Returns a list of all expanded nodes in the tree. pathName

mark option ?arg arg ...? This command is used to manipulate

309marks  which  is  quite  similar to selection, adding a secondary
310means of hilighting an item in the hierarchy.  The exact behavior
311of  the  command  depends on the option argument that follows the

mark argument. The following forms of the command are currently

313supported:  pathName  mark  clear Clears all the currently marked
314nodes in the hierarchy.  pathName mark  add  uid  ?uid  uid  ...?
315Marks  the  nodes  with the specified uids in the hierarchy using
316the ‐markbackground and ‐markforeground options and  without  af‐
317fecting  the  mark  state  of  any  other nodes that were already
318marked.  pathName mark remove uid  ?uid  uid  ...?   Unmarks  the
319nodes  with the specified uids in the hierarchy without affecting
320the mark state of any  other  nodes  that  were  already  marked.

pathName mark get Returns a list of the unique ids that are cur‐

322rently marked.  pathName refresh uid Performs a redraw of a  spe‐
323cific  node that has the given uid.  If the node is not currently
324visible or in other words already drawn on the text, then no  ac‐
325tion  is taken.  pathName prune uid Removes the node specified by
326the given uid from the hierarchy.  Should the node have children,
327then  all  of its children will be removed as well.  pathName se‐

lection option ?arg arg ...? This command is used to manipulate

329the  selection  of nodes in the hierarchy.  The exact behavior of
330the command depends on the option argument that follows  the  se‐

lection argument. The following forms of the command are cur‐

332rently supported: pathName selection clear Clears  all  the  cur‐
333rently  selected  nodes in the hierarchy.  pathName selection add

uid ?uid uid ...? Selects the nodes with the specified uids in

335the  hierarchy using the ‐selectionbackground and ‐selectionfore‐

ground options and without affecting the selection state of any

337other  nodes  that were already selected.  pathName selection re‐

move uid ?uid uid ...? Deselects the nodes with the specified

339uids  in  the  hierarchy without affecting the selection state of
340any other nodes that were already selected.   pathName  selection

get Returns a list of the unique ids that are currently selected.

342A nodes selection status is also dependent on it  being  visible.
343If a node is selected and its parent is then collapsed making the
344selected node not visible, then its selection status  is  changed
345to unselected.  pathName toggle uid Toggles the hierarchy beneath
346the node with the specified unique id.  If the hierarchy is  cur‐
347rently expanded, then it is collapsed, and vice‐versa.
348
349Name:           list
350Class:          Text
351The  list  component is the text widget in which the hierarchy is
352displayed.  See the "text" widget manual entry for details on the
353text component item.
354Name:           bgMenu
355Class:          Menu
356The  bgMenu  component  is the popup menu which is displayed upon
357pressing the right mouse button in the background, i.e. not  over
358a  specific  node.  Menu items can be added along with their com‐
359mands via the component command.  See the  "menu"  widget  manual
360entry for details on the bgMenu component item.
361Name:           horizsb
362Class:          Scrollbar
363The  horizsb  component  is  the  horizontal scroll bar.  See the
364"scrollbar" widget manual entry for details on the horizsb compo‐
365nent item.
366Name:           itemMenu
367Class:          Menu
368The  itemMenu component is the popup menu which is displayed upon
369selection of a hierarchy node with the right mouse button.   Menu
370items  can  be  added along with their commands via the component
371command.  See the "menu" widget manual entry for details  on  the
372itemMenu component item.
373Name:           vertsb
374Class:          Scrollbar
375The  vertsb  component  is  the  vertical  scroll  bar.   See the
376"scrollbar" widget manual entry for details on the vertsb  compo‐
377nent item.
378
379package require Iwidgets 4.0 proc get_files {file} {
380    global env
381
382    if {$file == ""} {
383        set dir $env(HOME)
384    } else {
385        set dir $file
386    }
387
388    if {[catch {cd $dir}] != 0} {
389        return ""
390    }
391
392    set rlist ""
393
394    foreach file [lsort [glob ‐nocomplain *]] {
395        lappend rlist [list [file join $dir $file] $file]
396    }
397
398    return $rlist }
399
400iwidgets::hierarchy .h ‐querycommand "get_files %n" ‐visibleitems
40130x15     ‐labeltext $env(HOME) pack .h ‐side  left  ‐expand  yes
402‐fill  both  Mark L. Ulferts Michael J. McLennan hierarchy, text,
403widget
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
Impressum