#
# Feedback
# ----------------------------------------------------------------------
# Implements a Feedback widget, to display feedback on the status of an 
# process to the user. Display is given as a percentage and as a 
# thermometer type bar. Options exist for adding a label and controlling its
# position.
#
# ----------------------------------------------------------------------
#  AUTHOR: Kris Raney                    EMAIL: kraney@spd.dsccc.com
#
#  @(#) $Id: feedback.itk,v 1.3 2006/09/11 20:35:54 irby Exp $
# ----------------------------------------------------------------------
#            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.
# ======================================================================

# Acknowledgements:
#
# Special thanks go to Sam Shen(SLShen@lbl.gov), as this code is based on his 
# feedback.tcl code from tk inspect. The original code is copyright 1995
# Lawrence Berkeley Laboratory.
#
# This software is copyright (C) 1994 by the Lawrence Berkeley Laboratory.
#  
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that: (1) source code distributions
# retain the above copyright notice and this paragraph in its entirety, (2)
# distributions including binary code include the above copyright notice and
# this paragraph in its entirety in the documentation or other materials
# provided with the distribution, and (3) all advertising materials mentioning
# features or use of this software display the following acknowledgement:
# ``This product includes software developed by the University of California,
# Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
# the University nor the names of its contributors may be used to endorse
# or promote products derived from this software without specific prior
# written permission.
#  
# THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
# WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 
#
# Default resources.
#
option add *Feedback.borderWidth 0 widgetDefault
option add *Feedback.elementBorderWidth 2 widgetDefault
option add *Feedback.relief flat widgetDefault
option add *Feedback.labelPos n widgetDefault
option add *Feedback.barWidth 200 widgetDefault
option add *Feedback.barHeight 20 widgetDefault
option add *Feedback.barColor blue widgetDefault
 
#
# Usual options.
#
itk::usual Feedback {
    keep -background -borderwidth -cursor \
         -elementborderwidth -foreground -highlightcolor -highlightthickness \
         -labelfont
}
 
# ------------------------------------------------------------------
#                          FEEDBACK
# ------------------------------------------------------------------
class ::iwidgets::Feedback {
    inherit iwidgets::Labeledwidget

    constructor {args} {}

    itk_option define -steps steps Steps 10

    public method reset {}
    public method step {{inc 1}}

    private variable _stepval 0
}

#
# Provide a lowercased access method for the Dialogshell class.
# 
proc ::iwidgets::feedback {pathName args} {
    uplevel ::iwidgets::Feedback $pathName $args
}

body ::iwidgets::Feedback::constructor {args} {
  itk_option add hull.borderwidth hull.relief

  itk_component add spacer {
    frame $itk_interior.spacer
  } {
    keep -background
    rename -width -barwidth barWidth Width
  }
  pack $itk_component(spacer) -side top -padx 10

  itk_component add bar {
    frame $itk_interior.bar -relief raised \
        -borderwidth 2 -highlightthickness 0
  } {
    rename -background -barcolor barColor BarColor
    rename -borderwidth -elementborderwidth elementBorderWidth BorderWidth
    rename -height -barheight barHeight Height
  }
  pack $itk_component(bar) -side top -padx 10 -pady 2 -anchor w

  itk_component add percentage {
    label $itk_interior.percentage -text "0%"
  }
  pack $itk_component(percentage) -side top -fill x -padx 2 -pady 2

  #
  # Explicitly handle configs that may have been ignored earlier.
  #
  eval itk_initialize $args
}

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

# ------------------------------------------------------------------
# OPTION: -steps
#
# Set the total number of steps.
# ------------------------------------------------------------------
configbody ::iwidgets::Feedback::steps {
  step 0
}

# ------------------------------------------------------------------
#                            METHODS
# ------------------------------------------------------------------
 
# ------------------------------------------------------------------
# METHOD: reset
#
# Resets the status bar to 0
# ------------------------------------------------------------------
body ::iwidgets::Feedback::reset {} {
  set _stepval 0
  step 0
}

# ------------------------------------------------------------------
# METHOD: step ?inc?
#
# Increase the value of the status bar by inc. Default of 1
# ------------------------------------------------------------------
body ::iwidgets::Feedback::step {{inc 1}} {
  incr _stepval $inc
  set fraction [expr 1.0*$_stepval/$itk_option(-steps)]

  if {$fraction > 1.0} {
    set fraction 1
  } elseif {$fraction < 0.0} {
    set fraction 0
  }
  $itk_component(percentage) configure \
      -text [format %.0f%% [expr 100.0*$fraction]]

  $itk_component(bar) configure \
      -width [expr int($itk_option(-barwidth)*$fraction)]

  if {[winfo ismapped $itk_component(hull)]} {
      update
  }
}