rbcurse 1.5.0 → 1.5.2

data/lib/rbcurse/deprecated/README.markdown

@@ -0,0 +1,12 @@
+== Short Story
+
+If you are new here, don't touch anything in this directory.
+
+== Long Story
+
+This directory contains stuff that was once used, but has since been rewritten in a simpler form.
+Thus, I've replaced this with the simpler form. This still exists for anyone who was using it.
+
+Some old stuff was either rather ambitiously rewritten or written awfully like MessageBox. I've got a more sensible version up now. Stuff here will *NOT* be maintained by me anylonger.
+
+There's also stuff here that will *NOT* work any longer such as SplitPanes and ScrollPanes. Support for them has been removed from the core (Form, widget and window) since it was complicating the core too much.

data/lib/rbcurse/deprecated/rpad.rb

@@ -0,0 +1,375 @@
+require 'ver/window'
+
+# This contains pad and subwin.
+#
+# 1. IMHO, subwins and derwins are not very stable. Avoid using them. I've tinkered
+#    with them quite a bit and given them up. 
+# 2. Pads are quite okay, I tried something too complex, and copywin often can give
+#    errors, or seg faults. So i've steered away from the Pad class. I may try a simpler
+#    less clever pad approach to textview sometime again.
+
+module VER
+##
+# Pad
+# This is EXPERIMENTAL
+# A pad cannot be used interchangeable since some application functions such as wrefresh
+# are illegal. Cannot expect the application to take care.
+# Internally we can make it easier. Mostly a pad is used to map to one portion of the screen.
+# So we allow that to be defined once. Then only start row and col of pad change.
+# Maybe we should check pad coordinates so no errors
+# Also check screen coordinates (if we know)
+# We need padheight and padwidth only to ensure we don't keep recreating.
+# Howevre, when comp's height increases, then decreases, pad height remains larger
+# but we keep printing an extra row in copywin. so Pad needs to maintain comp height
+# and padheight.
+# @since 0.1.3
+# NOTE used only by TabbedPane. If we rewrite without using it in 1.3.1 then scrap.
+# 2011-11-8 Now the new simpler TabbedPane does not use pads. 
+# The aim o this class was to act as a replacement for window, making it seamless
+# to use a pad instead
+class Pad  < VER::Window
+  # top and left correspond to screen's top and left wich will mostly be fixed
+  attr_accessor :top, :left
+  # start row and col correspond to pad's top and left which will change if scrolling
+  attr_accessor :pminrow, :pmincol
+  # screen's height and width, now it reflects components height and width
+  attr_accessor :sheight, :swidth
+  attr_reader :otherwin
+  # dimensions the pad was created with, used so we don't keep recreating pad, only if increase.
+  attr_reader :padheight, :padwidth
+  #attr_accessor :name  # more for debugging log files. 2010-02-02 19:58 
+  def initialize(height, width)
+    @visible = true
+    # do we set height and width ?? XXX
+    @window = Ncurses.newpad(height, width)
+    @padheight = height
+    @padwidth = width
+    @height = height
+    @width = width
+    @sheight = height
+    @swidth = width
+    init_vars
+  end
+  def init_vars
+    super
+    @top ||= 0; @left ||= 0
+    @pmincol ||= 0 # pad will print from this col
+    @pminrow ||= 0 # pad will print from this row
+    @window_type = :PAD
+    @name ||="#{self}"
+    $log.debug "        PAD constructor #{self} , #{@window} "
+  end
+  #
+  # @param layout is a hash (@see Window.initialize)
+  def self.create_with_layout(layout)
+    @window = Pad.new(layout[:height], layout[:width])
+    @window.reset_layout(layout)
+    return @window
+  end
+  ##
+  # increases the pad size, since the widget may have been resized
+  # checks that one of ht or width has been increased
+  # destroys earlier pad and returns new one
+  # Updates sheight and swidth even if reduced so copywin works fine.
+  # @param [Fixnum] height to resize to
+  # @param [Fixnum] width to resize to
+  # @return [Pad]
+  #  2009-10-29 23:18 
+  def resize(ht = 0, w = 0)
+    # update sheight and swidth even if reduced, so that pad doesn't overwrite.
+    @sheight = ht if ht > 0
+    @swidth = w if w > 0
+    return if ht < @padheight and w < @padwidth
+    @padheight = ht if ht > @padheight
+    @padwidth = w if w > @padwidth
+    destroy
+    $log.debug " L502 resize, creating newpad with #{@padheight} and #{@padwidth} "
+    @window = Ncurses.newpad(@padheight, @padwidth)
+    $log.debug " L502 resize created #{@window} "
+    return @window
+  end
+  ## used if pad and window are same size only
+  # creates a similar sized window
+  # assumes window is backed by this pad
+  # @param object of Window class
+  def self.create_for_window(win)
+    # get coordinates for win
+    @otherwin = win
+    smaxx = win.getmaxx()
+    smaxy = win.getmaxy()
+    top = win.getminx()
+    left = win.getminy()
+    sheight = win.height
+    swidth = win.width
+    # make pad based on size of window
+    window = Pad.create_with_layout(layout = { :height => sheight, :width => swidth, :top => top, :left => sleft })
+    window.sheight = sheight
+    window.swidth = swidth
+    return window
+
+  end
+  # top and left correspond to screen's top and left wich will mostly be fixed.
+  # In cases where the component may float around, as in Splitpanes second component
+  # this would be set using component's row and col.
+  def set_screen_row_col top, left=-1
+    @top = top
+    @left = left unless left < 0
+  end
+  alias :set_screen_pad_left :set_screen_row_col
+
+  ## added user setting screens max row and col (e.g splitpanes first component)
+  def set_screen_max_row_col mr, mc
+    $log.debug "#{@name} set_screen_max_row_col #{mr},#{mc}. earlier #{@screen_maxrow}, #{@screen_maxcol}  "
+    # added || check on 2010-01-09 18:39 since crashing if mr > sh + top ..
+    # I removed the check, since it results in a blank area on screen since the 
+    # widget has not expanded itself. Without the check it will  crash on copywin so you
+    # should increase widget size or disallow  calling this in this situation.
+    if mr > (@sheight + @top -1 -@pminrow)
+      $log.warn " ->>> ** set_screen_max_row_col #{mr} > #{@sheight} + #{@top} -1 - #{@pminrow} ** "
+      $log.warn " ->>> can result in error in copy_win or in some rows not displaying"
+      return # some situations actually require this ...
+    end unless mr.nil?
+    @screen_maxrow = mr unless mr.nil? # || mr > (@sheight + @top -1 -@pminrow)
+    @screen_maxcol = mc unless mc.nil?
+  end
+  # start row and col correspond to pad's top and left which will change if scrolling
+  # However, if we use this as a backing store for subwindows it could remain the same
+  def set_pad_top_left top, left=-1
+    $log.debug "#{@name} inside set_pad_top_left to #{top} #{left} earlier #{@pminrow}, #{@pmincol}"
+    @pminrow = top unless top < 0
+    @pmincol = left unless left < 0
+  end
+  # return screen max row which will be used for writing to window
+  # XXX what if user sets/overrides sheight
+  def smaxrow
+    #$log.debug "    ... niside smaxrow #{@sheight} + #{@top} -1 "
+    #@sheight + @top -1 
+    $log.debug "smr: #{@screen_maxrow}   ... niside smaxrow #{@sheight} + #{@top} -1 - #{@pminrow}"
+    @screen_maxrow || @sheight + @top -1 -@pminrow
+  end
+  ##
+  # return screen max col which will be used for writing to window
+  def smaxcol
+    #$log.debug "    ... niside smaxcol #{@swidth} + #{@left} -1 "
+    #@swidth + @left -1
+    #      $log.debug "    ... niside smaxcol #{@swidth} + #{@left} -1 - #{@pmincol} "
+    @screen_maxcol || @swidth + @left -1 - @pmincol
+  end
+  ##
+  # specify the window or subwin that the pad is writing to
+  # 2010-02-20 22:45 - actually since there are pad methods smaxrow used on otherwin
+  # therefor it can only be a Pad !! NOTE
+  def set_backing_window win
+    @otherwin = win
+    # XX should we  extract the coordinates and use for printing ??
+    # or for setting maxrow and maxcol
+  end
+  # trying to make things as easy as possible
+  # returns -1 if error in prefresh
+  def wrefresh
+    $log.debug " inside pad's wrefresh #{@window}. minr,minc,top,left,smaxr,c: #{@pminrow}, #{@pmincol}, #{@top} #{@left} #{smaxrow()} #{smaxcol()} self: #{self.name} "
+
+    # caution, prefresh uses maxrow and maxcol not height and width
+    # so we have to add top and less one since we are zero based
+    ret = @window.prefresh(@pminrow, @pmincol, @top, @left, smaxrow(), smaxcol())
+    $log.warn " WREFRESH returns -1 ERROR - width or height must be exceeding " if ret == -1
+    @modified = false
+    return ret
+  end
+  ##
+  # copy the window to the pad (assumes we are writing onto win and keeping
+  # pad as backup
+  # also assuming only one win so, window not passed as param
+  # @return return value of copywin which should be 0 (-1 is ERR)
+  def copy_pad_to_win
+    $log.warn " DEPRECATED copy_pad_to_win" # CLEANUP
+    raise "DEPREC copy_pad_to_win deprecated. Will be removed. Let me know if it is needed"
+    # check that we don't exceed other windows height/maxrow
+    smr = smaxrow()
+    # SHIT, this means the otherwin has to be a Pad, cannot be a window
+    osw = @otherwin.width
+    osh = @otherwin.height
+    osh = @height if osh == 0 # root window has 0
+    osw = @width if osw == 0 # root window has 0
+    osmr = @otherwin.smaxrow() rescue osh # TRYING for windows
+    osmc = @otherwin.smaxcol() rescue osw
+    if smr >= osmr
+      $log.debug " adjusted smr from #{smr} to #{osmr} -1 causing issues in viewfooter"
+      smr = osmr-1 # XXX causing issues in viewport, wont print footer with this
+    end
+    if smr > @sheight + @top -1 -@pminrow # 2010-01-17 13:27 
+      smr = @sheight + @top -1 -@pminrow 
+      $log.debug " adjusted smr to #{smr} to prevent crash "
+    end
+    smc = smaxcol()
+    $log.debug " SMC original = #{smc} "
+    if smc >= osmc
+      smc = osmc-1
+      smc = @width # XXX ??? THIS WAS WORKING< but throwing error in viewport case
+      smc = [osmc-1, @width].min # yet another hack
+      $log.debug " SMC o-1 #{osmc-1} wdth #{@width}, smc #{smc}  "
+    end
+    ### XXX commented out since it doesn't let a comp print fully if widget expanded (splitpane)
+    #smc = osw -1 if smc >= osw; # added 2009-11-02 17:01 for tabbedpanes
+
+    # dang, this is coming up a lot. 2010-01-16 20:34 
+    # the second scrollpane was one row too large in testsplit3a.rb
+    if smr - @top > @padheight
+      $log.debug " fixing smr to padheight  2010-01-16 20:35 HOPE THIS DOESNT BREAK ANYTHING"
+      smr = @padheight
+    end
+    @pminrow = 0 if @pminrow < 0
+    @pmincol = 0 if @pmincol < 0
+    $log.debug " COPYING #{self.name} to #{@otherwin.name} "
+    $log.debug " calling copy pad #{@pminrow} #{@pmincol}, #{@top} #{@left}, #{smr} #{smc} self #{self.name} "
+    $log.debug "  calling copy pad H: #{@height} W: #{@width}, PH #{@padheight} PW #{@padwidth} WIN:#{@window} "
+    #      $log.debug "  -otherwin target copy pad #{@otherwin.pminrow} #{@otherwin.pmincol}, #{@otherwin.top} #{@otherwin.left}, #{osmr} #{osmc} OTHERWIN:#{@otherwin.name} "
+    ret="-"
+    #if ret == -1
+    #x XXX        $log.debug "  #{ret} otherwin copy pad #{@otherwin.pminrow} #{@otherwin.pmincol}, #{@otherwin.top} #{@otherwin.left}, #{osmr} #{osmc} "
+    $log.debug "  #{ret} otherwin copy pad H: #{osh} W: #{osw}"
+    if @top >= osh
+      $log.debug "  #{ret} ERROR top exceeds other ht #{@top}   H: #{osh} "
+    end
+    if @left >= osw
+      $log.debug "  #{ret} ERROR left exceeds other wt #{@left}   W: #{osw} "
+    end
+    if smr >= osh
+      $log.debug "  #{ret} ERROR smrow exceeds other ht #{smr}   H: #{osh} "
+      smr = osh() -1 # testing 2010-01-31 21:47  , again 2010-02-05 20:22 
+    end
+    if smc >= osw
+      $log.debug "  #{ret} ERROR smcol exceeds other wt #{smc}   W: #{osw} "
+    end
+    if smc - @left > @padwidth
+      $log.debug "  #{ret} ERROR smcol - left  exceeds padwidth   #{smc}- #{@left}   PW: #{@padwidth} "
+    end
+    if smr - @top > @padheight
+      $log.debug "  #{ret} ERROR smr  - top  exceeds padheight   #{smr}- #{@top}   PH: #{@padheight} "
+    end
+    ret = @window.copywin(@otherwin.get_window,@pminrow,@pmincol, @top, @left, smr, smc, 0)
+    $log.debug " copywin ret #{ret} "
+    # 2010-01-11 19:42 one more cause of -1 coming is that padheight (actual height which never
+    # changes unless pad increases) or padwidth is smaller than area being printed. Solution: increase 
+    # buffer by increasing widgets w or h. smc - left should not exceed padwidth. smr-top should not
+    # exceed padheight
+    #end
+    @modified = false
+    return ret
+  end
+  # @deprecated
+  def copy_win_to_pad
+    $log.warn " DEPRECATED copy_win_to_pad" # CLEANUP 2011-09-29 
+    raise "DEPREC copy_win_to_pad deprecated. Will be removed. Let me know if it is needed"
+    smr = smaxrow()
+    if smr >= @window.smaxrow()
+      smr = @window.smaxrow()-1
+    end
+    $log.debug " copy_win_to_pad #{@otherwin.name}, #{@window.name}, pminr:#{@pminrow} pminc:#{@pmincol} top:#{@top} left:#{@left} smr:#{smr} "
+    ret = @otherwin.copywin(@window.get_window,@pminrow,@pmincol, @top, @left, smr, smaxcol(), 1)
+    @modified = false
+    return ret
+  end
+  ## 
+  #Used to overwrite the pad onto the screen window
+  # A window should have been specified as window to back (@see set_backing_window) or (@see create_with_window)
+  def overwrite_window
+    return @window.overwrite(@otherwin.get_window)
+  end
+
+  ## 
+  #  convenience method so that pad can use printstring but remove screen's row and col
+  #  The absolute row and col will be taken into consideration when printing on screen.
+  #  
+  # @param [Fixnum] row row to print on
+  # @param [Fixnum] col column to print on
+  # @param [String] value to print
+  # @param [Fixnum] color - color combination
+  # @param [Fixnum, nil] attrib defaults to NORMAL
+
+  # Pls remove the raise once the program is working, extra line can slow things down
+  # Keep it on when testing.
+  # If the raise is thrown, it means your object could be positioned higher than it should be,
+  # or at some point you have increased top, without increasing the objects row.
+  def printstring(row,col,value,color,attrib=Ncurses::A_NORMAL)
+    #$log.debug " pad printstring #{row} - #{@top} , #{col} - #{@left} "
+    raise "printstring row < top, pls correct code #{row} #{@top}, #{col} #{@left} " if row < @top or col < @left
+    #$log.warn "printstring row < top, pls correct code #{row} #{@top} " if row < @top
+    super(row - @top, col - @left, value, color, attrib)
+  end # printstring
+  #  convenience method so that pad can use print_border but remove screen's row and col
+  #  Please note that this requires that buffer have latest top and left.
+  def print_border row, col, height, width, color, att=Ncurses::A_NORMAL
+    $log.debug " pad printborder #{row} - #{@top} , #{col} - #{@left}, #{height} , #{width}  "
+    raise "print_border: row < top, pls correct code #{row} #{@top},  #{col} #{@left} " if row < @top or col < @left
+    #$log.warn   "print_border: row < top, pls correct code #{row} #{@top} " if row < @top
+    super(row - @top, col - @left, height, width,  color, att)
+  end
+  def print_border_only row, col, height, width, color, att=Ncurses::A_NORMAL
+    $log.debug " pad printborder_only #{row} - #{@top} , #{col} - #{@left}, #{height} , #{width}  "
+    raise "print_border row < top, pls correct code #{row} #{@top},  #{col} #{@left} " if row < @top or col < @left
+    super(row - @top, col - @left, height, width,  color, att)
+  end
+  # use in place of mvwhline if your widget could be using a pad or window
+  def rb_mvwhline row, col, char, width
+    super(row-@top, col-@left, char, width)
+  end
+  # use in place of mvwvline if your widget could be using a pad or window
+  def rb_mvwvline row, col, char, width
+    super(row-@top, col-@left, char, width)
+  end
+  # use in place of mvaddch if your widget could be using a pad or window
+  def rb_mvaddch row, col, char
+    super(row-@top, col-@left, char)
+  end
+end # class Pad
+#-------------------------------- deprecated stuff ------------------ #
+##
+# added RK 2009-10-08 23:57 for tabbedpanes
+# THIS IS EXPERIMENTAL - 
+# I have not called super in the initializer so any methods you try on subwin
+# that exist in the superclass which use @window will bomb
+# @since 0.1.3 REMOVE UNUSED.
+# @deprecated
+class SubWindow  < VER::Window
+  attr_reader :width, :height, :top, :left
+  attr_accessor :layout
+  attr_reader   :panel   # XXX reader requires so he can del it in end
+  attr_reader   :subwin   # 
+  attr_reader   :parent   # 
+
+  def initialize(parent, layout)
+    @visible = true
+    reset_layout(layout)
+
+    @parent = parent
+    #@subwin = @parent.get_window().derwin(@height, @width, @top, @left)
+    @subwin = @parent.get_window().subwin(@height, @width, @top, @left)
+    $log.debug "SUBWIN init #{@height} #{@width} #{@top} #{@left} "
+    #$log.debug "SUBWIN init #{@subwin.getbegx} #{@subwin.getbegy} #{@top} #{@left} "
+    @panel = Ncurses::Panel.new_panel(@subwin)
+
+    @window = @subwin # makes more mthods available
+    init_vars
+
+  end
+  # no need really now 
+  def reset_layout layout
+    @layout = layout # 2010-02-13 22:23 
+    @height = layout[:height]
+    @width = layout[:width]
+    @top = layout[:top]
+    @left = layout[:left]
+  end
+  def _destroy
+    # typically the ensure block should have this
+    # or should window do it for all subwins, or would we want to wait that long ?
+    $log.debug "subwin destroy"
+
+    Ncurses::Panel.del_panel(panel.pointer) if !panel.nil?    # FFI
+    #@window.delwin(@window) if !@window.nil? # added FFI 2011-09-7 
+    delwin if !@window.nil? # added FFI 2011-09-7 
+  end
+end
+
+end

data/lib/rbcurse/deprecated/rscrollpane.rb

@@ -0,0 +1,512 @@
+=begin
+  * Name: Scrollpane
+  * Description: a scrollable widget allowing user to scroll and view
+    parts of underlying object that typically are larger than screen area.
+    Mainly, contains a viewport, scrollbars and manages viewport through usage
+    of scrollbars.
+    Also contains viewport for row and columns.
+  * Author: rkumar 
+Todo section:
+  - add events, property changed etc at least for scrolling - DONE
+    SCrollpane normall should listen in to changes in viewport, however Scro calls those very methods
+    and what's more, other classes would listen to SCR and not to VP.
+  - scrollbars to be classes - shall we avoid over-engineering, and KISS
+  - if scrollpane reduced it should also resize, as example inside splitpane.
+  * file created 2009-10-27 19:20 
+  * Added a call to child's set_form_col from set_form_row
+Major changes 2010-02-11 19:51 to simplify version RFED16
+  * Still need to clean up this and viewport. make as light as possible
+  * If scrolling, no repainting should happen. Scrollpane could get the buffer
+    and scroll itself. Or ensure that inner object does not rework...
+
+  Pass handle_key to child, also repaint refer child.
+  Avoid passing to viewport as this would slow down alot.
+
+  NOTE: if a caller is interested in knowing what scrolling has happened, pls bind to :STATE_CHANGE, you will receive the viewport object. If you find this cumbersome, and wish to know only about scrolling, we can put in a scrolling event and inform of row or col scrolling. Or we can fire a property change with row or col increment.
+  
+  
+  --------
+  * License:
+    Same as Ruby's License (http://www.ruby-lang.org/LICENSE.txt)
+
+=end
+#require 'rubygems'
+#require 'ncurses'
+require 'logger'
+require 'rbcurse'
+require 'rbcurse/rviewport'
+
+#include Ncurses # FFI 2011-09-8 
+include RubyCurses
+module RubyCurses
+  extend self
+
+  ##
+  # A scrollable box throgh which one can see portions of underlying object
+  # such as textarea, table or a form, usually the underlying data is larger
+  # than what can be displayed.
+  
+  class ScrollPane < Widget
+    # viewport
+    # row_viewport
+    # column_viewport
+    # horizontal scrollbar 0-NONE, 1=ALWAYS, 2=AS_NEEDED
+    # vertical scrollbar 0-NONE, 1=ALWAYS, 2=AS_NEEDED
+    attr_accessor :cascade_changes  # should changes in size go down to child, default false
+
+    def initialize form, config={}, &block
+      @focusable = true
+      @editable = false
+      #@left_margin = 1
+      @row = 0
+      @col = 0
+      super
+      @row_offset = @col_offset = 1
+      init_vars
+      @_events.push :STATE_CHANGE
+    #  $log.debug " SCROLLPANE recvs form #{form.name}, #{form.window.name} " unless form.nil?
+
+
+    end
+    ##
+    # set child component being used in viewport
+    # @see set_viewport_view
+    def child ch
+      if ch != nil
+        @child = ch # added 2010-02-11 15:28 we might do away with viewport, setting panned to child
+        @child.rows_panned = @child.cols_panned = 0
+
+        ch.parent_component = self # added 2010-01-13 12:55 so offsets can go down ?
+
+        @child.should_create_buffer = true 
+        @form.add_rows += 2 # related to scr_top  XXX What if form not set. i cannot keep accumulating
+        update_child
+        # -3 since we start row +1 to get indented by 1, also we use
+        # height -1 in scrollpane, so we need -2 to indent, and one more
+        # for row
+        set_viewport_view(ch)
+      end
+    end
+    ## 
+    # update of child's coordinates, needs to be called whenever it
+    # changes, so i need to call it before calling child's update
+    # FIXME - this is become 2 calls, make it one - becoming expensive
+    # if called often
+    def update_child
+      scr_top = 3 # for Pad, if Pad passed as in SplitPane
+      scr_left = 1 # for Pad, if Pad passed as in SplitPane
+      if @form.window.window_type == :WINDOW
+        scr_top = @row + 1
+        scr_left = @col + 1
+        @child.row(@row+@row_offset)
+        @child.col(@col+@col_offset)
+      else
+        # PAD case
+        @child.row(scr_top)
+        @child.col(scr_left)
+      end
+        @child.set_buffering(:target_window => @target_window || @form.window, :form => @form, :bottom => @height-3, :right => @width-3 )
+        @child.set_buffering(:screen_top => scr_top, :screen_left => scr_left)
+        # lets set the childs ext offsets
+        $log.debug "SCRP #{name} adding (to #{@child.name}) ext_row_off: #{@child.ext_row_offset} +=  #{@ext_row_offset} +#{@row_offset}  "
+        $log.debug "SCRP adding ext_col_off: #{@child.ext_col_offset} +=  #{@ext_col_offset} +#{@col_offset}  "
+        ## 2010-02-09 18:58 i think we should not put col_offset since the col
+        ## of child would take care of that. same for row_offset. XXX 
+        @child.ext_col_offset += @ext_col_offset + @col + @col_offset - @screen_left # 2010-02-09 19:14 
+        # added row and col setting to child RFED16 2010-02-17 00:22 as
+        # in splitpane. seems we are not using ext_offsets now ? texta
+        # and TV are not. and i've commented off from widget
+
+        $log.debug " #{@child.ext_row_offset} +=  #{@ext_row_offset} + #{@row} -#{@screen_top}  "
+        @child.ext_row_offset +=  @ext_row_offset  + @row   + @row_offset - @screen_top 
+        # adding this since child's ht should not be less. or we have a
+        # copywin failure
+        @child.height ||= @height
+        @child.width ||= @width
+        if @child.height < @height
+          @child.height = @height
+        end
+        if @child.width < @width
+          @child.width = @width
+        end
+
+    end
+    def init_vars
+      #@curpos = @pcol = @toprow = @current_index = 0
+      @hsb_policy = :AS_NEEDED
+      @vsb_policy = :AS_NEEDED
+      @repaint_required = true
+      @repaint_border = true
+      @row_outofbounds=0
+      @col_outofbounds=0
+      @border_width = 2
+      @screen_top = 0
+      @screen_left = 0
+    end
+    # set the component to be viewed
+    def set_viewport_view ch
+      @viewport = Viewport.new nil
+      @viewport.set_view ch
+      ## this -2 should depend on whether we are putting border/scrollbars or not.
+      # -1 added on 2010-02-16 23:35 since we are red 1, and bw
+      @viewport.set_view_size(@height-@border_width-0, @width-@border_width-0) # XXX make it one less
+      @viewport.cascade_changes = @cascade_changes # added 2010-02-04 18:19 
+      @viewport.bind(:STATE_CHANGE) { |e| view_state_changed(e) }
+      @viewport.bind(:PROPERTY_CHANGE) { |e| view_property_changed(e) }
+    end
+    # return underlying viewport
+    # in order to run some of its methods
+    def get_viewport
+      return @viewport
+    end
+    # Directly set the viewport.
+    # Usually it is best to use set_viewport_view instead
+    def set_viewport vp
+      old = @viewport
+      @viewport = vp
+      fire_property_change "viewport", old, @viewport
+    end
+    # sets the component to be used as a rowheader TODO
+    def set_rowheader_view ch
+      old = @rowheader
+      @rowheader = Viewport.new
+      @rowheader.set_view ch
+      fire_property_change "row_header", old, @rowheader
+    end
+    # sets the component to be used as a column header TODO
+    def set_columnheader_view ch
+      old = @columnheader
+      @columnheader = Viewport.new
+      @columnheader.set_view ch
+      fire_property_change "column_header", old, @columnheader
+    end
+    def set_view_size h,w
+      # calling the property shoudl uniformally trigger fire_property_change
+      @viewport.set_view_size h,w
+      #height(h)
+      #width(w)
+      #fire_handler :PROPERTY_CHANGE, self # XXX should it be an event STATE_CHANGED with details
+    end
+    ## seems i wrote this only so i could set repaint_required to true
+    # However, now that VP calls state changed, that will happen XXX
+    def set_view_position r,c
+      ret = @viewport.set_view_position r,c
+      if ret
+        @repaint_required = true if ret 
+    #    fire_property_change("view_position", 
+      end
+      return ret
+    end
+    # this method is registered with Viewport for changes
+    def view_state_changed ev
+      fire_handler :STATE_CHANGE, ev #???
+      @repaint_required = true
+    end
+    # this method is registered with Viewport for changes to properties
+    def view_property_changed ev
+      fire_handler :PROPERTY_CHANGE, ev #???
+      @repaint_required = true
+    end
+    # @return [true, false] false if r,c not changed
+    def increment_view_row num
+#x      r = @viewport.row() #- @viewport.top_margin
+#x      c = @viewport.col() #- @viewport.left_margin
+      r, c = @viewport.get_pad_top_left()
+      $log.debug " SCR inc viewport currently :  r #{r} c #{c} "
+      r += num
+      ret = set_view_position r, c
+      v_scroll_bar if ret
+      return ret
+    end
+    # @return [true, false] false if r,c not changed
+    def increment_view_col num
+      r, c = @viewport.get_pad_top_left()
+      #r = @viewport.row() #- @viewport.top_margin
+      #c = @viewport.col() #- @viewport.left_margin
+      c += num
+      ret = set_view_position r, c
+      h_scroll_bar if ret
+      return ret
+    end
+    def repaint # scrollpane
+      # viewports child should repaint onto pad
+      # viewport then clips
+      # this calls viewports refresh from its refresh
+      return unless @repaint_required
+      if @viewport
+        update_child
+        $log.debug "SCRP  #{@name} calling viewport repaint"
+        #@viewport.repaint_all true # 2010-01-16 23:09 
+        @viewport.repaint_required true # changed 2010-01-19 19:34 
+        @viewport.repaint # child's repaint should do it on its pad
+        $log.debug " #{@name}  SCRP scrollpane repaint #{@graphic.name} "
+      end
+        # TODO this only if major change
+       if @repaint_border && @repaint_all # added 2010-01-16 20:15 
+        #@graphic.wclear
+        $log.debug " #{@name} repaint all scroll: r #{@row} c #{@col}  h  #{@height}-1 w #{@width} "
+        bordercolor = @border_color || $datacolor
+        borderatt = @border_attrib || Ncurses::A_NORMAL
+        # NOTE - should be width-1 print_b reduces one from width, but
+        # not height !
+
+        @graphic.print_border_only(@row, @col, @height-1, @width, bordercolor, borderatt)
+        h_scroll_bar
+        v_scroll_bar
+#x XXX       @viewport.repaint_all(true) unless @viewport.nil? # brought here 2010-01-19 19:34 
+        #@repaint_border = false # commented off on 2010-01-16 20:15 so repaint_all can have effect
+       end
+      return if @viewport == nil
+      $log.debug "SCRP   #{@name} calling viewport to SCRP  b2s #{@graphic.name}  "
+      paint 
+    end
+    def getvalue
+      # TODO
+    end
+    ## handle keys for scrollpane.
+    # First hands key to child object
+    # If unused, checks to see if it has anything mapped.
+    # If not consumed, returns :UNHANDLED, else 0.
+    def handle_key ch
+      # if this gets key it should just hand it to child
+        return :UNHANDLED if @viewport.nil? # added 2010-02-02 12:44 
+      if @viewport != nil
+        $log.debug "    calling child handle_key #{ch} "
+        ret = @viewport.handle_key ch
+        # XXX ret returns 0under normal circumstance, so will next line work ?
+        # what i mean is if ret == 0
+        
+        @repaint_required = true if ret == 0  # added 2009-12-27 22:21 BUFFERED
+        $log.debug "  ... child ret #{ret}"
+
+
+        ## Here's the only option scrollpane has of checking whether the child has
+        ##+ exceeded boundary BUFFERED 2009-12-29 23:12 
+        #  TEMPORARILY COMMENTED WHILE TESTING SCROLL UP AND DOWN XXX
+        #fr = @form.row
+        #fc = @form.col
+        #if fr >= @row + @height -2
+          #@form.setrowcol @row + @height -2, fc
+        #elsif fr < @row
+          #@form.setrowcol @row, fc
+        #end
+        #if fc >= @col + @width -1
+          #@form.setrowcol fr, @col + @width -1
+        #end
+        ##
+
+        return ret if ret != :UNHANDLED
+      end
+      ret = 0 # default return value
+      ks = keycode_tos(ch)
+      $log.debug " scrollpane gets KEY #{ch}, ks #{ks} "
+      case ch
+        when ?\M-n.getbyte(0)
+          ## scroll down one row (unless multiplier set)
+          ret = down
+      when ?\M-p.getbyte(0)
+          ## scroll up one row (unless multiplier set)
+        ret = up
+      #when ?0.getbyte(0), ?\C-[.getbyte(0)
+        #goto_start #start of buffer # cursor_start
+      #when ?\C-].getbyte(0)
+        #goto_end # end / bottom cursor_end # TODO
+      when ?\M-\<.getbyte(0)
+        @height.times { up ; }
+      when ?\M-\>.getbyte(0)
+        @height.times { down ; }
+      when KEY_DOWN
+        ret = down
+        #check_curpos
+      when  ?\M-h.getbyte(0)
+        ## scroll left one position
+        repeatm {
+          ret = cursor_backward
+          @child.cols_panned = @child.cols_panned+1  if ret
+          @form.setrowcol @form.row, @form.col+1+@col_outofbounds if ret 
+        }
+      when  ?\M-l.getbyte(0)
+        ## scroll right one position
+        repeatm {
+          ret = cursor_forward
+          @child.cols_panned = @child.cols_panned-1  if ret
+          @form.setrowcol @form.row, @form.col-1+@col_outofbounds if ret 
+        }
+      when KEY_BACKSPACE, KEY_BSPACE
+        ret = cursor_backward
+      #when ?\C-u.getbyte(0)
+        ## multiplier. Series is 4 16 64
+        #@multiplier = (@multiplier == 0 ? 4 : @multiplier *= 4)
+        #return 0
+      when ?\C-c.getbyte(0)
+        $multiplier = 0
+        return 0
+      else
+        return :UNHANDLED
+      end
+      ret = :UNHANDLED if !ret
+      $multiplier = 0
+      return ret # 0 2010-02-04 18:47 returning ret else repaint is happening when UNHANDLED
+    end
+    # private
+    def _down
+      increment_view_row(1)
+    end
+    # private
+    def _up
+      increment_view_row(-1)
+    end
+    def cursor_forward
+      increment_view_col(1)
+    end
+    def cursor_backward
+      increment_view_col(-1)
+    end
+    def down
+      ## scroll down one row (currently one only)
+      $log.debug " MULT DOWN #{$multiplier} "
+      repeatm {
+      ret = _down
+      return unless ret # 2010-02-04 18:29 
+      ## we've scrolled down, but we need  to keep the cursor where
+      ##+ editing actually is. Isn't this too specific to textarea ?
+      $log.debug " SCRP setting row to #{@form.row-1} upon scrolling down  "
+      ## only move up the cursor if its within bounds
+      #       if @form.row > @row
+      @child.rows_panned = @child.rows_panned-1  if ret 
+      @form.setrowcol @form.row-1+@row_outofbounds, @form.col if ret 
+      }
+    end
+    def up
+          ## scroll up one row (currently one only)
+      repeatm {
+        ret = _up
+        return unless ret # 2010-02-04 18:29 
+        $log.debug " SCRP setting row to #{@form.row+1} upon scrolling up R:#{@row} H:#{@height}  "
+   #     if @form.row < @row + @height
+          @child.rows_panned = @child.rows_panned+1  if ret 
+          @form.setrowcol @form.row+1+@row_outofbounds, @form.col if ret 
+      }
+    end
+    def on_enter
+      #super 2010-01-02 18:53 leading to a stack overflow XXX ???
+      set_form_row
+    end
+    # this is called once externally, on on_enter
+    #+ after that its called internally only, which in this case is never
+    def set_form_row
+      #@form.row = @row + 1 unless @form.nil?
+      if @viewport != nil
+        #$log.debug "    calling scrollpane set_form_row"
+        ret = @viewport.child.set_form_row # added 2009-12-27 23:23 BUFFERED
+        ret = @viewport.child.set_form_col # added 2010-01-16 21:09 
+      end
+      $log.debug " FORM SCRP #{@form.name} "
+      $log.debug "SCRP set_form_row #{@form.row}  #{@form.col} "
+    end
+    ## added 2010-02-09 10:17 
+    # Sometimes some parent objects may just call this.
+    # Would be better if they only called row and row called both ??? or is that less reliable
+    # In any case we have to combine this someday!!
+    def set_form_col
+      #@form.row = @row + 1 unless @form.nil?
+      if @viewport != nil
+        #$log.debug "    calling scrollpane set_form_row"
+        ret = @viewport.child.set_form_col # added 2010-01-16 21:09 
+      end
+      $log.debug " FORM SCRP #{@form.name} "
+      $log.debug "SCRP set_form_col #{@form.row}  #{@form.col} "
+    end
+
+    ## this is called once only, on select_field by form.
+    ##+ after that not at all.
+    def rowcol
+      r1 = @row #+@row_offset
+      c1 = @col #+@col_offset
+      return r1, c1 if @viewport.nil? # added 2010-02-02 12:41 
+
+      r,c = @viewport.child.rowcol # added 2009-12-28 15:23 BUFFERED
+      $log.debug "SCRP rowcol:  #{r1} + #{r} , #{c1} + #{c} "
+      return r1+r, c1+c
+    end
+
+    def paint
+      @repaint_required = false
+      @repaint_all = false
+    end
+    def h_scroll_bar
+      return if @viewport.nil?
+      sz = (@viewport.width*1.00/@viewport.child().width)*@viewport.width
+      #$log.debug " h_scroll_bar sz #{sz}, #{@viewport.width} #{@viewport.child().width}" 
+      sz = sz.ceil
+      return if sz < 1
+      start = 1
+      start = ((@viewport.col*1.00+@viewport.width)/@viewport.child().width)*@viewport.width
+      start -= sz
+      start = start.ceil
+      # # the problem with next 2 lines is that attributes of border could be overwritten
+      # draw horiz line
+      r = @row #+ @ext_row_offset # 2010-02-11 11:57 RFED16
+      c = @col #+ @ext_col_offset # 2010-02-11 11:57 RFED16
+      $log.debug " h_scroll_bar start #{start}, r #{r} c #{c} h:#{@height} "
+      @graphic.rb_mvwhline(r+@height-1, c+1, FFI::NCurses::ACS_HLINE, @width-2)
+      # draw scroll bar
+      #sz.times{ |i| @graphic.mvaddch(r+@height-1, c+start+1+i, FFI::NCurses::ACS_CKBOARD) }
+      sz.times{ |i| @graphic.rb_mvaddch(r+@height-1, c+start+1+i, FFI::NCurses::ACS_CKBOARD) }
+    end
+    def v_scroll_bar
+        return if @viewport.nil?
+      sz = (@viewport.height*1.00/@viewport.child().height)*@viewport.height
+      #$log.debug " v_scroll_bar sz #{sz}, #{@viewport.width} #{@viewport.child().width}" 
+      sz = sz.ceil
+      return if sz < 1
+      start = 1 
+      start = ((@viewport.row*1.00+@viewport.height)/@viewport.child().height)*@viewport.height
+      start -= sz
+      r = @row #+ @ext_row_offset # 2010-02-11 11:57 RFED16
+      c = @col #+ @ext_col_offset # 2010-02-11 11:57 RFED16
+      $log.debug " v_scroll_bar start #{start}, col:#{@col} w:#{@width}, r #{r}+1 c #{c}+w-1 " 
+      start = start.ceil
+      # # the problem with next 2 lines is that attributes of border could be overwritten
+      # draw verti line
+      # this is needed to erase previous bar when shrinking
+      #@graphic.mvwvline(r+1,c+@width-1, FFI::NCurses::ACS_VLINE, @height-2)
+      @graphic.rb_mvwvline(r+1,c+@width-1, FFI::NCurses::ACS_VLINE, @height-2)
+      # draw scroll bar
+      #sz.times{ |i| @graphic.mvaddch(r+start+1+i, c+@width-1, FFI::NCurses::ACS_CKBOARD) }
+      sz.times{ |i| @graphic.rb_mvaddch(r+start+1+i, c+@width-1, FFI::NCurses::ACS_CKBOARD) }
+    end
+    # set height
+    # a container must pass down changes in size to it's children
+    #  2010-02-04 18:06 - i am not sure about this. When viewport is set then it passes down 
+    #  changes to child which user did not intend. Maybe in splitpane it is okay but other cases?
+    #  Perhaps its okay if scrollpane gets larger than child, not otherwise.
+    # added 2010-01-16 23:55 
+      def height(*val)
+          return @height if val.empty?
+          oldvalue = @height || 0
+          super
+          @height = val[0]
+          return if @viewport == nil
+          delta = @height - oldvalue
+          return if delta == 0
+          @repaint_required = true
+          @viewport.height += delta
+      end
+    # set width
+    # a container must pass down changes in size to it's children
+    # added 2010-01-16 23:55 
+      def width(*val)
+          return @width if val.empty?
+          oldvalue = @width || 0
+          super
+          @width = val[0]
+          return if @viewport == nil
+          delta = @width - oldvalue
+          return if delta == 0
+          @repaint_required = true
+          @viewport.width += delta
+      end
+
+  end # class ScrollPane
+end # module