ncumbra 0.1.0

data/lib/umbra/button.rb

@@ -0,0 +1,130 @@
+# ----------------------------------------------------------------------------- #
+#         File: button.rb
+#  Description: button widget that has an action associated with :PRESS event
+#     which by default is the SPACE key.
+#       Author: j kepler  http://github.com/mare-imbrium/canis/
+#         Date: 2018-03-16 
+#      License: MIT
+#  Last update: 2018-04-07 23:07
+# ----------------------------------------------------------------------------- #
+#  button.rb  Copyright (C) 2012-2018 j kepler
+#  == TODO 
+#  - mnemonics with highlighting
+#  - default button
+require 'umbra/widget'
+#  ----------------
+module Umbra
+  class Button < Widget 
+    attr_accessor :surround_chars   # characters to use to surround the button, def is square brackets
+    # char to be underlined, and bound to Alt-char
+    attr_accessor :mnemonic
+    def initialize config={}, &block
+      @focusable = true
+      @editable = false
+      @highlight_attr = REVERSE
+      # hotkey denotes we should bind the key itself not alt-key (for menulinks)
+      #@hotkey = config.delete(:hotkey)  2018-03-22 - 
+      # 2018-03-18 - FORM_ATTACHED deprecated to keep things simple
+      register_events([:PRESS])
+      @default_chars = ['> ', ' <'] # a default button is painted differently
+      super
+
+
+      @surround_chars ||= ['[ ', ' ]'] 
+      @col_offset = @surround_chars[0].length 
+      @text_offset = 0      # used to determine where underline should fall TODO ???
+      map_keys
+    end
+    ##
+    # set button based on Action
+    # 2018-03-22 - is this still used ?
+    # This allows action objects to be used in multiple places such as buttons, menus, popups etc.
+    def action a
+      text a.name
+      mnemonic a.mnemonic unless a.mnemonic.nil?
+      command { a.call }
+    end
+
+    def getvalue
+      @text
+    end
+
+    # ensure text has been passed or action
+    def getvalue_for_paint
+      ret = getvalue
+      @text_offset = @surround_chars[0].length
+      @surround_chars[0] + ret + @surround_chars[1]
+    end
+
+    def repaint  # button
+      return unless @repaint_required
+
+        $log.debug("BUTTON repaint : #{self}  r:#{@row} c:#{@col} , cp:#{@color_pair}, st:#{@state}, #{getvalue_for_paint}" )
+        r,c = @row, @col 
+        _attr = @attr || NORMAL
+        _color = @color_pair
+        if @state == :HIGHLIGHTED
+          _color = @highlight_color_pair || @color_pair
+          _attr = @highlight_attr || _attr
+        elsif selected? # only for certain buttons lie toggle and radio
+          _color = @selected_color_pair || @color_pair
+        end
+        #$log.debug "XXX: button #{text}   STATE is #{@state} color #{_color} , attr:#{_attr}"
+        value = getvalue_for_paint
+        #$log.debug("button repaint :#{self} r:#{r} c:#{c} col:#{_color} v: #{value} ul #{@underline} mnem #{@mnemonic} ")
+        #len = @width || value.length # 2018-04-07 - width is not serving a purpose right now
+        #                             # since surround chars still come where they do, and only highlight uses the width
+        #                             which looks wrong.
+        len = value.length
+        @graphic.printstring r, c, "%-*s" % [len, value], _color, _attr
+
+        # if a mnemonic character has been defined, then locate the index and highlight it.
+        # TODO a mnemonic can also be defined in the text with an ampersand.
+        if @mnemonic
+          index = value.index(@mnemonic) || value.index(@mnemonic.swapcase)
+          if index
+            y = c + index
+            x = r
+            @graphic.mvchgat(x, y, max=1, FFI::NCurses::A_BOLD|UNDERLINE, FFI::NCurses.COLOR_PAIR(_color || 1), nil)
+          end
+        end
+        @repaint_required = false
+    end
+
+    ## command of button (invoked on press, hotkey, space)
+    # added args 2008-12-20 19:22 
+    def command *args, &block
+      bind_event :PRESS, *args, &block
+    end
+    ## fires PRESS event of button
+    def fire
+      #$log.debug "firing PRESS #{text}"
+      fire_handler :PRESS, ActionEvent.new(self, :PRESS, text)
+    end
+    # for campatibility with all buttons, will apply to radio buttons mostly
+    def selected?; false; end
+
+    def map_keys
+      return if @keys_mapped
+      bind_key(32, "fire") { fire } if respond_to? :fire
+    end
+
+    # Button
+    def handle_key ch
+      super
+    end
+
+    # layout an array of buttons horizontally {{{
+    def self.button_layout buttons, row, startcol=0, cols=FFI::NCurses.COLS-1, gap=5
+      col = startcol
+      buttons.each_with_index do |b, ix|
+        $log.debug " BUTTON #{b}: #{b.col} "
+        b.row = row
+        b.col col
+        $log.debug " after BUTTON #{b}: #{b.col} "
+        len = b.text.length + gap
+        col += len
+      end
+    end
+  end #BUTTON # }}}
+end # module

data/lib/umbra/buttongroup.rb

@@ -0,0 +1,96 @@
+# ----------------------------------------------------------------------------- #
+#         File: buttongroup.rb
+#  Description: Manages a group of radio buttons
+#       Author: j kepler  http://github.com/mare-imbrium/canis/
+#         Date: 2018-04-02 - 08:47
+#      License: MIT
+#  Last update: 2018-04-02 23:30
+# ----------------------------------------------------------------------------- #
+#  buttongroup.rb  Copyright (C) 2012-2018 j kepler
+# This is not a visual class or a widget.
+# This class allows us to attach several RadioButtons to it, so it can maintain which one is the 
+# selected one. It also allows for assigning of commands to be executed whenever a button is pressed,
+# akin to binding to the +fire+ of the button, except that one would not have to bind to each button,
+# but only once here.
+#
+# @example
+#     group = ButtonGroup.new
+#     group.add(r1).add(r2).add(r3)
+#     group.command(somelabel) do |grp, label| label.text = grp.value; end
+#
+class ButtonGroup 
+
+  # Array of buttons that have been added.
+  attr_reader    :elements
+  # name for group, can be used in messages
+  attr_accessor  :name
+
+  # the value of the radio button that is selected. To get the button itself, use +selection+.
+  attr_reader :value
+
+  def initialize name="Buttongroup"
+    @elements = []
+    @hash     = {}
+    @name     = name
+  end
+
+  # add a radio button to the group.
+  def add e
+    @elements << e
+    @hash[e.value] = e
+    e.button_group=(self)
+    self
+  end
+  # remove button from group
+  def remove e
+    @elements.delete e
+    @hash.delete e.value
+    self
+  end
+
+  # @return the radiobutton that is selected
+  def selection
+    @hash[@value]
+  end
+
+  # @param [String, RadioButton] +value+ of a button, or +Button+ itself to check if selected.
+  # @return [true or false] for whether the given value or button is the selected one
+  def selected? val
+    if val.is_a? String
+      @value == val
+    else
+      @hash[@value] == val
+    end
+  end
+  # install trigger to call whenever a value is updated
+  # @public called by user components
+  def command *args, &block
+    @commands ||= []
+    @args ||= []
+    @commands << block
+    @args << args
+  end
+  # select the given button or value. 
+  # This may be called by user programs to programmatically select a button
+  def select button
+    if button.is_a? String
+      ;
+    else
+      button = button.value
+    end
+    self.value = button
+  end
+  # whenever a radio button is pressed, it updates the value of the group with it;s value.
+  # since only one is true at a time.
+  def value=(value)
+    @value = value
+    # 2018-04-02 - need to repaint all the radio buttons so they become off
+    @elements.each {|e| e.repaint_required = true }
+
+    return unless @commands
+    @commands.each_with_index do |comm, ix|
+      comm.call(self, *@args[ix]) unless comm.nil?
+    end
+  end
+
+end 

data/lib/umbra/checkbox.rb

@@ -0,0 +1,42 @@
+# ----------------------------------------------------------------------------- #
+#         File: checkbox.rb
+#  Description: 
+#       Author: j kepler  http://github.com/mare-imbrium/canis/
+#         Date: 2018-04-01 - 16:08
+#      License: MIT
+#  Last update: 2018-04-01 16:21
+# ----------------------------------------------------------------------------- #
+#  checkbox.rb  Copyright (C) 2012-2018 j kepler
+module Umbra
+  ##
+  # A checkbox, may be selected or unselected
+  #
+  class Checkbox < ToggleButton 
+    attr_accessor :align_right    # the button will be on the right 2008-12-09 23:41 
+    # if a variable has been defined, off and on value will be set in it (default 0,1)
+    def initialize config={}, &block
+      @surround_chars = ['[', ']']    # 2008-12-23 23:16 added space in Button so overriding
+      super
+    end
+    def getvalue
+      @value 
+    end
+      
+    def getvalue_for_paint
+      buttontext = getvalue() ? "X" : " "
+      dtext = @width.nil? ? @text : "%-*s" % [@width, @text]
+      dtext = "" if @text.nil?  # added 2009-01-13 00:41 since cbcellrenderer prints no text
+      if @align_right
+        @text_offset = 0
+        @col_offset = dtext.length + @surround_chars[0].length + 1
+        return "#{dtext} " + @surround_chars[0] + buttontext + @surround_chars[1] 
+      else
+        pretext = @surround_chars[0] + buttontext + @surround_chars[1] 
+        @text_offset = pretext.length + 1
+        @col_offset = @surround_chars[0].length
+        #@surround_chars[0] + buttontext + @surround_chars[1] + " #{@text}"
+        return pretext + " #{dtext}"
+      end
+    end
+  end # class 
+end # module

data/lib/umbra/dialog.rb

@@ -0,0 +1,214 @@
+# ----------------------------------------------------------------------------- #
+#         File: dialog.rb
+#  Description: A simple dialog box that only depends on window.
+#        This does not have forms or buttons, fields etc. That would introduce a circular
+#        dependence that I would like to avoid. This way widgets can include this to print an error
+#        or other message.
+#        NOTE: to check similar behavior, load "links" and press "q", its displays a dialog box with yes/no.
+#        Also check midnight-commander, press F10 to quit and see dialog box.
+#       Author: j kepler  http://github.com/mare-imbrium/canis/
+#         Date: 2018-03-27 - 12:09
+#      License: MIT
+#  Last update: 2018-04-20 11:05
+# ----------------------------------------------------------------------------- #
+#  dialog.rb  Copyright (C) 2012-2018 j kepler
+#
+require 'umbra/window'
+module Umbra
+
+# A simple dialog box that only displays a line of text, centered.
+# It can take an array of button labels (just strings) and display them, and return the index
+# of the button pressed, when closed.
+# If no buttons are supplied, an "Ok" button is displayed.
+# Minimum requirements are `text` and `title`
+class Dialog
+
+  attr_accessor  :text                       # text or message to print centered
+  attr_accessor  :title                      # title of dialog
+  attr_accessor  :title_color_pair           # color pair of title
+  attr_accessor  :title_attr                 # attribute of title
+  attr_accessor  :window_color_pair          # color pair of window
+  attr_accessor  :window_attr                # attribute of window
+  attr_accessor  :border_color_pair          # color pair of border
+  attr_accessor  :border_attr                # attribute of border
+  attr_accessor  :buttons                    # button text array
+
+  ## currently color and attr for text is missing. I think it should be what window has.
+
+  def initialize config={}, &block
+    config.each_pair { |k,v| variable_set(k,v) }
+    if block_given?
+      if block.arity > 0
+        yield self
+      else
+        self.instance_eval(&block)
+      end
+    end
+    @title       ||= "Alert"
+    @buttons     ||= ["Ok"]
+  end
+
+  private def variable_set var, val
+    send("#{var}=", val) 
+  end
+  private def _create_window
+    text = @text || "Warning! Did not get text"
+    #h = 7
+    # increase height to 9 so we can put a fake button below text
+    h = 9
+    w = text.size + 20
+    # don't exceed max
+    w = [FFI::NCurses.COLS-10, w].min
+    @window_color_pair ||= CP_BLACK
+    @window_attr       ||= REVERSE
+    win = create_centered_window h, w, @window_color_pair, @window_attr
+
+    ## ---- border section --- {{{
+    row = 1
+    col = 2
+    borderatt   = @border_attr || NORMAL
+    bordercolor = @border_color_pair || CP_BLACK
+    win.wattron(bordercolor | borderatt)
+    print_border_mb win, row, col, win.height, win.width, nil, nil
+    win.wattroff(bordercolor | borderatt)
+    ## ---- border section --- }}}
+
+    ## ---- title section ---- {{{
+    @title            ||= "No title"
+    @title_color_pair ||= CP_CYAN
+    @title_attr       ||= REVERSE
+    title = " "+@title+" "
+    # normalcolor gives a white on black stark title like links and elinks
+    # You can also do 'acolor' to give you a sober title that does not take attention away, like mc
+    win.printstring(row=1,col=(w-title.length)/2,title, color=@title_color_pair, @title_attr)
+    ## ---- title section ---- }}}
+
+    # text can be longer than window. truncate or wrap
+    # tet.size can be longer than w
+    _col = (w-text.size)/2
+    _col = 3 if _col < 3
+    win.printstring 3, _col, text
+    ## ---- button section ---- {{{
+    paint_buttons win, @buttons, 0
+    ## ---- button section ---- }}}
+    @window = win
+    win.wrefresh
+  end
+  def paint_buttons win, buttons, active_index
+    brow   = 6
+    bcol   = (win.width-(buttons.size*10))/2
+    origbcol = bcol
+    FFI::NCurses.mvwhline(win.pointer, brow-1, 3, FFI::NCurses::ACS_HLINE, win.width-6)
+    #@button_color ||= create_color_pair(COLOR_BLACK, COLOR_MAGENTA)
+    @button_color ||= CP_BLACK
+    active_color = create_color_pair(COLOR_BLACK, COLOR_MAGENTA)
+    #active_color = create_color_pair(COLOR_MAGENTA, COLOR_BLACK)
+    active_col = bcol
+    buttons.each_with_index do |button, ix|
+      button_attr  = NORMAL
+      button_color = @button_color
+      _button = "[ #{button} ]"
+      if ix == active_index
+        button_attr = BOLD
+        button_color = active_color
+        active_col = bcol
+        _button = "> #{button} <"
+      end
+      win.printstring brow, bcol, _button, button_color, button_attr
+      bcol += 10
+    end
+    FFI::NCurses.wmove(win.pointer, brow, active_col+2)
+  end
+
+  # convenience func to get int value of a key {{{
+  # added 2014-05-05
+  # instead of ?\C-a.getbyte(0)
+  # use key(?\C-a)
+  # or key(?a) or key(?\M-x)
+  def key ch
+    ch.getbyte(0)
+  end # }}}
+  def run
+   _create_window unless @window 
+    win = @window
+    buttoncount = @buttons.count
+    buttonindex = 0
+    begin
+      while (ch = win.getkey) != FFI::NCurses::KEY_RETURN
+        begin
+          next if ch == -1
+          break if ch == 32 or key(?q) == ch
+          # go to next button if right or down or TAB pressed
+          if ch == FFI::NCurses::KEY_TAB or ch == FFI::NCurses::KEY_RIGHT or FFI::NCurses::KEY_DOWN
+            buttonindex += 1
+          elsif ch == FFI::NCurses::KEY_LEFT or FFI::NCurses::KEY_UP
+            buttonindex -= 1
+          else
+            # should check against first char of buttons TODO
+            #puts "Don't know #{ch}"
+          end
+          buttonindex = 0 if buttonindex > buttoncount-1
+          buttonindex = buttoncount-1 if buttonindex < 0
+          paint_buttons win, @buttons, buttonindex
+        rescue => e
+          puts e
+          puts e.backtrace.join("\n")
+        end
+        win.wrefresh
+      end
+    ensure
+      win.destroy
+    end
+    #FFI::NCurses.endwin # don't think this should be here if popped up by another window
+    return buttonindex
+  end
+end # module
+
+  # create a centered window. # {{{
+  # NOTE: this should probably go into window class, or some util class.
+  # TODO: it hardcodes background color. fix this.
+  def create_centered_window height, width, color_pair=0, attrib=REVERSE
+    row = ((FFI::NCurses.LINES-height)/2).floor
+    col = ((FFI::NCurses.COLS-width)/2).floor
+    win = Window.new  height, width, row, col
+    #FFI::NCurses.wbkgd(win.pointer, FFI::NCurses.COLOR_PAIR(0) | REVERSE); #  does not work on xterm-256color
+    FFI::NCurses.wbkgd(win.pointer, FFI::NCurses.COLOR_PAIR(color_pair) | attrib); #  does not work on xterm-256color
+    #FFI::NCurses.wbkgd(win.pointer, color_pair | attrib)
+    return win
+  end # }}}
+  private def print_border_mb window, row, col, height, width, color, attr # {{{
+    win = window.pointer
+    #att = attr
+    len = width
+    len = FFI::NCurses.COLS if len == 0
+    space_char = " ".codepoints.first
+    (row-1).upto(row+height-1) do |r|
+      # this loop clears the screen, printing spaces does not work since ncurses does not do anything
+      FFI::NCurses.mvwhline(win, r, col, space_char, len)
+    end
+
+    FFI::NCurses.mvwaddch win, row, col, FFI::NCurses::ACS_ULCORNER
+    FFI::NCurses.mvwhline( win, row, col+1, FFI::NCurses::ACS_HLINE, width-6)
+    FFI::NCurses.mvwaddch win, row, col+width-5, FFI::NCurses::ACS_URCORNER
+    FFI::NCurses.mvwvline( win, row+1, col, FFI::NCurses::ACS_VLINE, height-4)
+
+    FFI::NCurses.mvwaddch win, row+height-3, col, FFI::NCurses::ACS_LLCORNER
+    FFI::NCurses.mvwhline(win, row+height-3, col+1, FFI::NCurses::ACS_HLINE, width-6)
+    FFI::NCurses.mvwaddch win, row+height-3, col+width-5, FFI::NCurses::ACS_LRCORNER
+    FFI::NCurses.mvwvline( win, row+1, col+width-5, FFI::NCurses::ACS_VLINE, height-4)
+  end # }}}
+end
+
+if __FILE__ == $0
+  include Umbra
+  ch = nil
+  begin
+    init_curses
+    cp = create_color_pair( COLOR_BLUE, COLOR_WHITE )
+    m = Dialog.new text: ARGV[0], title: ARGV[1]||"Alert", buttons: ["Yes", "No"], window_color_pair: cp, window_attr: NORMAL
+    ch = m.run
+  ensure
+    FFI::NCurses.endwin 
+  end
+  puts "got key: #{ch}"
+end

data/lib/umbra/eventhandler.rb

@@ -0,0 +1,134 @@
+module Umbra
+  # module containing methods to enable widgets and forms to handle events.
+  # Included by form and widget
+  module EventHandler 
+    # register_events: widgets may register their events prior to calling super {{{
+    # This ensures that caller programs don't use wrong event names.
+    #
+    def register_events eves
+      @_events ||= []
+      case eves
+      when Array
+        @_events.push(*eves)
+      when Symbol
+        @_events << eves
+      else
+        raise ArgumentError "register_events: Don't know how to handle #{eves.class}"
+      end
+    end # }}}
+    ##
+    # bind_event: bind an event to a block, optional args will also be passed when calling {{{
+    # 2018-04-01 - renamed +bind+ to +bind_event+
+    def bind_event event, *xargs, &blk
+      #$log.debug "#{self} called EventHandler BIND #{event}, args:#{xargs} "
+      if @_events
+        $log.warn "bind: #{self.class} does not support this event: #{event}. #{@_events} " if !event? event
+        #raise ArgumentError, "#{self.class} does not support this event: #{event}. #{@_events} " if !event? event
+      else
+        # it can come here if bind in initial block, since widgets add to @_event after calling super
+        # maybe we can change that.
+        $log.warn "BIND #{self.class} (#{event})  XXXXX no events defined in @_events. Please do so to avoid bugs and debugging. This will become a fatal error soon."
+      end
+      @handler ||= {}
+      @event_args ||= {}
+      @handler[event] ||= []
+      @handler[event] << blk
+      @event_args[event] ||= []
+      @event_args[event] << xargs
+    end # }}}
+
+    ##
+    # fire_handler: Fire all bindings for given event  {{{
+    # e.g. fire_handler :ENTER, self
+    # The first parameter passed to the calling block is either self, or some action event
+    # The second and beyond are any objects you passed when using `bind` or `command`.
+    # Exceptions are caught here itself, or else they prevent objects from updating, usually the error is 
+    # in the block sent in by application, not our error.
+    # TODO: if an object throws a subclass of VetoException we should not catch it and throw it back for 
+    # caller to catch and take care of, such as prevent LEAVE or update etc.
+    def fire_handler event, object
+      $log.debug "inside def fire_handler evt:#{event}, o: #{object.class}"
+      if !@handler.nil?
+        if @_events
+          raise ArgumentError, "fire_handler: #{self.class} does not support this event: #{event}. #{@_events} " if !event? event
+        else
+          $log.debug "fire_handler #{self.class}  XXXXX no events defined in @_events "
+        end
+        ablk = @handler[event]
+        if !ablk.nil?
+          aeve = @event_args[event]
+          ablk.each_with_index do |blk, ix|
+            #$log.debug "#{self} called EventHandler firehander #{@name}, #{event}, obj: #{object},args: #{aeve[ix]}"
+            $log.debug "#{self} called EventHandler firehander #{@name}, #{event}"
+            begin
+              blk.call object,  *aeve[ix]
+            rescue FieldValidationException => fve
+              # added 2011-09-26 1.3.0 so a user raised exception on LEAVE
+              # keeps cursor in same field.
+              raise fve
+              #rescue PropertyVetoException => pve
+              # 2018-03-18 - commented off
+              # added 2011-09-26 1.3.0 so a user raised exception on LEAVE
+              # keeps cursor in same field.
+              #raise pve
+            rescue => ex
+              ## some don't have name
+              # FIXME this should be displayed somewhere. It just goes into log file quietly.
+              $log.error "======= Error ERROR in block event #{self}:  #{event}"
+              $log.error ex
+              $log.error(ex.backtrace.join("\n")) 
+              alert ex.to_s    # added 2018-04-08 - 08:55 so it shows up
+              FFI::NCurses.beep    # doesn't do anything, maybe switched off in preferences
+            end
+          end
+        else
+          # there is no block for this key/event
+          # we must behave exactly as processkey
+          # NOTE this is too risky since then buttons and radio buttons
+          # that don't have any command don;t update,so removing 2011-12-2 
+          #return :UNHANDLED
+          return :NO_BLOCK
+        end # if
+      else
+        # there is no handler
+        # I've done this since list traps ENTER but rarely uses it.
+        # For buttons default, we'd like to trap ENTER even when focus is elsewhere
+        # we must behave exactly as processkey
+        # NOTE this is too risky since then buttons and radio buttons
+        # that don't have any command don;t update,so removing 2011-12-2 
+        #return :UNHANDLED
+        # If caller wants, can return UNHANDLED such as list and ENTER.
+        return :NO_BLOCK
+      end # if
+    end # }}}
+
+    # event? : returns boolean depending on whether this widget has registered the given event {{{
+    def event? eve
+      @_events.include? eve
+    end # }}}
+
+# ActionEvent # {{{
+    # source - as always is the object whose event has been fired
+    # id     - event identifier (seems redundant since we bind events often separately.
+    # event  - is :PRESS
+    # action_command - command string associated with event (such as title of button that changed
+    ActionEvent = Struct.new(:source, :event, :action_command) do
+      # This should always return the most relevant text associated with this object
+      # so the user does not have to go through the source object's documentation.
+      # It should be a user-friendly string 
+      # @return text associated with source (label of button)
+      def text
+        source.text
+      end
+
+      # This is similar to text and can often be just an alias.
+      # However, i am putting this for backward compatibility with programs
+      # that received the object and called it's getvalue. It is better to use text.
+      # @return text associated with source (label of button)
+      def getvalue
+        raise "getvalue in eventhandler. remove if does not happen in 2018"
+        source.getvalue
+      end
+    end # }}}
+  end # module eventh 
+end # module