ncumbra 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca4311543d96466d546a976b01991af75abb649575d862cd6d9c9b94bd7a3833
-  data.tar.gz: 6f56247dc1b5dfd77cb1d8fa0de95b275010ca276906c3ec88ac8119b6df134b
+  metadata.gz: 0f50282711c7933882897af2adccae541d0b52eec92487c4d2ce2dda917a0eee
+  data.tar.gz: fe8fd6c63aa1c4eb16f08b1ae4f6018aea8484429886139b6aebe3c930fbc05d
 SHA512:
-  metadata.gz: 749b3f931e2fbf3fc32176711207edb52f0794082f579b037f942a7e2cb47bdbd3136035faceb395f3f55015a9ec212c6ac7995a0d0e10197932e04e0c1bc4b4
-  data.tar.gz: c0e1e0e7bf83fa0a16f91b26495ffb93823ba614f6216438337beb3ab31958775e79b240aab1277fdab2d03cec6c2279c405a95b811dd2be2b1c527412079374
+  metadata.gz: eb0e57a9cca233e75a136189ad0a428dbc226f99d4c05ff59d92801cbb1cce0494aaad604816c1bc59ba291dab2afd08a7920d986a387a080ae6cdb5ba38a418
+  data.tar.gz: a47df4fad81e54ee99cf340fde0808e5805a1c4dceb214a35f271ab41ca7d3313410ac6be1f76adb979b8709927af0cec1448b470229bf80acb135f56e1ea94f

data/CHANGELOG

@@ -1,3 +1,6 @@
+2018-06-11
+  - for 0.1.4 
+    - Search in multiline widgets
 2018-06-03
   - for 0.1.3 
     - YARD Documentation of attr_property

data/README.md

@@ -11,9 +11,13 @@ This is a stripped version of `canis` gem (ncurses ruby).
  - should be able to use a file or widget from here (in another application) without having to copy too much
  - should be able to understand one file without having to understand entire library
  - should be easy for others to change as per their needs, or copy parts.
+ - many portions of `Widget` and `Form` have been rewritten and simplified.
+
+Documentation is at: https://www.rubydoc.info/gems/ncumbra
 
 
 ## Gem name
+
   The name `umbra` was taken, so had to change the gem name to `ncumbra` but the packages and structure etc remain umbra.
 
 ## Motivation for yet another ncurses library
@@ -22,6 +26,7 @@ This is a stripped version of `canis` gem (ncurses ruby).
  keeping parts as independent as possible. 
 
 ## Future versions
+
  - Ampersand in Label and Button to signify shortcut/mnemonic.
  - combo list
  - 256 colors
@@ -212,6 +217,11 @@ The simplest widget in `Umbra` is the Label. Labels are used for a single line o
     title = Label.new( :text => "Demo of Labels", :row => 0, :col => 0 , :width => FFI::NCurses.COLS-1,
                     :justify => :center, :color_pair => 0)
 
+The next example prints a label on the last line stretching from left to right. It will be used in later examples for printing a message when some event is triggered.
+
+    message_label = Label.new row: -1, col: 0, width: -1, color_pair: CP_CYAN, text: "Messages will come here..."
+
+
 A `mnemonic` and related widget may be associated with a label. This `mnemonic` is a shortcut or hotkey for jumping directly to another which is specified by `related_widget`. The `related_widget` must be a focusable object such as a `Field` or `Listbox`. The `mnemonic` is displayed with bold and underlined attribute since underline may not work on some terminals. The Alt-key is to be pressed to jump directly to the field.
 
 ```ruby
@@ -224,25 +234,28 @@ The `width` has been specified as the size of the current screen. You may use a
 
 Now change the `width` to `-1`. Run the program again and stretch the window's width. What happens ? Negative widths and heights are re-calculated at the time of printing, so a change in width of the screen will immediately reflect in the label's width. A negative value for width or height means that the object must stretch or extend to that row or column from the end. Negative widths are thus relative to the right end of the window. Positive widths are absolute.
 
-The important methods of `Label` are:
+The important properties of `Label` are:
 
 - `text` - may be changed at any time, and will immediately reflect
 - `row`  - vertical position on screen (0 to FFI::NCurses.LINES-1). Can be negative for relative position.
 - `col`  - horizontal position on screen (0 to FFI::NCurses.COLS-1)
 - `width` - defaults to length of `text` but can be larger or smaller. Can be negative.
-- `color_pair` - see details for creating colors.
+- `color_pair` - see details for creating colors. e.g. `CP_GREEN` `CP_CYAN` `CP_MAGENTA`, etc.
 - `attr` : maybe `BOLD` , `NORMAL` , `REVERSE` or `UNDERLINE`
 - `justify` - `:right`, `:left` or `:center`
 - `related_widget` - editable or focusable widget associated with this label.
 - `mnemonic` - short-cut used to shift access to `related_widget`
-- `print_label` - override the usual printing of a label. A label usually prints in one colour and attribute (or combination of attributes. However, for any customized printing of a label, one can override this method at the instance level.
+
+Label also has the following method/s:
+
+- `print_label` - override the usual printing of a label. A label usually prints in one colour and attribute (or combination of attributes). However, for any customized printing of a label, one can override this method at the instance level. For an example of customized printing, see examples/extab3.rb.
 
 ### Field
 
 This is an entry field. Text may be edited in a `Field`. Various validations are possible. Custom validations may be specified. 
 
 ```ruby
-    w = Field.new( :name => "name", :row => 1, :col => 1 , :width => 50)
+    w = Field.new( name: "name", row: 1, col: 1, width: 50)
     w.color_pair = CP_CYAN
     w.attr = FFI::NCurses::A_REVERSE
     w.highlight_color_pair = CP_YELLOW
@@ -253,7 +266,7 @@ This is an entry field. Text may be edited in a `Field`. Various validations are
 The above example shows creation of an editable field. The field has been further customized to have a different color when it is in focus (highlighted).
 
 
-Other customizations of field are as follows:
+Other examples of customizations of field are as follows:
 ```ruby
   w.chars_allowed = /[\w\+\.\@]/
   email.valid_regex = /\w+\@\w+\.\w+/
@@ -411,10 +424,8 @@ It adds the following properties to ToggleButton.
 `value` may be used to set the initial value, or retrieve the value at any time.
 
 ```ruby
-    row = 10
-    col = 10
-    check =  Checkbox.new text: "No Frames", value: true,  row: row+1, col: col, mnemonic: "N"
-    check1 = Checkbox.new text: "Use https", value: false, row: row+2, col: col, mnemonic: "U"
+    check =  Checkbox.new text: "No Frames", value: true,  row: 11, col: 10, mnemonic: "N"
+    check1 = Checkbox.new text: "Use https", value: false, row: 12, col: 10, mnemonic: "U"
 ```
 
 A code block may be attached to the clicking of checkboxes either using `command` or binding to `:PRESS`.
@@ -440,8 +451,8 @@ The above is similar to:
 
 ### RadioButton
 
-A +ToggleButton+ button that may have an on or off value. Usually, several related radio buttons are created and only one may be +on+.
-Here, we create a +ButtonGroup+ and then `add` radio buttons to it. 
+A `ToggleButton` button that may have an on or off value. Usually, several related radio buttons are created and only one may be _on_.
+Here, we create a `ButtonGroup` and then `add` radio buttons to it. 
 
 ```ruby
 radio1 = RadioButton.new text: "Red", value: "R", row: 5, col: 20
@@ -470,13 +481,13 @@ A ButtonGroup is a collection of RadioButtons.
 
 Methods:
 
-- `add` - add a +RadioButton+ to the group.
+- `add` - add a `RadioButton` to the group.
 - `selection` - return the button that is selected
 - `value` - get the value of the selected button
 - `select?` - ask if given button is selected
-- `select` - select the given button
 - `elements` - get an array of buttons added
 - `command` - supply a block to be called whenever a button in the group is clicked.
+- `select` - select the given button (simulate keypress programmatically)
 
 
 ```ruby
@@ -530,8 +541,8 @@ The `:CHANGED` event is fired whenever an array is passed to the `list=` method.
 
    In addition to arrow keys, one may use "j" and "k" for down and up. Other keys are:
 
-   - "g" - first row
-   - "G" - last row
+   - g - first row
+   - G - last row
    - C-d - scroll down
    - C-u - scroll up
    - C-b - scroll backward
@@ -786,7 +797,7 @@ An object's `bind_event` is used to attach a code block to an event.
 
 ### Key Bindings
 
-For an object, or for the form, keys may be bound to a code block. All functionality in the system is bound to a code block, making it possible to override provided behavior, although that is not recommended. Tab, backtab and Escape may not be over-ridden.
+For an object, or for the form, keys may be bound to a code block. All functionality in this library is bound to a code block, making it possible to override provided behavior, although that is not recommended. Tab, backtab and Escape may not be over-ridden.
 
     form.bind_key(KEY_F1, "Help") { help() }
 
@@ -794,11 +805,20 @@ For an object, or for the form, keys may be bound to a code block. All functiona
 
     list.bind_key(FFI::NCurses::KEY_CTRL_A, 'cursor home')  { cursor_home }
 
+One may bind Control, Alt, Function and Shifted-Function keys in Umbra. However, multiple keys as in vim or emacs may not be bound. If you require mapping key combinations such as "gg" or "Ctrl-x x" then you should look at the canis gem.
+You may also map the first key to a method that takes a second key. In such cases, it is better to popup a menu so the user knows that a second key is pending.
+
+(Note: TAB and BACKTAB are hardcoded in form.rb for traversal, ESCAPE is hardcoded in field.rb. If a widget does not consume the ARROW keys, they may also be used for traversal by form.rb)
 
 ## More examples
 
  See examples directory for code samples for all widgets. Be sure the run all the examples to see the capabilities of the library and the widgets.
 
+## Testing
+
+I have not found a way of automated testing for ncurses applications. Suggestions are welcome.
+My way is of manually testing which is cumbersome, and that discourages rewrites, refactoring, etc.
+
 ## Contributing
 
 Please go through the source, and suggest improvements to the design and code.

data/lib/umbra.rb

@@ -64,6 +64,26 @@ module Umbra
     m.run
   end
 
+  def get_string label, config={}
+    require 'umbra/messagebox'
+    config[:title]             ||= "Entry"
+    config[:buttons]           ||= ["Ok", "Cancel"]
+    fld = nil
+    mb = MessageBox.new config do 
+      add Label.new text: label, row: 2, col: 2
+      fld = Field.new name: "field", row: 3, col: 2
+      add fld
+    end
+    index = mb.run
+    if index == 0
+      return fld.text
+    else
+      return nil
+    end
+  end
+    
+
+
   ## create a logger instance given a path, return the logger
   ## NOTE: Ideally would like to set $log here to this, but what if user creates multiple.
   def create_logger path, config={}

data/lib/umbra/box.rb

@@ -4,15 +4,17 @@
 #       Author: j kepler  http://github.com/mare-imbrium/canis/
 #         Date: 2018-04-07
 #      License: MIT
-#  Last update: 2018-06-02 19:01
+#  Last update: 2018-06-03 14:50
 # ----------------------------------------------------------------------------- #
 #  box.rb  Copyright (C) 2018 j kepler
 module Umbra
   ##
   # A box is a container around one, or more, widgets.
-  # Properties include #visible, #justify and #title.
+  # Properties include `visible,` `justify` and `title.`
+  # It is not focusable, so no keys can be mapped to it.
+  #
   ## FIXME box needs to resize components if it's dimensions are changed.
-  ##  Or should components have a link to parent, so they can resize themselves ?
+  ## Or should components have a link to parent, so they can resize themselves ?
   #
   class Box < Widget 
     # @param title [String] set and return title of box
@@ -127,9 +129,10 @@ module Umbra
       @widget = w
     end
 
-    ## paint a horizontal line, as a separator between widgets
-    ## param [Integer] row - row
-    ## param [Integer] col - column
+    ## Paint a horizontal line, as a separator between widgets
+    ## Called by `repaint`.
+    ## @param row [Integer] row
+    ## @param col [Integer] column
     def hline row, col
       return if row >= self.row + self.height
       $log.debug "  hline: #{row} ... #{@row}   #{@height}  "

data/lib/umbra/listbox.rb

@@ -5,7 +5,7 @@ require 'umbra/multiline'
 #       Author: j kepler  http://github.com/mare-imbrium/umbra
 #         Date: 2018-03-19 
 #      License: MIT
-#  Last update: 2018-06-03 10:39
+#  Last update: 2018-06-07 09:35
 # ----------------------------------------------------------------------------- #
 #  listbox.rb  Copyright (C) 2012-2018 j kepler
 #  == TODO 
@@ -46,6 +46,7 @@ module Umbra
       #register_events([:LIST_SELECTION_EVENT])
       register_events([:SELECT_ROW])
       super
+      @search_offset      = 1                  # search has offset of 1, due to added mark
     end
 
 

data/lib/umbra/multiline.rb

@@ -6,11 +6,10 @@ require 'umbra/widget'
 #       Author: j kepler  http://github.com/mare-imbrium/canis/
 #         Date: 2018-05-08 - 11:54
 #      License: MIT
-#  Last update: 2018-06-01 14:36
+#  Last update: 2018-06-10 10:50
 # ----------------------------------------------------------------------------- #
 #  multiline.rb Copyright (C) 2012-2018 j kepler
 #
-##  TODO search through text and put cursor on next result.
 ##  TODO allow setting of current_index programmatically
 ##  TODO is a row visible. visible? row. and make a row visible. programmatically
 ##  TODO insert delete a row (if editable)
@@ -26,6 +25,9 @@ module Umbra
 
     attr_reader   :list                        # array containing data (usually Strings)
     attr_reader   :panned_cols                 ## How may columns has widget panned to right
+    ## adjustment for searching for a pattern in a line, if adding text to start of string.
+    ## Example, listbox adds one char to start. One may override and add two.
+    attr_accessor  :search_offset              
 
     # index of focussed row, starting 0, index into the list supplied
     attr_reader   :current_index
@@ -35,6 +37,7 @@ module Umbra
       @editable           = false
       @pstart             = 0                  # which row does printing start from
       @current_index      = 0                  # index of row on which cursor is
+      @search_offset      = 0                  # search has no offset
 
       ## PRESS event relates to pressing RETURN/ENTER (10)
       register_events([:LEAVE_ROW, :ENTER_ROW, :PRESS])
@@ -277,6 +280,8 @@ module Umbra
       ## C-h was not working, so trying C-j
       bind_key(FFI::NCurses::KEY_CTRL_J, 'scroll_left')  { scroll_left }
       bind_key(FFI::NCurses::KEY_CTRL_L, 'scroll_right')  { scroll_right }
+      bind_key(?/, 'ask search')                         { ask_search }
+      bind_key(?n, 'next match ')                        { find_more }
       @keys_mapped = true
     end
 
@@ -514,12 +519,103 @@ module Umbra
       @current_index = line
       ensure_visible line
     end
+    #def each_line
+      #@list.each_with_index do |line, ix|
+        #line = self.value_of_row( line, ix, :NONE)
+        #yield line
+      #end
+    #end
+
+    ## Ask user for a pattern to look for in lines.
+    ## Put cursor on first match.
+    def ask_search
+      str = get_string("Search:")
+      return unless str
+      ix = next_match str
+      if ix
+        @current_index, @curpos = ix
+        set_col_offset @curpos   ## why do we need to do this also
+        $log.debug "  ask_search ci: #{@current_index}  , #{@curpos} "
+        @last_regex = str
+      else
+        alert "Pattern not found: #{str}"
+      end
+    end
+
+    ## find more occurrences of match. This is bound to 'n' key.
+    def find_more
+      return unless @last_regex
+      str = @last_regex
+      $log.debug "  FIND MORE last_regex is : #{@last_regex} "
+      ix = next_match @last_regex
+      #return unless ix
+      if ix
+        @current_index, @curpos = ix
+        set_col_offset @curpos   ## why do we need to do this also
+      else
+        alert "No more matches for: #{str}"
+      end
+    end
+
+    ## find the first or next occurrence of a pattern
+    ## @param str [String] pattern to match
+    ## @param startline [Integer] line to start search on
+    ## @param curpos [Integer] cursor position to start search on
+    ## @param endline [Integer] line to end search on
+    def next_match str, startline = nil,  _curpos = nil, endline = nil
+      return unless str
+
+      ## check current line for more occurrences.
+      if !startline
+        startline = @current_index
+        _curpos ||= (@curpos + 1) # FIXME +1 should only happen if a search has already happened
+        #_pos = @list[startline].index(str, _curpos)
+        _pos = to_searchable(startline).index(str, _curpos)
+        return [startline, _pos + search_offset] if _pos
+        startline += 1
+      end
+      ## Check rest of file
+      ## loop through array, check after startline to eof
+      @list.each_with_index do | line, ix|
+        next if ix < startline
+        break if endline && ix > endline
+        #_found = line.index(str)
+        _found = to_searchable(ix).index(str)
+        #$log.debug "  next_match: #{line}: #{_found}  " if _found
+        return [ix, _found + search_offset] if _found
+      end
+      if startline > 0
+        # this can get called again since startline was made 1 in above block. FIXME
+        #return next_match str, 0, @current_index
+      end
+      return nil
+    end
+
+
+    ## This needs to be overridden in case of lists that contain something other than 
+    ## `String` as their elements. In such a case, `search_offset` may need to be adjusted also.
+    ## @param index [Integer] offset of row in list
+    ## @return [String] searchable representation of list element at `index`
+    def to_searchable index
+      s = @list[index]
+      case s
+      when String
+        return s                                       ## return the string as is.
+      when Array
+                                                       ## may need to be overridden by caller
+        return s.join(" ")
+      else
+        raise "Don't know how to handle this datatype, please override to_searchable"
+      end
+    end
+
 
     ## UNTESTED
     def delete_at index
       return unless @list
       return unless @editable
-      @repaint_all = true
+      #@repaint_all = true
+      @repaint_required = true
       @list.delete_at index
     end
 
@@ -527,7 +623,8 @@ module Umbra
     def insert index, line
       return unless @list
       return unless @editable
-      @repaint_all = true
+      #@repaint_all = true
+      @repaint_required = true
       @list.insert index, line
     end
 

data/lib/umbra/table.rb

@@ -4,28 +4,29 @@
 #       Author: j kepler  http://github.com/mare-imbrium/umbra/
 #         Date: 2018-05-06 - 09:56
 #      License: MIT
-#  Last update: 2018-05-22 14:46
+#  Last update: 2018-06-03 14:43
 # ----------------------------------------------------------------------------- #
 #  table.rb  Copyright (C) 2018 j kepler
 
-##--------- Todo section ---------------
-## DONE w - next column, b - previous column
-## TODO paint lines as column separators. issue is panning.
-## TODO starting visual column (required when scrolling)
-## DONE change a value value_at(x,y, value) ; << ; delete_at 
-## TODO change column width interactively, hide column , move column
-## TODO maybe even column_color(n, color_pair, attr)
-## TODO sort on column/s.
-## TODO selection will have to be added. maybe we should have extended listbox after all. Or made multiline selectable.
-## DONE how to format the header
-## DONE formatting rows
-## DONE if we want to color specific columns based on values then I think we have to format (render) the row at the last 
+=begin
+## --------- Todo section ---------------
+## - TODO paint lines as column separators. issue is panning.
+## - TODO starting visual column (required when scrolling)
+## - DONE change a value value_at(x,y, value) ; << ; delete_at 
+## - TODO change column width interactively, hide column , move column
+## - TODO maybe even column_color(n, color_pair, attr)
+## - TODO sort on column/s.
+## - TODO selection will have to be added. maybe we should have extended listbox after all. Or made multiline selectable.
+## - DONE how to format the header
+## - DONE formatting rows
+## - DONE if we want to color specific columns based on values then I think we have to format (render) the row at the last 
 ##      moment in print_row and not in advance
-## NOTE: we are setting the data in tabular, not list. So calling list() will give nil until a render has happened.
+## - NOTE: we are setting the data in tabular, not list. So calling list() will give nil until a render has happened.
 ##     callers will have to use data() instead of list() which is not consistent.
-## NOTE: current_index in this object refers to index including header and separator. It is not the offset in the data array.
+## - NOTE: current_index in this object refers to index including header and separator. It is not the offset in the data array.
 ##    For that we need to adjust with @data_offset.
-#
+=end
+
 require 'forwardable'
 require 'umbra/tabular'
 require 'umbra/multiline'

data/lib/umbra/version.rb

@@ -1,3 +1,3 @@
 module Umbra
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ncumbra
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - kepler
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-03 00:00:00.000000000 Z
+date: 2018-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -137,7 +137,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
 summary: tiny ncurses library for creating simple apps. Stripped version of Canis.