#
# Scrolledframe
# ----------------------------------------------------------------------
# Implements horizontal and vertical scrollbars around a childsite
# frame.  Includes options to control display of scrollbars.
#
# ----------------------------------------------------------------------
#  AUTHOR: Sue Yockey                           syockey@spd.dsccc.com 
#          Mark Ulferts                         mulferts@spd.dsccc.com 
#
#  @(#) $Id: scrolledframe.itk,v 1.3 2006/09/11 20:35:55 irby Exp $
# ----------------------------------------------------------------------
#            Copyright (c) 1995 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.
# ======================================================================

#
# Default resources.
#
option add *Scrolledframe.borderWidth 2 widgetDefault
option add *Scrolledframe.relief sunken widgetDefault
option add *Scrolledframe.scrollMargin 3 widgetDefault
option add *Scrolledframe.vscrollMode static widgetDefault
option add *Scrolledframe.hscrollMode static widgetDefault
option add *Scrolledframe.width 100 widgetDefault
option add *Scrolledframe.height 100 widgetDefault
option add *Scrolledframe.labelPos n widgetDefault

#
# Usual options.
#
itk::usual Scrolledframe {
    keep -activebackground -activerelief -background -borderwidth -cursor \
	 -elementborderwidth -foreground -highlightcolor -highlightthickness \
	 -jump -labelfont -troughcolor
}

# ------------------------------------------------------------------
#                            SCROLLEDFRAME
# ------------------------------------------------------------------
class iwidgets::Scrolledframe {
    inherit iwidgets::Labeledwidget

    constructor {args} {}
    destructor {}

    itk_option define -sbwidth sbWidth Width 15
    itk_option define -scrollmargin scrollMargin ScrollMargin 3
    itk_option define -vscrollmode vscrollMode VScrollMode static
    itk_option define -hscrollmode hscrollMode HScrollMode static
    itk_option define -width width Width 30
    itk_option define -height height Height 30

    public method childsite {} 
    public method justify {direction} 
    public method xview {args} 
    public method yview {args} 

    protected method _configureCanvas {} 
    protected method _configureFrame {} 
    protected method _scrollFrame {wid first last} 
    protected method _updateFiller {}
    protected method _configureFiller {}

    private method _fillerWidth {} 
    private method _horizScrollbarDisplay {mode} 
    private method _vertScrollbarDisplay {mode} 

    protected variable _vmode off            ;# Vertical scroll mode
    protected variable _hmode off            ;# Vertical scroll mode
    protected variable _reconfigPlanned ""   ;# non-null, filler update pending

    private variable _initialized 0            ;# Initialization flag.
}

#
# Provide a lowercased access method for the Scrolledframe class.
# 
proc ::iwidgets::scrolledframe {pathName args} {
    uplevel ::iwidgets::Scrolledframe $pathName $args
}

# ------------------------------------------------------------------
#                        CONSTRUCTOR
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::constructor {args} {
    component hull configure -borderwidth 0
    pack propagate $itk_component(shell) no

    #
    # Create some frames to hold both the top and bottom halves of 
    # the widget.  The top will contain both the canvas and vertical 
    # scrollbar.  The bottom houses the horizontal scrollbar and 
    # some filler.
    #
    itk_component add topFrame {
	frame $itk_interior.topFrame
    } {
	keep -background -cursor 
    }
    pack $itk_component(topFrame) -fill both -expand yes
    
    #
    # Frame around horizontal scrollbar 
    #
    itk_component add bottomHalf {
	frame $itk_component(topFrame).bottomHalf
    } {
	keep -background -cursor
    }
    pack $itk_component(bottomHalf) -fill x -side bottom
    
    #
    # Frame for horizontal margin between scrolled area & scrollbar
    #
    itk_component add hMargin {
	frame $itk_component(topFrame).hMargin
    } {
	keep -background -cursor
    }
    pack $itk_component(hMargin) -side bottom

    #
    # Frame around canvas and vertical scrollbar
    #
    itk_component add topHalf {
	frame $itk_component(topFrame).topHalf
    } {
	keep -background -cursor
    }
    pack $itk_component(topHalf) -fill both -expand yes    
    
    # 
    # Create a frame for the canvas to provide relief for the canvas.
    #
    itk_component add canvasFrame {
	frame $itk_component(topHalf).canvasFrame \
		-relief sunken -borderwidth 2
    } {
	keep -background -borderwidth -cursor -relief 
    }
    
    # 
    # Create a canvas to scroll
    #
    itk_component add scrCanvas {
	canvas $itk_component(canvasFrame).scrCanvas \
		-height 1.0 -width 1.0 \
                -scrollregion "0 0 1 1" \
		-highlightthickness 0 \
                -borderwidth 0 -relief flat \
                -xscrollcommand \
		[code $this _scrollFrame $itk_component(bottomHalf).hSB] \
		-yscrollcommand \
		[code $this _scrollFrame $itk_component(topHalf).vSB]
    } {
	keep -background -cursor
    }
    pack $itk_component(scrCanvas) -fill both -expand yes
    bind $itk_component(scrCanvas) <Configure> [code $this _configureCanvas]
    
    #
    # Create a Frame inside canvas to hold widgets to be scrolled 
    #
    itk_component add scrFrame {
	frame $itk_component(scrCanvas).scrFrame 
    } {
	keep -background -cursor
    }
    pack $itk_component(scrFrame) -fill both -expand yes
    $itk_component(scrCanvas) create window 1 1 -tags frameTag \
            -window $itk_component(scrFrame) -anchor nw
    set itk_interior $itk_component(scrFrame)
    bind $itk_component(scrFrame) <Configure> [code $this _configureFrame]
    
    #
    # Create frame for the vertical margin between the scrolling
    # area and the scrollbar.
    #
    itk_component add vMargin {
	frame $itk_component(topHalf).vMargin -width 0
    } {
	keep -background -cursor
    }
    
    # 
    # Create the vertical scroll bar.
    #
    itk_component add vSB {
	scrollbar $itk_component(topHalf).vSB -orient vertical \
		-command [code $itk_component(scrCanvas) yview]
    } {
	keep -activebackground -activerelief -background -borderwidth \
		-cursor -elementborderwidth \
		-highlightcolor -jump -highlightthickness -relief \
		-repeatdelay -repeatinterval -troughcolor
	rename -highlightbackground -background background Background
    }
    pack $itk_component(vSB) -side right -fill y
    pack $itk_component(vMargin) -side right
    pack $itk_component(canvasFrame) -fill both -expand yes -side left
    
    #
    # Create the horizontal scrollbar.
    #
    itk_component add hSB {
	scrollbar $itk_component(bottomHalf).hSB -orient horizontal \
		-command [code $itk_component(scrCanvas) xview]
    } {
	keep -activebackground -activerelief -background -borderwidth \
		-cursor -elementborderwidth \
		-highlightcolor -jump -highlightthickness -relief \
		-repeatdelay -repeatinterval -troughcolor
	rename -highlightbackground -background background Background
    }
    pack $itk_component(hSB) -side left -fill x -expand yes
    
    #
    # Create the filler frame and compute its width.
    #
    itk_component add filler {
	frame $itk_component(bottomHalf).filler -width [_fillerWidth]
    } {
	keep -background -cursor
    }
    pack $itk_component(filler) -side right 
    
    #
    # Explicitly handle configs that may have been ignored earlier.
    #
    eval itk_initialize $args
    
    bind $itk_component(hMargin) <Configure> [code $this _configureFiller]
    bind $itk_component(vSB) <Configure> [code $this _configureFiller]
    bind $itk_component(vMargin) <Configure> [code $this _configureFiller]
    bind $itk_component(hSB) <Configure> [code $this _configureFiller]

    set _initialized 1
    configure -scrollmargin $itk_option(-scrollmargin)
}

# ------------------------------------------------------------------
#                           DESTURCTOR
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::destructor {} {
    if {$_reconfigPlanned != ""} {after cancel $_reconfigPlanned}
}

# ------------------------------------------------------------------
#                             OPTIONS
# ------------------------------------------------------------------

# ------------------------------------------------------------------
# OPTION: -sbwidth
#
# Set the width of the scrollbars.
# ------------------------------------------------------------------
configbody iwidgets::Scrolledframe::sbwidth {
    if {$_initialized} {
	$itk_component(vSB) configure -width $itk_option(-sbwidth)
	$itk_component(hSB) configure -width $itk_option(-sbwidth)
    }
}

# ------------------------------------------------------------------
# OPTION: -scrollmargin
#
# Set the distance between the scrollbars and the canvas.
# ------------------------------------------------------------------
configbody iwidgets::Scrolledframe::scrollmargin {
    if {$_initialized} {
	set pixels [winfo pixels $itk_component(hMargin) \
		$itk_option(-scrollmargin)]
	
	if {$_hmode == "on"} {
	    $itk_component(hMargin) config -width 1 -height $pixels
	}
	
	if {$_vmode == "on"} {
	    $itk_component(vMargin) config -width $pixels -height 1
	}
	
	$itk_component(filler) config -width [_fillerWidth] -height 1
    }
}

# ------------------------------------------------------------------
# OPTION: -vscrollmode
#
# Enable/disable display and mode of veritcal scrollbars.
# ------------------------------------------------------------------
configbody iwidgets::Scrolledframe::vscrollmode {
    switch $itk_option(-vscrollmode) {
    	static {
    	    _vertScrollbarDisplay on
    	}
	
    	dynamic -
    	none {
    	    _vertScrollbarDisplay off
    	}
	
    	default {
    	    error "bad vscrollmode option\
		    \"$itk_option(-vscrollmode)\": should be\
		    static, dynamic, or none"
    	}
    }
}

# ------------------------------------------------------------------
# OPTION: -hscrollmode
#
# Enable/disable display and mode of horizontal scrollbars.
# ------------------------------------------------------------------
configbody iwidgets::Scrolledframe::hscrollmode {
    switch $itk_option(-hscrollmode) {
    	static {
    	    _horizScrollbarDisplay on
    	}
	
    	dynamic -
    	none {
    	    _horizScrollbarDisplay off
    	}
	
    	default {
    	    error "bad hscrollmode option\
		    \"$itk_option(-hscrollmode)\": should be\
		    static, dynamic, or none"
    	}
    }
}

# ------------------------------------------------------------------
# OPTION: -width
#
# Specifies the width of the scrolled frame.  The value may be 
# specified in any of the forms acceptable to Tk_GetPixels.  
# ------------------------------------------------------------------
configbody iwidgets::Scrolledframe::width {
    set pixels \
    	    [winfo pixels $itk_component(shell) $itk_option(-width)]
    
    $itk_component(shell) config -width $pixels
}

# ------------------------------------------------------------------
# OPTION: -height
#
# Specifies the height of the scrolled frame.  The value may be 
# specified in any of the forms acceptable to Tk_GetPixels.  
# ------------------------------------------------------------------
configbody iwidgets::Scrolledframe::height {
    set pixels \
    	    [winfo pixels $itk_component(shell) $itk_option(-height)]
    
    $itk_component(shell) config -height $pixels
}

# ------------------------------------------------------------------
#                            METHODS
# ------------------------------------------------------------------

# ------------------------------------------------------------------
# METHOD: childsite
#
# Returns the path name of the child site widget.
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::childsite {} {
    return $itk_component(scrFrame)
}

# ------------------------------------------------------------------
# METHOD: justify
#
# Justifies the scrolled region in one of four directions: top,
# bottom, left, or right.
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::justify {direction} {
    if {[winfo ismapped $itk_component(scrCanvas)]} {
	update idletasks
	
	switch $direction {
	    left {
		$itk_component(scrCanvas) xview moveto 0
	    }
	    right {
		$itk_component(scrCanvas) xview moveto 1
	    }
	    top {
		$itk_component(scrCanvas) yview moveto 0
	    }
	    bottom {
		$itk_component(scrCanvas) yview moveto 1
	    }
	    default {
		error "bad justify argument \"$direction\": should be\
			left, right, top, or bottom"
	    }
	}
    }
}

# ------------------------------------------------------------------
# METHOD: xview index
#
# Adjust the view in the frame so that character position index
# is displayed at the left edge of the widget.
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::xview {args} {
    return [eval $itk_component(scrCanvas) xview $args]
}

# ------------------------------------------------------------------
# METHOD: yview index
#
# Adjust the view in the frame so that character position index
# is displayed at the top edge of the widget.
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::yview {args} {
    return [eval $itk_component(scrCanvas) yview $args]
}

# ------------------------------------------------------------------
# PRIVATE METHOD: _configureCanvas 
#
# Responds to configure events on the canvas widget.  When canvas 
# changes size, adjust frame size.
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::_configureCanvas {} {
    set sr [$itk_component(scrCanvas) cget -scrollregion]
    set srw [lindex $sr 2]
    set srh [lindex $sr 3]
    
    $itk_component(scrFrame) configure -height $srh -width $srw
}

# ------------------------------------------------------------------
# PRIVATE METHOD: _configureFrame 
#
# Responds to configure events on the frame widget.  When the frame 
# changes size, adjust scrolling region size.
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::_configureFrame {} {
    $itk_component(scrCanvas) configure \
	    -scrollregion [$itk_component(scrCanvas) bbox frameTag] 
}

# ------------------------------------------------------------------
# PRIVATE METHOD: _fillerWidth 
#
# Compute the width of the filler frame based on the vertical 
# scrollbar width plus the margin.
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::_fillerWidth {} {
    if {$_vmode == "on"} {
	return [expr [winfo reqwidth $itk_component(vSB)] + \
		[winfo reqwidth $itk_component(vMargin)]]
    } else {
	return 1
    }
}

# ------------------------------------------------------------------
# PROTECTED METHOD: _configureFiller 
#
# Set up to do an update of the filler if one is not all ready 
# planned.
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::_configureFiller {} {
    if {$_reconfigPlanned == ""} {
	set _reconfigPlanned [after idle [code $this _updateFiller]]
    }
}

# ------------------------------------------------------------------
# PROTECTED METHOD: _updateFiller 
#
# Update the width of the filler following a configure event on 
# a scrollbar or margin.
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::_updateFiller {} {
    $itk_component(filler) config -width [_fillerWidth] -height 1
    set _reconfigPlanned ""
}

# ------------------------------------------------------------------
# PRIVATE METHOD: _horizScrollbarDisplay 
#
# Displays the horizontal scrollbar based on the input mode.
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::_horizScrollbarDisplay {mode} {
    switch $mode  {
	on {
	    set _hmode on
	    
	    $itk_component(hMargin) config -width 1 -height \
		    [winfo pixels $itk_component(hMargin) \
		    $itk_option(-scrollmargin)]
	    
	    pack $itk_component(hSB) -side left -fill x -expand yes
	}
	
	off {
	    set _hmode off
	    
	    pack forget $itk_component(hSB)
	    
	    $itk_component(hMargin) config -width 1 -height 1
	    $itk_component(filler) config -width 1 -height 1
	}
	
	default {
	    error "invalid argument \"$mode\": should be on or off"
	}
    }
}

# ------------------------------------------------------------------
# PRIVATE METHOD: _vertScrollbarDisplay 
#
# Displays the vertical scrollbar based on the input mode.
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::_vertScrollbarDisplay {mode} {
    switch $mode  {
	on {
	    set _vmode on
	    
	    $itk_component(vMargin) config -height 1 -width \
		    [winfo pixels $itk_component(vMargin) \
		    $itk_option(-scrollmargin)]

	    pack forget $itk_component(canvasFrame)
	    pack forget $itk_component(vMargin)
	    pack $itk_component(vSB) -side right -fill y
	    pack $itk_component(vMargin) -side right
	    pack $itk_component(canvasFrame) -fill both -expand yes -side left
	}
	
	off {
	    set _vmode off
	    
	    pack forget $itk_component(vSB)
	    
	    $itk_component(vMargin) config -width 1 -height 1
	    $itk_component(filler) config -width 1 -height 1
	}
	
	default {
	    error "invalid argument \"$mode\": should be on or off"
	}
    }
}

# ------------------------------------------------------------------
# PRIVATE METHOD: _scrollFrame 
#
# Performs scrolling and display of scrollbars based on the total 
# and maximum frame size as well as the current -vscrollmode and 
# -hscrollmode settings.  Parameters are automatic scroll parameters.
# ------------------------------------------------------------------
body iwidgets::Scrolledframe::_scrollFrame {wid first last} {
    $wid set $first $last
    
    if {$wid == $itk_component(vSB)} {
	if {$itk_option(-vscrollmode) == "dynamic"} {
	    if {($first == 0) && ($last == 1)} {
		if {$_vmode != "off"} {
		    _vertScrollbarDisplay off
		}
		
	    } else {
		if {$_vmode != "on"} {
		    _vertScrollbarDisplay on
		}
	    }
	}
	
    } elseif {$wid == $itk_component(hSB)} {
	if {$itk_option(-hscrollmode) == "dynamic"} {
	    if {($first == 0) && ($last == 1)} {
		if {$_hmode != "off"} {
		    _horizScrollbarDisplay off
		}
		
	    } else {
		if {$_hmode != "on"} {
		    _horizScrollbarDisplay on
		}
	    }
	}
    }
}