Subversion Repositories or1k

# Hierarchy

# ----------------------------------------------------------------------

# Hierarchical data viewer.  Manages a list of nodes that can be

# expanded or collapsed.  Individual nodes can be highlighted.

# Clicking 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.

# ----------------------------------------------------------------------

#   AUTHOR:  Michael J. McLennan

#            Bell Labs Innovations for Lucent Technologies

#            mmclennan@lucent.com

#

#            Mark L. Ulferts

#            DSC Communications

#            mulferts@austin.dsccc.com

#

#      RCS:  $Id: hierarchy.itk,v 1.1.1.1 2002-01-16 10:24:50 markom Exp $

# ----------------------------------------------------------------------

#                Copyright (c) 1996  Lucent Technologies

# ======================================================================

# Permission to use, copy, modify, and distribute this software and its

# documentation for any purpose and without fee is hereby granted,

# provided that the above copyright notice appear in all copies and that

# both that the copyright notice and warranty disclaimer appear in

# supporting documentation, and that the names of Lucent Technologies

# any of their entities not be used in advertising or publicity

# pertaining to distribution of the software without specific, written

# prior permission.

#

# Lucent Technologies disclaims all warranties with regard to this

# software, including all implied warranties of merchantability and

# fitness.  In no event shall Lucent Technologies be liable for any

# special, indirect or consequential damages or any damages whatsoever

# resulting from loss of use, data or profits, whether in an action of

# contract, negligence or other tortuous action, arising out of or in

# connection with the use or performance of this software.

#

# ----------------------------------------------------------------------

#            Copyright (c) 1996 DSC Technologies Corporation

# ======================================================================

# Permission to use, copy, modify, distribute and license this software

# and its documentation for any purpose, and without fee or written

# agreement with DSC, is hereby granted, provided that the above copyright

# notice appears in all copies and that both the copyright notice and

# warranty disclaimer below appear in supporting documentation, and that

# the names of DSC Technologies Corporation or DSC Communications

# Corporation not be used in advertising or publicity pertaining to the

# software without specific, written prior permission.

#

# DSC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING

# ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, AND NON-

# INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE

# AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE,

# SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. IN NO EVENT SHALL

# DSC BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR

# ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,

# WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTUOUS ACTION,

# ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS

# SOFTWARE.

# ======================================================================

#

# Usual options.

#

itk::usual Hierarchy {

    keep -cursor -textfont -font

    keep -background -foreground -textbackground

    keep -selectbackground -selectforeground

}

# ------------------------------------------------------------------

#                            HIERARCHY

# ------------------------------------------------------------------

class iwidgets::Hierarchy {

    inherit iwidgets::Scrolledwidget

    constructor {args} {}

    destructor {}

    itk_option define -alwaysquery alwaysQuery AlwaysQuery 0

    itk_option define -closedicon closedIcon Icon {}

    itk_option define -expanded expanded Expanded 0

    itk_option define -filter filter Filter 0

    itk_option define -font font Font \

        -*-Courier-Medium-R-Normal--*-120-*-*-*-*-*-*

    itk_option define -height height Height 0

    itk_option define -iconcommand iconCommand Command {}

    itk_option define -markbackground markBackground Foreground #a0a0a0

    itk_option define -markforeground markForeground Background Black

    itk_option define -nodeicon nodeIcon Icon {}

    itk_option define -openicon openIcon Icon {}

    itk_option define -querycommand queryCommand Command {}

    itk_option define -selectcommand selectCommand Command {}

    itk_option define -selectbackground selectBackground Foreground #c3c3c3

    itk_option define -selectforeground selectForeground Background Black

    itk_option define -visibleitems visibleItems VisibleItems 80x24

    itk_option define -width width Width 0

    public method clear {}

    public method collapse {node}

    public method current {}

    public method draw {{when -now}}

    public method expand {node}

    public method mark {op args}

    public method prune {node}

    public method refresh {node}

    public method selection {op args}

    public method toggle {node}

    public method bbox {index}

    public method compare {index1 op index2}

    public method debug {args} {eval $args}

    public method delete {first {last {}}}

    public method dlineinfo {index}

    public method dump {args}

    public method get {index1 {index2 {}}}

    public method index {index}

    public method insert {args}

    public method scan {option args}

    public method search {args}

    public method see {index}

    public method tag {op args}

    public method window {option args}

    public method xview {args}

    public method yview {args}

    protected method _contents {uid}

    protected method _iconSelect {node icon}

    protected method _post {x y}

    protected method _drawLevel {node indent}

    protected method _select {x y}

    protected method _deselectSubNodes {uid}

    protected method _deleteNodeInfo {uid}

    protected method _getParent {uid}

    protected method _getHeritage {uid}

    protected method _isInternalTag {tag}

    private variable _filterCode ""  ;# Compact view flag.

    private variable _hcounter 0     ;# Counter for hierarchy icons

    private variable _icons          ;# Array of user icons by uid

    private variable _images         ;# Array of our icons by uid

    private variable _indents        ;# Array of indentation by uid

    private variable _marked         ;# Array of marked nodes by uid

    private variable _markers ""     ;# List of markers for level being drawn

    private variable _nodes          ;# List of subnodes by uid

    private variable _pending ""     ;# Pending draw flag

    private variable _posted ""      ;# List of tags at posted menu position

    private variable _selected       ;# Array of selected nodes by uid

    private variable _tags           ;# Array of user tags by uid

    private variable _text           ;# Array of displayed text by uid

    private variable _states         ;# Array of selection state by uid

    private variable _ucounter 0     ;# Counter for user icons

}

#

# Provide a lowercased access method for the Hierarchy class.

#

proc ::iwidgets::hierarchy {pathName args} {

    uplevel ::iwidgets::Hierarchy $pathName $args

}

#

# Use option database to override default resources of base classes.

#

option add *Hierarchy.menuCursor arrow widgetDefault

option add *Hierarchy.labelPos n widgetDefault

option add *Hierarchy.tabs 30 widgetDefault

# ------------------------------------------------------------------

#                        CONSTRUCTOR

# ------------------------------------------------------------------

body iwidgets::Hierarchy::constructor {args} {

    itk_option remove iwidgets::Labeledwidget::state

    #

    # Our -width and -height options are slightly different than

    # those implemented by our base class, so we're going to

    # remove them and redefine our own.

    #

    itk_option remove iwidgets::Scrolledwidget::width

    itk_option remove iwidgets::Scrolledwidget::height

    #

    # Create a clipping frame which will provide the border for

    # relief display.

    #

    itk_component add clipper {

        frame $itk_interior.clipper

    } {

        usual

        keep -borderwidth -relief -highlightthickness -highlightcolor

        rename -highlightbackground -background background Background

    }

    grid $itk_component(clipper) -row 0 -column 0 -sticky nsew

    grid rowconfigure $_interior 0 -weight 1

    grid columnconfigure $_interior 0 -weight 1

    #

    # Create a text widget for displaying our hierarchy.

    #

    itk_component add list {

        text $itk_component(clipper).list -wrap none -cursor center_ptr \

                -state disabled -width 1 -height 1 \

                -xscrollcommand \

                [code $this _scrollWidget $itk_interior.horizsb] \

                -yscrollcommand \

                [code $this _scrollWidget $itk_interior.vertsb] \

                -borderwidth 0 -highlightthickness 0

    } {

        usual

        keep -spacing1 -spacing2 -spacing3 -tabs

        rename -font -textfont textFont Font

        rename -background -textbackground textBackground Background

        ignore -highlightthickness -highlightcolor

        ignore -insertbackground -insertborderwidth

        ignore -insertontime -insertofftime -insertwidth

        ignore -selectborderwidth

        ignore -borderwidth

    }

    grid $itk_component(list) -row 0 -column 0 -sticky nsew

    grid rowconfigure $itk_component(clipper) 0 -weight 1

    grid columnconfigure $itk_component(clipper) 0 -weight 1

    #

    # Configure the command on the vertical scroll bar in the base class.

    #

    $itk_component(vertsb) configure \

        -command [code $itk_component(list) yview]

    #

    # Configure the command on the horizontal scroll bar in the base class.

    #

    $itk_component(horizsb) configure \

                -command [code $itk_component(list) xview]

    #

    # Configure our text component's tab settings for twenty levels.

    #

    set tabs ""

    for {set i 1} {$i < 20} {incr i} {

        lappend tabs [expr $i*12+4]

    }

    $itk_component(list) configure -tabs $tabs

    #

    # Add popup menus that can be configured by the user to add

    # new functionality.

    #

    itk_component add itemMenu {

        menu $itk_component(list).itemmenu -tearoff 0

    } {

        usual

        ignore -tearoff

        rename -cursor -menucursor menuCursor Cursor

    }

    itk_component add bgMenu {

        menu $itk_component(list).bgmenu -tearoff 0

    } {

        usual

        ignore -tearoff

        rename -cursor -menucursor menuCursor Cursor

    }

    #

    # Adjust the bind tags to remove the class bindings.  Also, add

    # bindings for mouse button 1 to do selection and button 3 to

    # display a popup.

    #

    bindtags $itk_component(list) [list $itk_component(list) . all]

    bind $itk_component(list)  \

            [code $this _select %x %y]

    bind $itk_component(list)  \

            [code $this _post %x %y]

    #

    # Initialize the widget based on the command line options.

    #

    eval itk_initialize $args

}

# ------------------------------------------------------------------

#                           DESTRUCTOR

# ------------------------------------------------------------------

body iwidgets::Hierarchy::destructor {} {

    if {$_pending != ""} {

        after cancel $_pending

    }

}

# ------------------------------------------------------------------

#                             OPTIONS

# ------------------------------------------------------------------

# ------------------------------------------------------------------

# OPTION: -font

#

# Font used for text in the list.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::font {

    $itk_component(list) tag configure info \

            -font $itk_option(-font) -spacing1 6

}

# ------------------------------------------------------------------

# OPTION: -selectbackground

#

# Background color scheme for selected nodes.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::selectbackground {

    $itk_component(list) tag configure hilite \

            -background $itk_option(-selectbackground)

}

# ------------------------------------------------------------------

# OPTION: -selectforeground

#

# Foreground color scheme for selected nodes.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::selectforeground {

    $itk_component(list) tag configure hilite \

            -foreground $itk_option(-selectforeground)

}

# ------------------------------------------------------------------

# OPTION: -markbackground

#

# Background color scheme for marked nodes.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::markbackground {

    $itk_component(list) tag configure lowlite \

            -background $itk_option(-markbackground)

}

# ------------------------------------------------------------------

# OPTION: -markforeground

#

# Foreground color scheme for marked nodes.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::markforeground {

    $itk_component(list) tag configure lowlite \

            -foreground $itk_option(-markforeground)

}

# ------------------------------------------------------------------

# OPTION: -querycommand

#

# 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.

#

#   {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

# association 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

# additional 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.

#

#   {{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 determine

# if the node has a children.  This can be cost some performace 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 avoiding the look

# ahead operation.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::querycommand {

    clear

    draw -eventually

}

# ------------------------------------------------------------------

# OPTION: -selectcommand

#

# Command executed to select an item in the list.  If this command

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

# If it contains a "%s", it is replaced with a boolean indicator of

# the node's current selection status, where a value of 1 denotes

# that the node is currently selected and 0 that it is not.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::selectcommand {

}

# ------------------------------------------------------------------

# OPTION: -iconcommand

#

# Command executed upon selection of user icons.  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.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::iconcommand {

}

# ------------------------------------------------------------------

# OPTION: -alwaysquery

#

# Boolean flag which tells the hierarchy widget weather or not

# each refresh of the display should be via a new query using

# the -querycommand option or use the values previous found the

# last time the query was made.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::alwaysquery {

}

# ------------------------------------------------------------------

# OPTION: -filter

#

# When true only the branch nodes and selected items are displayed.

# This gives a compact view of important items.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::filter {

    switch -- $itk_option(-filter) {

        1 - true - yes - on {

            set newCode {set display [info exists _selected($child)]}

        }

            set newCode {set display 1}

        }

        default {

            error "bad filter option \"$itk_option(-filter)\":\

                   should be boolean"

        }

    }

    if {$newCode != $_filterCode} {

        set _filterCode $newCode

        draw -eventually

    }

}

# ------------------------------------------------------------------

# OPTION: -expanded

#

# When true, the hierarchy will be completely expanded when it

# is first displayed.  A fresh display can be triggered by

# resetting the -querycommand option.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::expanded {

    switch -- $itk_option(-expanded) {

        1 - true - yes - on {

            ;# okay

        }

            ;# okay

        }

        default {

            error "bad expanded option \"$itk_option(-expanded)\":\

                   should be boolean"

        }

    }

}

# ------------------------------------------------------------------

# OPTION: -openicon

#

# Specifies the open icon image to be used in the hierarchy.  Should

# one not be provided, then one will be generated, pixmap if

# possible, bitmap otherwise.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::openicon {

    if {$itk_option(-openicon) == {}} {

        if {[lsearch [image names] openFolder] == -1} {

            if {[lsearch [image types] pixmap] != -1} {

                image create pixmap openFolder -data {

                    /* XPM */

                    static char * dir_opened [] = {

                        "16 16 4 1",

                        /* colors */

                        ". c grey85 m white g4 grey90",

                        "b c black  m black g4 black",

                        "y c yellow m white g4 grey80",

                        "g c grey70 m white g4 grey70",

                        /* pixels */

                        "................",

                        "................",

                        "................",

                        "..bbbb..........",

                        ".bggggb.........",

                        "bggggggbbbbbbb..",

                        "bggggggggggggb..",

                        "bgbbbbbbbbbbbbbb",

                        "bgbyyyyyyyyyyybb",

                        "bbyyyyyyyyyyyyb.",

                        "bbyyyyyyyyyyybb.",

                        "byyyyyyyyyyyyb..",

                        "bbbbbbbbbbbbbb..",

                        "................",

                        "................",

                        "................"};

                }

            } else {

                image create bitmap openFolder -data {

                    #define open_width 16

                    #define open_height 16

                    static char open_bits[] = {

                        0x00, 0x00, 0x00, 0x00, 0x3c, 0x00, 0x42, 0x00,

                        0x81, 0x3f, 0x01, 0x20, 0xf9, 0xff, 0x0d, 0xc0,

                        0x07, 0x40, 0x03, 0x60, 0x01, 0x20, 0x01, 0x30,

                        0xff, 0x1f, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};

                }

            }

            set itk_option(-openicon) openFolder

        }

    } else {

        if {[lsearch [image names] $itk_option(-openicon)] == -1} {

            error "bad openicon option \"$itk_option(-openicon)\":\

                   should be an existing image"

        }

    }

}

# ------------------------------------------------------------------

# OPTION: -closedicon

#

# Specifies the closed icon image to be used in the hierarchy.

# Should one not be provided, then one will be generated, pixmap if

# possible, bitmap otherwise.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::closedicon {

    if {$itk_option(-closedicon) == {}} {

        if {[lsearch [image names] closedFolder] == -1} {

            if {[lsearch [image types] pixmap] != -1} {

                image create pixmap closedFolder -data {

                    /* XPM */

                    static char *dir_closed[] = {

                        "16 16 3 1",

                        ". c grey85 m white g4 grey90",

                        "b c black  m black g4 black",

                        "y c yellow m white g4 grey80",

                        "................",

                        "................",

                        "................",

                        "..bbbb..........",

                        ".byyyyb.........",

                        "bbbbbbbbbbbbbb..",

                        "byyyyyyyyyyyyb..",

                        "byyyyyyyyyyyyb..",

                        "byyyyyyyyyyyyb..",

                        "byyyyyyyyyyyyb..",

                        "byyyyyyyyyyyyb..",

                        "byyyyyyyyyyyyb..",

                        "bbbbbbbbbbbbbb..",

                        "................",

                        "................",

                        "................"};

                }

            } else {

                image create bitmap closedFolder -data {

                    #define closed_width 16

                    #define closed_height 16

                    static char closed_bits[] = {

                        0x00, 0x00, 0x00, 0x00, 0x78, 0x00, 0x84, 0x00,

                        0xfe, 0x7f, 0x02, 0x40, 0x02, 0x40, 0x02, 0x40,

                        0x02, 0x40, 0x02, 0x40, 0x02, 0x40, 0x02, 0x40,

                        0xfe, 0x7f, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};

                }

            }

            set itk_option(-closedicon) closedFolder

        }

    } else {

        if {[lsearch [image names] $itk_option(-closedicon)] == -1} {

            error "bad closedicon option \"$itk_option(-closedicon)\":\

                   should be an existing image"

        }

    }

}

# ------------------------------------------------------------------

# OPTION: -nodeicon

#

# Specifies the node icon image to be used in the hierarchy.  Should

# one not be provided, then one will be generated, pixmap if

# possible, bitmap otherwise.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::nodeicon {

    if {$itk_option(-nodeicon) == {}} {

        if {[lsearch [image names] nodeFolder] == -1} {

            if {[lsearch [image types] pixmap] != -1} {

                image create pixmap nodeFolder -data {

                    /* XPM */

                    static char *dir_node[] = {

                        "16 16 3 1",

                        ". c grey85 m white g4 grey90",

                        "b c black  m black g4 black",

                        "y c yellow m white g4 grey80",

                        "................",

                        "................",

                        "................",

                        "...bbbbbbbbbbb..",

                        "..bybyyyyyyyyb..",

                        ".byybyyyyyyyyb..",

                        "byyybyyyyyyyyb..",

                        "bbbbbyyyyyyyyb..",

                        "byyyyyyyyyyyyb..",

                        "byyyyyyyyyyyyb..",

                        "byyyyyyyyyyyyb..",

                        "byyyyyyyyyyyyb..",

                        "bbbbbbbbbbbbbb..",

                        "................",

                        "................",

                        "................"};

                }

            } else {

                image create bitmap nodeFolder -data {

                    #define node_width 16

                    #define node_height 16

                    static char node_bits[] = {

                        0x00, 0x00, 0x00, 0x00, 0xe0, 0x7f, 0x50, 0x40,

                        0x48, 0x40, 0x44, 0x40, 0x42, 0x40, 0x7e, 0x40,

                        0x02, 0x40, 0x02, 0x40, 0x02, 0x40, 0x02, 0x40,

                        0xfe, 0x7f, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};

                }

            }

            set itk_option(-nodeicon) nodeFolder

        }

    } else {

        if {[lsearch [image names] $itk_option(-nodeicon)] == -1} {

            error "bad nodeicon option \"$itk_option(-nodeicon)\":\

                   should be an existing image"

        }

    }

}

# ------------------------------------------------------------------

# OPTION: -width

#

# Specifies the width of the hierarchy widget as an entire unit.

# The value may be specified in any of the forms acceptable to

# Tk_GetPixels.  Any additional space needed to display the other

# components such as labels, margins, and scrollbars force the text

# 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.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::width {

    if {$itk_option(-width) != 0} {

        set shell [lindex [grid info $itk_component(clipper)] 1]

        #

        # Due to a bug in the tk4.2 grid, we have to check the

        # propagation before setting it.  Setting it to the same

        # value it already is will cause it to toggle.

        #

        if {[grid propagate $shell]} {

            grid propagate $shell no

        }

        $itk_component(list) configure -width 1

        $shell configure \

                -width [winfo pixels $shell $itk_option(-width)]

    } else {

        configure -visibleitems $itk_option(-visibleitems)

    }

}

# ------------------------------------------------------------------

# OPTION: -height

#

# Specifies the height of the hierarchy widget as an entire unit.

# The value may be specified in any of the forms acceptable to

# Tk_GetPixels.  Any additional space needed to display the other

# components such as labels, margins, and scrollbars force the text

# 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 different

# manner.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::height {

    if {$itk_option(-height) != 0} {

        set shell [lindex [grid info $itk_component(clipper)] 1]

        #

        # Due to a bug in the tk4.2 grid, we have to check the

        # propagation before setting it.  Setting it to the same

        # value it already is will cause it to toggle.

        #

        if {[grid propagate $shell]} {

            grid propagate $shell no

        }

        $itk_component(list) configure -height 1

        $shell configure \

                -height [winfo pixels $shell $itk_option(-height)]

    } else {

        configure -visibleitems $itk_option(-visibleitems)

    }

}

# ------------------------------------------------------------------

# OPTION: -visibleitems

#

# Specified the widthxheight in characters and lines for the text.

# This option is only administered if the width and height options

# are both set to zero, otherwise they take precedence.  With the

# visibleitems option engaged, geometry constraints are maintained

# only on the text.  The size of the other components such as

# labels, margins, and scroll bars, are additive and independent,

# effecting the overall size of the scrolled text.  In contrast,

# should the width and height options have non zero values, they

# are applied to the scrolled text as a whole.  The text is

# compressed or expanded to maintain the geometry constraints.

# ------------------------------------------------------------------

configbody iwidgets::Hierarchy::visibleitems {

    if {[regexp {^[0-9]+x[0-9]+$} $itk_option(-visibleitems)]} {

        if {($itk_option(-width) == 0) && \

                ($itk_option(-height) == 0)} {

            set chars [lindex [split $itk_option(-visibleitems) x] 0]

            set lines [lindex [split $itk_option(-visibleitems) x] 1]

            set shell [lindex [grid info $itk_component(clipper)] 1]

            #

            # Due to a bug in the tk4.2 grid, we have to check the

            # propagation before setting it.  Setting it to the same

            # value it already is will cause it to toggle.

            #

            if {! [grid propagate $shell]} {

                grid propagate $shell yes

            }

            $itk_component(list) configure -width $chars -height $lines

        }

    } else {

        error "bad visibleitems option\

                \"$itk_option(-visibleitems)\": should be\

                widthxheight"

    }

}

# ------------------------------------------------------------------

#                         PUBLIC METHODS

# ------------------------------------------------------------------

# ----------------------------------------------------------------------

# PUBLIC METHOD: clear

#

# Removes all items from the display including all tags and icons.

# The display will remain empty until the -filter or -querycommand

# options are set.

# ----------------------------------------------------------------------

body iwidgets::Hierarchy::clear {} {

    $itk_component(list) configure -state normal -cursor watch

    $itk_component(list) delete 1.0 end

    $itk_component(list) configure -state disabled -cursor $itk_option(-cursor)

    catch {unset _nodes}

    catch {unset _text}

    catch {unset _tags}

    catch {unset _icons}

    catch {unset _states}

    catch {unset _images}

    catch {unset _indents}

    return

}

# ----------------------------------------------------------------------

# PUBLIC METHOD: selection option ?uid uid...?

#

# Handles all operations controlling selections in the hierarchy.

# Selections may be cleared, added, removed, or queried.  The add and

# remove options accept a series of unique ids.

# ----------------------------------------------------------------------

body iwidgets::Hierarchy::selection {op args} {

    switch -- $op {

        clear {

            $itk_component(list) tag remove hilite 1.0 end

            catch {unset _selected}

            return

        }

        add {

            foreach node $args {

                set _selected($node) 1

                catch {

                    $itk_component(list) tag add hilite \

                            "$node.first" "$node.last"

                }

            }

        }

        remove {

            foreach node $args {

                catch {

                    unset _selected($node)

                    $itk_component(list) tag remove hilite \

                            "$node.first" "$node.last"

                }

            }

        }

        get {

            return [array names _selected]

        }

        default {

            error "bad selection operation \"$op\":\

                   should be add, remove, clear or get"

        }

    }

}

# ----------------------------------------------------------------------

# PUBLIC METHOD: mark option ?arg arg...?

#

# Handles all operations controlling marks in the hierarchy.  Marks may

# be cleared, added, removed, or queried.  The add and remove options

# accept a series of unique ids.

# ----------------------------------------------------------------------

body iwidgets::Hierarchy::mark {op args} {

    switch -- $op {

        clear {

            $itk_component(list) tag remove lowlite 1.0 end

            catch {unset _marked}

            return

        }

        add {

            foreach node $args {

                set _marked($node) 1

                catch {

                    $itk_component(list) tag add lowlite \

                            "$node.first" "$node.last"

                }

            }

        }

        remove {

            foreach node $args {

                catch {

                    unset _marked($node)

                    $itk_component(list) tag remove lowlite \

                            "$node.first" "$node.last"

                }

            }

        }

        get {

            return [array names _marked]

        }

        default {

            error "bad mark operation \"$op\":\

                   should be add, remove, clear or get"

        }

    }

}

# ----------------------------------------------------------------------

# PUBLIC METHOD: current

#

# Returns 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.

# ----------------------------------------------------------------------

body iwidgets::Hierarchy::current {} {

    return $_posted

}

# ----------------------------------------------------------------------

# PUBLIC METHOD: expand node

#

# Expands the hierarchy beneath the specified node.  Since this can take

# a moment for large hierarchies, the cursor will be changed to a watch

# during the expansion.

# ----------------------------------------------------------------------

body iwidgets::Hierarchy::expand {node} {

    if {! [info exists _states($node)]} {

        error "bad expand node argument: \"$node\", the node doesn't exist"

    }

    if {!$_states($node) && \

            (([lsearch $_tags($node) branch] != -1) || \

             ([llength [_contents $node]] > 0))} {

        $itk_component(list) configure -state normal -cursor watch

        update

        #

        # Get the indentation level for the node.

        #

        set indent $_indents($node)

        set _markers ""

        $itk_component(list) mark set insert "$node:start"

        _drawLevel $node $indent

        #

        # Following the draw, all our markers need adjusting.

        #

        foreach {name index} $_markers {

            $itk_component(list) mark set $name $index

        }

        #

        # Set the image to be the open icon, denote the new state,

        # and set the cursor back to normal along with the state.

        #

        $_images($node) configure -image $itk_option(-openicon)

        set _states($node) 1

        $itk_component(list) configure -state disabled \

                -cursor $itk_option(-cursor)

    }

}

# ----------------------------------------------------------------------

# PUBLIC METHOD: collapse node

#

# Collapses the hierarchy beneath the specified node.  Since this can

# take a moment for large hierarchies, the cursor will be changed to a

# watch during the expansion.

# ----------------------------------------------------------------------