canis 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 816492c76956497f6216f58530ac662a8914f404
-  data.tar.gz: 81030d5970df8c6ada548ad6a5cbe1782d8c2f16
+  metadata.gz: d5a775dee6fbf1b0f9bc371c1e11ec5822241396
+  data.tar.gz: ac9799e0d5419870a54b30f388b0e56984def45e
 SHA512:
-  metadata.gz: 6a2294dabd5cd4b38db99ca783c7b3d2005dd9c3b3cb2823c4d284cf60d88f503f870cca06b9596224696a4e70f611417a9e29a341f862921df3e07497face81
-  data.tar.gz: 6510464a766ee936761d32fbbaef6e2d9ed21f3e81d7425956f7d45de5dd2d5b1797cfd71c8799f1499187917f1d8a4c971ab8c0de88d777f134ed00730873f5
+  metadata.gz: f261dc96bb4b87476193966e16cbf8c417de1cd49f4b4e99a173837045ea527dc6e503916c06a868c2e9598fa981c30eaf7f749b58c7d730e5c4e2c06fb1aa3a
+  data.tar.gz: 992fe5d6546ece188d6b5599a03d94b6f3b35e86fb40e878dcda350107a389f51edd31929a522546a3d3ac6fd26ea263d194f766eb64fe14aba61be2f96f956b

data/CHANGES

@@ -50,3 +50,8 @@ Built 0.0.2 but i did not release it.
     This way an app can have its own logger and not bother about canis' logging.
     Or it can merge the two.
   - Moved helpmanager from rwidgets to its own file. Needs to be refactored and cleaned up.
+
+2014-08-18 - 17:11 
+- for 0.0.5
+  - fixed a bug in handling of multiple key assignments due to which extra keys pushed onto stack
+  - App keyblock yields string of key without changing or converting to symbol

data/examples/testkeypress.rb

@@ -62,7 +62,7 @@ if $0 == __FILE__
         str = keycode_tos ch if ch.is_a? Fixnum
         #str1 = @window.key_tos ch if ch.is_a? Fixnum
         str1 = $key_chr
-        $log.debug  "#{ch} got (#{str} #{str1})"
+        $log.debug  "#{ch} got (#{str} $key_chr:#{str1})"
         texta << "#{ch} got (#{str}) #{str1}"
         if ch == 99999
           name = get_string "Add a name for #{$key_chr}?"

data/lib/canis/core/include/appmethods.rb

@@ -28,6 +28,9 @@ module Canis
     # Maybe not be able to get your prompt correctly.
     # 
     public
+    #
+    # suspends current program and puts user on unix prompt
+    #
     def suspend
       _suspend(false) do
         system("tput cup 26 0")
@@ -70,6 +73,10 @@ module Canis
       # Earlier close key was ENTER but we need that to execute or fire
       Canis::Viewer.view(res.split("\n"), :close_key => 'q', :title => "<q> to close, M-l M-h to scroll")
     end
+    #
+    # takes a unix command (system) and executes the same. No output
+    # @return return value of system command
+    # 
     def shell_out command
       w = @window || @form.window
       w.hide

data/lib/canis/core/system/colormap.rb

@@ -1,5 +1,20 @@
 require 'canis/core/system/ncurses'
 
+# 2014-08-11 - 09:54 
+# There is a limit to the number of color pairs one can make 0 .. COLOR_PAIRS - 1
+# which i why i get junk colors after 255. In my program, color_pairs is 32767 ???
+#
+# curses.init_pair(pair_number, fg, bg)
+# 
+ #    Change the definition of a color-pair. It takes three arguments: the
+# number of the color-pair to be changed, the foreground color number, and the
+# background color number. The value of pair_number must be between 1 and
+# COLOR_PAIRS - 1 (the 0 color pair is wired to white on black and cannot be
+# changed). The value of fg and bg arguments must be between 0 and COLORS. If the
+# color-pair was previously initialized, the screen is refreshed and all
+# occurrences of that color-pair are changed to the new definition.
+#   - https://docs.python.org/2/library/curses.html
+
 module Canis
   module ColorMap
     # 2010-09-20 12:22 changed colors from string to symbol
@@ -17,6 +32,8 @@ module Canis
     def ColorMap.install_color fgc, bgc
       #$log.debug " install_color found #{fgc} #{@bgc} "
       @color_id += 1
+      # testing to see, since i get junk after 255 or so
+      #@color_id = 255 if @color_id > 255
       fg = ColorMap.get_color_const fgc
       bg = ColorMap.get_color_const bgc
       FFI::NCurses.init_pair(@color_id, fg, bg);
@@ -93,6 +110,13 @@ module Canis
 
       #    $log.debug " colormap SETUP: #{$datacolor} #{$reversecolor} "
     end
+    # reset the color_id to zero so one can create colors from scratch.
+    # This is only to be used in the case of a color demo when you don't want the colors
+    #  we originally made, since there seems to be a shortage of slots.
+    def ColorMap.reset_color_id
+      @color_id = 0
+      $color_map = {}
+    end
 
   end # modul
   if $0 == __FILE__

data/lib/canis/core/system/window.rb

@@ -4,7 +4,7 @@
 #       Author: jkepler http://github.com/mare-imbrium/canis/
 #         Date: Around for a long time
 #      License: Same as Ruby's License (http://www.ruby-lang.org/LICENSE.txt)
-#  Last update: 2014-07-10 00:13
+#  Last update: 2014-08-15 12:12
 #
 #  == CHANGED
 #     removed dead or redudant code - 2014-04-22 - 12:53 
@@ -18,16 +18,6 @@
 #
 require 'canis/core/system/ncurses'
 require 'canis/core/system/panel'
-# this is since often windows are declared with 0 height or width and this causes
-# crashes in the most unlikely places. This prevceents me from having to write ternary
-# e.g.
-#     @layout[:width].ifzero(FFI::NCurses::LINES-2)
-class Fixnum
-  def ifzero v
-    return self if self != 0
-    return v
-  end
-end
 # This class is to be extended so that it can be called by anyone wanting to implement
 # chunks ot text with color and attributes. Chunkline consists of multiple chunks of colored text
 # and should implement a +each_with_color+.
@@ -36,21 +26,51 @@ end
 class AbstractChunkLine; end
 
 module Canis
+  # A Basic class of this library, all output is eventually done on a window.
+  # Root windows and dialogs use this class.
+  # A root window covers the entire screen, and is the basis of an application usually.
+  # 
+  # == Examples
+  #
+  #    w = Canis::Window.root_window
+  #
+  #    w = Canis::Window.create_window( ht, wid, top, left)
+  #    
+  #    w = Canis::Window.new( ht, wid, top, left)
+  #
+  #    layout = { :height => ht, :width => w, :top => t, :left => l }
+  #    w = Canis::Window.new( layout )
+  #
+  # == Commonly used methods
+  #
+  #  - destroy
+  #  - printstring
+  #  - wrefresh
+  #  - getchar
+  #  - print_border
+  #
   class Window 
+    # dimensions of window
     attr_reader :width, :height, :top, :left
+    # hash containing dimensions
     attr_accessor :layout # hash containing hwtl
+    # panel related to window, used to delete it in the end
     attr_reader   :panel   # reader requires so he can del it in end
     attr_accessor :name  # more for debugging log files. 2010-02-02 19:58 
     #attr_accessor :modified # has it been modified and may need a refresh 2014-04-22 - 10:23 CLEANUP
+    #
     # for root windows we need to know the form so we can ask it to update when
     #   there are overlapping windows.
     attr_accessor :form
 
-    # creation and layout related {{{
+    # window init {{{
+    # creation and layout related.
     # @param [Array, Hash] window coordinates (ht, w, top, left)
+    #
     # or 
+    #
     # @param [int, int, int, int] window coordinates (ht, w, top, left)
-    # 2011-09-21 allowing array, or 4 ints,  in addition to hash @since 1.3.1
+    #
     def initialize(*args)
 
       case args.size
@@ -109,7 +129,8 @@ module Canis
       $catch_alt_digits ||= false # is this where is should put globals ? 2010-03-14 14:00 XXX
     end
     ##
-    # this is an alternative constructor
+    # this is an alternative constructor, which by default creates a window that covers the entire
+    # screen
     def self.root_window(layout = { :height => 0, :width => 0, :top => 0, :left => 0 })
     
       @layout = layout
@@ -131,6 +152,11 @@ module Canis
     # NOTE : if there are too many root windows, this could get expensive since we are updating all.
     # We may need to have a way to specify which window to repaint.
     #  If there are non-root windows above, we may have manually refresh only the previous one.
+    # FIXME NOTE current our examples have lists and textpads that cover the root window so the 
+    #  refresh all is fine, but if there is screen area vacant then that will still be left black
+    #  Similarly in the case of a dialog below, the window and box will not be painted.
+    # We may need a key for refreshing the entire window, such as ^L in which the form and the window
+    #  is repainted.
     #
     def self.refresh_all current_win=nil
       #Ncurses.touchwin(FFI::NCurses.stdscr)
@@ -220,7 +246,9 @@ module Canis
     def wrefresh
       Ncurses.wrefresh(@window)
     end
-    def delwin # 2011-09-7 
+    #
+    # called by destroy()
+    def delwin 
       Ncurses.delwin(@window)
     end
     def attron *args
@@ -251,6 +279,8 @@ module Canis
     #end
     # since include FFI is taking over, i need to force it here. not going into
     # method_missing
+
+    # move window to row and col
     def wmove y,x
       #Ncurses.wmove @window, y, x
       FFI::NCurses.wmove @window, y, x
@@ -366,6 +396,7 @@ module Canis
 
     # Ncurses panel
 
+    # hide the window
     def hide
       #return unless visible? # added 2011-10-14 these 2 are not behaving properly
       Ncurses::Panel.hide_panel @panel.pointer
@@ -374,6 +405,7 @@ module Canis
       @visible = false
     end
 
+    # show the window
     def show
       #return if visible? # added 2011-10-14 these 2 are not behaving properly
       Ncurses::Panel.show_panel @panel.pointer
@@ -413,7 +445,6 @@ module Canis
     end
 
     # 
-    # 2011-11-13 since 1.4.1
     # Widgets can get window to create a pad for them. This way when the window
     #  is destroyed, it will delete all the pads. A widget wold not be able to do this.
     # The destroy method of the widget will be called.
@@ -680,6 +711,7 @@ module Canis
     #           take some actions
     #        end
     #    end
+    # @see +command+ (alias)
     def close_command *args, &block
       @close_command ||= []
       @close_args ||= []
@@ -743,7 +775,7 @@ module Canis
   class DefaultKeyReader # --- {{{
     def initialize win
       @window = win
-      @stack = []
+      #@stack = []
     end
 
     # return an int for the key read. this is just a single int, and is not interpreted

data/lib/canis/core/util/app.rb

@@ -120,6 +120,9 @@ module Canis
       end
       $log.debug " CLOSING APP"
     end
+
+    # This method is called by run, and thus in most cases this is what is used.
+    # +run+ calls this without a block
     # not sure, but user shuld be able to trap keystrokes if he wants
     # but do i still call handle_key if he does, or give him total control.
     # But loop is already called by framework
@@ -142,9 +145,17 @@ module Canis
               break
             end
 
+            # execute a code block so caller program can handle keys from a hash or whatever.
+            # Currently this has the issue that the key is still evaluated again in the next block
+            # - A double evaluation can happen
+            # - these keys will not appear in help
+            # FIXME
             if @keyblock
               str = keycode_tos ch
-              @keyblock.call(str.gsub(/-/, "_").to_sym) # not used ever
+              # why did we ever want to convert to a symbol. why not just pass it as is.
+              #@keyblock.call(str.gsub(/-/, "_").to_sym) # not used ever
+              ret = @keyblock.call(str) 
+              @form.repaint if ret
             end
 
             yield ch if block # <<<----
@@ -191,6 +202,9 @@ module Canis
     # returns a symbol of the key pressed
     # e.g. :C_c for Ctrl-C
     # :Space, :bs, :M_d etc
+    # NOTE 2014-08-15  Trying with just string returned by keycode_tos
+    # This should allow for simpler apps that want to handle keys perhaps taken from a config file
+    #  rather than bind each key manually.
     def keypress &block
      @keyblock = block
     end
@@ -198,7 +212,6 @@ module Canis
     # a label so it can be printed.
     def message text
       $status_message.value = text # trying out 2011-10-9 
-      #@message.value = text # 2011-10-17 14:07:01
     end
 
     # used only by LiveConsole, if enables in an app, usually only during testing.
@@ -366,17 +379,6 @@ module Canis
       #colorlabel = Label.new @form, {'text' => "Select a color:", "row" => row, "col" => col, "color"=>"cyan", "mnemonic" => 'S'}
     alias :text :label
     
-    # print a title on first row -- this is so bad, not even a label
-    def title string, config={}
-      raise "don't use DELETE dead code"
-      ## TODO center it
-      @window.printstring 1, 30, string, $normalcolor, 'reverse'
-    end
-    # print a sutitle on second row, center and use a label, if this is even used.
-    def subtitle string, config={}
-      raise "don't use DELETE"
-      @window.printstring 2, 30, string, $datacolor, 'normal'
-    end
     # menu bar
 
     # displays a horizontal line
@@ -446,6 +448,7 @@ module Canis
       matches = opts.grep Regexp.new("^#{cmd}")
     end
 
+    # This is the method that is called by all apps usually that define an App block
     def run &block
       begin
 

data/lib/canis/core/util/extras/padreader.rb

@@ -4,7 +4,7 @@
   * Author: jkepler (http://github.com/mare-imbrium/canis/)
   * Date: 22.10.11 - 20:35
   * License: Same as Ruby's License (http://www.ruby-lang.org/LICENSE.txt)
-  * Last update:  2013-04-01 13:43
+  * Last update:  2014-08-09 20:25
 
   == CHANGES
   == TODO 
@@ -14,6 +14,17 @@
      NOTE: I have continued this in textpad which is a widget that uses pads to scroll.
            This is very rough, i may work on this more later.
 =end
+# this is since often windows are declared with 0 height or width and this causes
+# crashes in the most unlikely places. This prevceents me from having to write ternary
+# e.g.
+#     @layout[:width].ifzero(FFI::NCurses::LINES-2)
+class Fixnum
+  def ifzero v
+    return self if self != 0
+    return v
+  end
+end
+
 require 'canis'
 
 include Canis

data/lib/canis/core/util/promptmenu.rb

@@ -5,7 +5,7 @@
 #       Author: j kepler  http://github.com/mare-imbrium/canis/
 #         Date: 2014-04-25 - 12:32
 #      License: MIT
-#  Last update: 2014-04-27 00:10
+#  Last update: 2014-08-09 18:55
 # ----------------------------------------------------------------------------- #
 #  promptmenu.rb  Copyright (C) 2012-2014 j kepler
 #  Depends on rcommandwindow for display_menu
@@ -42,6 +42,7 @@ module Canis
   # and the rest are ordinary characters.
   # 
   #  == Example
+  #
   #    menu = PromptMenu.new self do
   #      item :s, :goto_start
   #      item :b, :goto_bottom

data/lib/canis/core/util/rdialogs.rb

@@ -358,18 +358,33 @@ class StatusWindow # --- {{{
 end # }}}
 # returns instance of a status_window for sending multiple
 # statuses during some process
+# TODO FIXME block got ignored
 def status_window aconfig={}, &block
-  return StatusWindow.new aconfig
+  sw = StatusWindow.new aconfig
+  return sw unless block_given?
+  begin
+    yield sw
+  ensure
+    sw.destroy if sw
+  end
 end
 # this is a popup dialog box on which statuses can be printed as a process is taking place.
 # I am reusing StatusWindow and so there's an issue since I've put a box, so in clearing 
 # the line, I might overwrite the box
 def progress_dialog aconfig={}, &block
   aconfig[:layout] = [10,60,10,20]
+  # since we are printing a border
+  aconfig[:row_offset] ||= 4
+  aconfig[:col_offset] ||= 5
   window = status_window aconfig
   height = 10; width = 60
   window.win.print_border_mb 1,2, height, width, $normalcolor, FFI::NCurses::A_REVERSE
-  return window
+  return window unless block_given?
+  begin
+    yield window
+  ensure
+    window.destroy if window
+  end
 end
 # 
 # Display a popup and return the seliected index from list

data/lib/canis/core/widgets/applicationheader.rb

@@ -8,7 +8,7 @@
 #       Author: jkepler http://github.com/mare-imbrium/canis-core/
 #         Date: 
 #      License: Same as Ruby's License (http://www.ruby-lang.org/LICENSE.txt)
-#  Last update: 2011-11-16 - 00:07
+#  Last update: 2014-08-10 14:53
 #
 #  CHANGES:
 #              For some terminals, like xterm-256color which were not printing spaces
@@ -19,13 +19,27 @@
 require 'canis/core/widgets/rwidget'
 include Canis
 module Canis
+  # Maintain an application header on the top of an application.
+  # Application related text may be placed in the left, center or right slots.
+  #
+  # == Example
+  # a = ApplicationHeader.new "MyApp v1.0", :text_center => "Application Name", :text_right => "module",
+  #    :color => :white, :bgcolor => :blue
+  #
+  # # Later as user traverses a list or table, update row number on app header
+  # a.text_right "Row #{n}"
+  #
   class ApplicationHeader < Widget
+    # text on left of header
     dsl_property :text1
+    # text on left of header, after text1
     dsl_property :text2
+    # text in center of header
     dsl_property :text_center
+    # text on right side of header
     dsl_property :text_right
 
-
+    # @param text1 String text on left of header
     def initialize form, text1, config={}, &block
 
       @name = "header"
@@ -47,6 +61,7 @@ module Canis
       @text_center ||= ""
       @text_right ||= ""
     end
+    # returns value of text1, i.e. text on left of header
     def getvalue
       @text1
     end
@@ -56,6 +71,8 @@ module Canis
     def repaint
       return unless @repaint_required
  
+      # 2014-08-10 - 14:53 changing bgcolor or color resets color_pair, so this must be reset if nil
+      @color_pair ||= get_color $bottomcolor, @color, @bgcolor
       #print_header(htext, posy = 0, posx = 0)
       att = get_attrib @attr
       len = @window.width
@@ -73,6 +90,7 @@ module Canis
       print_top_right(@text_right)
       @repaint_required = false
     end
+    # internal method, called by repain to print text1 and text2 on left side
     def print_header(htext, r = 0, c = 0)
       #win = @window
       #len = @window.width
@@ -81,6 +99,7 @@ module Canis
       #@form.window.printstring r, c, "%-*s" % [len, htext], @color_pair, @attr
       @form.window.printstring r, c, htext, @color_pair, @attr
     end
+    # internal method, called by repaint to print text_center in the center
     def print_center(htext, r = 0, c = 0)
       win = @window
       len = win.getmaxx
@@ -89,6 +108,7 @@ module Canis
       #@form.window.printstring r, c, "%-*s" % [len, htext], @color_pair, @attr
       win.printstring r, ((len-htext.length)/2).floor, htext, @color_pair, @attr
     end
+    # internal method to print text_right
     def print_top_right(htext)
       hlen = htext.length
       len = @window.getmaxx # width was not changing when resize happens

data/lib/canis/core/widgets/rwidget.rb

@@ -9,7 +9,7 @@
   * Author: jkepler (ABCD)
   * Date: 2008-11-19 12:49 
   * License: Same as Ruby's License (http://www.ruby-lang.org/LICENSE.txt)
-  * Last update: 2014-07-10 00:07
+  * Last update: 2014-08-18 14:58
 
   == CHANGES
   * 2011-10-2 Added PropertyVetoException to rollback changes to property
@@ -576,9 +576,13 @@ module Canis
             $log.debug  " got node #{n} with #{e} "
             # instead of just nil, we need to go back up, but since not recursive ...
             #return nil unless n
-            $log.debug  "push unconsumed:#{unconsumed} " unless n
-            unconsumed.each {|e| window.ungetch(e)} unless n
-            return actions.last unless n
+            unless n
+              # testing shift otherwise it seems current key evaluated twice
+              unconsumed.shift
+              $log.debug  "push unconsumed:#{unconsumed} " unless n
+              unconsumed.each {|e| window.ungetch(e)} unless n
+              return actions.last unless n
+            end
             mp = n.map
             # there are no more keys, only an action
             if mp.nil? or mp.empty?
@@ -766,7 +770,7 @@ module Canis
         # so that if block does not handle, the key can still be handled
         # e.g. table last row, last col does not handle, so it will auto go to next field
         #  2010-02-24 13:45 handles 2 key combinations, copied from Form, must be identical in logic
-        #  except maybe for window pointer. TODO not tested
+        #  except maybe for window pointer. 
         def _process_key keycode, object, window
           return :UNHANDLED if @_key_map.nil?
           chr = nil
@@ -1513,7 +1517,13 @@ module Canis
   end #  }}}
 
   ##
+  # Manages the controls/widgets on a screen. 
+  # Manages traversal, rendering and events of all widgets that are associated with it
+  # via the +add_widget+ method.
   #
+  # Passes keys pressed by user to the current field.
+  # Any keys that are not handled by the current field, are handled by the form if the application
+  # has bound the key via +bind_key+.    
   # TODO: we don't have an event for when form is entered and exited.
   class Form # {{{
     include EventHandler
@@ -1872,7 +1882,10 @@ module Canis
       end
       f = @widgets[@active_index]
       index = @focusables.index(f)
-      index += 1
+      # 2014-08-09 - 13:09 f may be status_line esp if ai is -1, so it is not found in focusables
+      # why are we first checking widgets and then focusables.
+      #index += 1
+      index = index ? index+1 : 0
       f = @focusables[index]
       if f
         select_field f 
@@ -2118,8 +2131,7 @@ module Canis
           $log.debug " form RESIZE HK #{ch} #{self}, #{@name} "
           repaint_all_widgets
           return
-        #when Ncurses::KEY_RESIZE # SIGWINCH
-        when FFI::NCurses::KEY_RESIZE # SIGWINCH #  FFI
+        when FFI::NCurses::KEY_RESIZE # SIGWINCH 
           lines = Ncurses.LINES
           cols = Ncurses.COLS
           x = Ncurses.stdscr.getmaxy

data/lib/canis/core/widgets/statusline.rb

@@ -4,8 +4,15 @@ module Canis
 
   #
   # A vim-like application status bar that can display time and various other statuses
-  #  at the bottom, typically above the dock (3rd line from last).
+  #  at the bottom, typically above the dock (3rd line from last), or else the last line.
   #
+  # == Example
+  #
+  #    require 'canis/core/widgets/statusline'
+  #    @status_line = Canis::StatusLine.new @form, :row => Ncurses.LINES-2
+  #    @status_line.command {
+  #       "F1 Help | F2 Menu | F3 View | F4 Shell | F5 Sh | %20s" % [message_label.text]
+  #    }
   class StatusLine < Widget
     #attr_accessor :row_relative # lets only advertise this when we've tested it out
 
@@ -36,9 +43,10 @@ module Canis
     #
     # command that returns a string that populates the status line (left aligned)
     # @see :right
-    # See dbdemo.rb
-    # e.g. 
-    #   @l.command { "%-20s [DB: %-s | %-s ]" % [ Time.now, $current_db || "None", $current_table || "----"] }  
+    # @see dbdemo.rb
+    # == Example
+    #
+    #    @l.command { "%-20s [DB: %-s | %-s ]" % [ Time.now, $current_db || "None", $current_table || "----"] }  
     #
     def command *args, &blk
       @command = blk
@@ -47,7 +55,7 @@ module Canis
     alias :left :command
 
     # 
-    # Procudure for text to be right aligned in statusline
+    # Procedure for text to be right aligned in statusline
     def right *args, &blk
       @right_text = blk
       @right_args = args
@@ -105,7 +113,8 @@ module Canis
 
       @repaint_required = false
     end
-    def handle_keys ch
+    # not used since not focusable
+    def handle_keys ch 
       return :UNHANDLED
     end
     

data/lib/canis/version.rb

@@ -1,3 +1,3 @@
 module Canis
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: canis
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - kepler
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-12 00:00:00.000000000 Z
+date: 2014-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler