ncumbra 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6154c2af0ffac0eba6eb146efb61ee935b01b95299f828231e62ece1aa52760b
-  data.tar.gz: bb37af7243be9f5ba18252592a9a1a95b74157e66d5bb07d1ca1c3fd7cdb46fe
+  metadata.gz: ca4311543d96466d546a976b01991af75abb649575d862cd6d9c9b94bd7a3833
+  data.tar.gz: 6f56247dc1b5dfd77cb1d8fa0de95b275010ca276906c3ec88ac8119b6df134b
 SHA512:
-  metadata.gz: cae7cbbc5818c5831f02bf7aa94d44c2912420f2ddb4dea18ff35fc0fff011e557ca5de83fb98e9d950086fa75f01fa160f91eceb02c8b9a118e62dffa72afb2
-  data.tar.gz: 39bf8e78fddcde77125371be0a8b9a71bd70f59c242c2328c54ea1cf26d031218e532f41dacdbfd3fd34d521ee9869d7ffb856bfbf7d3f1b6ef7b0539b16c76f
+  metadata.gz: 749b3f931e2fbf3fc32176711207edb52f0794082f579b037f942a7e2cb47bdbd3136035faceb395f3f55015a9ec212c6ac7995a0d0e10197932e04e0c1bc4b4
+  data.tar.gz: c0e1e0e7bf83fa0a16f91b26495ffb93823ba614f6216438337beb3ab31958775e79b240aab1277fdab2d03cec6c2279c405a95b811dd2be2b1c527412079374

data/CHANGELOG

@@ -1,3 +1,8 @@
+2018-06-03
+  - for 0.1.3 
+    - YARD Documentation of attr_property
+	- Moved ButtonGroup and ItemEvent to module Umbra.
+
 2018-06-01
   - for 0.1.2 
     - much cleaning up and some renaming of methods and properties

data/README.md

@@ -440,8 +440,50 @@ 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. 
 
+```ruby
+radio1 = RadioButton.new text: "Red", value: "R", row: 5, col: 20
+radio2 = RadioButton.new text: "Green", value: "G", row: 6, col: 20
+group = ButtonGroup.new "Color"
+group.add(radio1).add(radio2)
+form.add_widget radio1, radio2
+```
+
+By default, the button prints the selector or box on the left as `( )`. By setting `align_right` the box will be printed on the right.
+
+A block may be attached to the group which will be called if any of its buttons is clicked.
+
+
+```ruby
+  group.command do
+    message_label.text = "#{group.name} #{group.value} has been selected"
+  end
+```
 
+### ButtonGroup
+
+A ButtonGroup is a collection of RadioButtons. 
+
+        group = ButtonGroup.new "Color"
+
+Methods:
+
+- `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.
+
+
+```ruby
+  group.command do
+    alert "#{group.name} #{group.value} has been selected"
+  end
+```
 
 ### Multiline
 

data/examples/ex3.rb

@@ -105,7 +105,7 @@ begin
   form.add_widget radio1, radio2
   group.command do
     message_label.text = "#{group.name} #{group.value} has been selected"
-    message_label.repaint_required = true
+    #message_label.repaint_required = true
   end
 
   ok_butt = Button.new( :name => 'ok', :text => 'Ok', :row => row+2, :col => col, :width => 10 , :color_pair => 0, :mnemonic => 'O')

data/lib/umbra/box.rb

@@ -4,38 +4,42 @@
 #       Author: j kepler  http://github.com/mare-imbrium/canis/
 #         Date: 2018-04-07
 #      License: MIT
-#  Last update: 2018-05-27 16:14
+#  Last update: 2018-06-02 19:01
 # ----------------------------------------------------------------------------- #
 #  box.rb  Copyright (C) 2018 j kepler
 module Umbra
   ##
-  # A box is a container around one, maybe more, widgets.
+  # A box is a container around one, or more, widgets.
+  # Properties include #visible, #justify and #title.
   ## 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
     attr_property :title
-    #attr_property :width
-    #attr_property :height
-    attr_accessor :row_offset     # not used yet
-    attr_accessor :col_offset     # not used yet
-    attr_property :visible
-    attr_reader   :widgets
-    attr_reader   :widget
-    attr_property :justify       # right, left or center TODO
+    # @param visible [true, false] set and return border visibility
+    attr_property :visible        # Is the border visible or not
+    # @return [Array<Widget>] return widgets added to this box
+    attr_reader   :widgets        # widgets added to this box
+    # @return [Widget] return widget added to this box
+    attr_reader   :widget         # single widget component
+    # @param justify [Symbol] set and return alignment of box :right :left :center
+    attr_property :justify       
 
     def initialize config={}, &block
       @focusable  = false
       @visible    = true
       super
-      #@int_height = @height - 2
+    
       @int_height = self.height - 2
-      #@int_width  = @width  - 2
+   
       @int_width  = self.width  - 2
       @hlines = []
       #@vlines = []   # UNUSED. TODO ???
     end
-    def repaint
+
+    # paint border and title, called by +Form+.
+    def repaint                                           #:nodoc:
       return unless @visible
       print_border self.row, self.col, self.height, self.width, @color_pair || CP_BLACK, @attr || NORMAL
       print_title @title
@@ -47,7 +51,7 @@ module Umbra
 
     ## 
     ## Add a variable list of components to a box, which are stacked horizontally by the box.
-    ## @param comma separated list of widgets
+    ## @param w [Array<Widget>]  comma separated list of widgets
     def add *w
       @widgets = w
       num = w.size
@@ -71,8 +75,8 @@ module Umbra
 
     ##
     ##  Horizontally place an array of widgets 
-    ## @param comma separated list of widgets
-    ## NOTE:  this is best used for widgets that can be resized.
+    ## @param w [Array<Widget>] comma separated list of widgets
+    ## @note  this is best used for widgets that can be resized.
     # Prefer not to use for buttons since the looks gets messed (inconsistency between button and highlight).
     # Therefore now, button calculates its own width which means that this program cannot determine what the width is
     # and thus cannot center it.

data/lib/umbra/button.rb

@@ -5,7 +5,7 @@
 #       Author: j kepler  http://github.com/mare-imbrium/canis/
 #         Date: 2018-03-16 
 #      License: MIT
-#  Last update: 2018-06-01 12:37
+#  Last update: 2018-06-02 19:28
 # ----------------------------------------------------------------------------- #
 #  button.rb  Copyright (C) 2012-2018 j kepler
 #  == Todo 
@@ -16,6 +16,7 @@ require 'umbra/widget'
 module Umbra
 
 
+  ## Widget that has an action associated with `:PRESS` event.
   class Button < Widget 
     attr_accessor :surround_chars   # characters to use to surround the button, def is square brackets
 
@@ -41,7 +42,7 @@ module Umbra
 
     ##
     # set button based on Action
-    # 2018-03-22 - is this still used ? XXX
+    # 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
@@ -95,12 +96,13 @@ module Umbra
         @repaint_required = false
     end
 
-    ## fires PRESS event of button
+    ## fires `PRESS` event of button
     def fire
       fire_handler :PRESS, ActionEvent.new(self, :PRESS, text)
     end
 
     # for campatibility with all buttons, will apply to radio buttons mostly
+    # @return [false]
     def selected?; false; end
 
     def map_keys
@@ -108,7 +110,7 @@ module Umbra
       bind_key(32, "fire") { fire } if respond_to? :fire
     end
 
-    # Button
+    # Button's key handler, just calls super
     def handle_key ch
       super
     end

data/lib/umbra/buttongroup.rb

@@ -4,93 +4,101 @@
 #       Author: j kepler  http://github.com/mare-imbrium/canis/
 #         Date: 2018-04-02 - 08:47
 #      License: MIT
-#  Last update: 2018-04-02 23:30
+#  Last update: 2018-06-03 12:18
 # ----------------------------------------------------------------------------- #
 #  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 
+module Umbra
 
-  # Array of buttons that have been added.
-  attr_reader    :elements
-  # name for group, can be used in messages
-  attr_accessor  :name
+  # 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 
 
-  # the value of the radio button that is selected. To get the button itself, use +selection+.
-  attr_reader :value
+    # Array of buttons that have been added.
+    attr_reader    :elements
+    # name for group, can be used in messages
+    attr_accessor  :name
 
-  def initialize name="Buttongroup"
-    @elements = []
-    @hash     = {}
-    @name     = name
-  end
+    # the value of the radio button that is selected. To get the button itself, use +selection+.
+    attr_reader :value
 
-  # 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
+    # @param name [String] a name which is used more for documenting/debugging.
+    def initialize name="Buttongroup"
+      @elements = []
+      @hash     = {}
+      @name     = name
+    end
 
-  # @return the radiobutton that is selected
-  def selection
-    @hash[@value]
-  end
+    # Add a radio button to the group.
+    # @note Maybe we should allow adding multiple, and alias to add_widget.
+    # @param e [RadioButton] button to add.
+    def add e
+      @elements << e
+      @hash[e.value] = e
+      e.button_group=(self)
+      self
+    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
+    # 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 val [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
-  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
+    # 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
-    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 }
+    # 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?
+      return unless @commands
+      @commands.each_with_index do |comm, ix|
+        comm.call(self, *@args[ix]) unless comm.nil?
+      end
     end
-  end
 
-end 
+  end 
+end  # module

data/lib/umbra/field.rb

@@ -1,14 +1,15 @@
 # ----------------------------------------------------------------------------- #
 #         File: field.rb
 #  Description: text input field or widget
-#       Author: j kepler  http://github.com/mare-imbrium/canis/
+#       Author: j kepler  http://github.com/mare-imbrium/
 #         Date: 2018-03
 #      License: MIT
-#  Last update: 2018-05-26 11:21
+#  Last update: 2018-06-02 10:26
 # ----------------------------------------------------------------------------- #
 #  field.rb  Copyright (C) 2012-2018 j kepler
 #
 
+module Umbra
 class InputDataEvent # {{{
   attr_accessor :index0, :index1, :source, :type, :row, :text
   def initialize index0, index1, source, type, row, text
@@ -35,7 +36,8 @@ class InputDataEvent # {{{
   def getvalue
     @source.getvalue
   end
-end # }}}
+end # class }}}
+end # module  
   # Text edit field
 #  Todo :
   # NOTE: +width+ is the length of the display whereas +maxlen+ is the maximum size that the value 

data/lib/umbra/label.rb

@@ -5,7 +5,7 @@
 #       Author: j kepler  http://github.com/mare-imbrium/canis/
 #         Date: 2018-03-08 - 14:04
 #      License: MIT
-#  Last update: 2018-05-22 23:36
+#  Last update: 2018-06-02 19:25
 # ----------------------------------------------------------------------------- #
 #  label.rb  Copyright (C) 2018- j kepler
 #
@@ -15,7 +15,8 @@ module Umbra
   # when creating use +text=+ to set text. Optionally use +justify+ and +width+.
 class Label < Widget 
 
-  # justify required a display length, esp if center.
+  # @note `justify` requires a display length, esp if center.
+  # @param justify [true, false] aliignment of label :right, :left or :center
   attr_property   :justify        #:right, :left, :center
   attr_accessor   :mnemonic       # alt-key that passes focus to related field 
   attr_accessor   :related_widget # field related to this label. See +mnemonic+.

data/lib/umbra/labeledfield.rb

@@ -4,12 +4,12 @@
 #       Author: j kepler  http://github.com/mare-imbrium/canis/
 #         Date: 2018-04-12 - 23:35
 #      License: MIT
-#  Last update: 2018-05-14 14:34
+#  Last update: 2018-06-03 09:58
 # ----------------------------------------------------------------------------- #
 #  labeledfield.rb Copyright (C) 2018 j kepler
 require 'umbra/field'
 module Umbra
-  # TODO we should consider creating a Label, so user can have more control. Or allow user
+  # TODO we should consider creating a `Label`, so user can have more control. Or allow user
   #   to supply a Label i/o a String ???
   #
   #   NOTE: If using LabeledField in a messagebox, pls specify messagebox width explicitly
@@ -20,23 +20,34 @@ module Umbra
   #   This could contain a Labal and a Field and extend Widget. Actually, it could be LabeledWidget
   #     so that any other widget is sent in and associated with a a label.
   #
+
+  ## A widget that has an entry +Field+ and an associated +String+.
+  # This stores a +String+ and prints it before the +Field+. 
+  # This label is gauranteed to print to the left of the Field.
+  # This label prints on +lrow+ and +lcol+ if supplied, else it will print on the left of the field
+  # at +col+ minus the width of the label. 
+  #
+  # It is initialized exactly like a Field, with the addition of `:label` (and optionally label_color_pair,
+  #   label_attr, and lcol, lrow)
   class LabeledField < Field
-    # This stores a +String+ and prints it before the +Field+. 
-    # This label is gauranteed to print to the left of the Field.
-    # This label prints on +lrow+ and +lcol+ if supplied, else it will print on the left of the field
-    # at +col+ minus the width of the label. 
-    #
-    # It is initialized exactly like a Field, with the addition of label (and optionally label_color_pair,
-    #   label_attr, and lcol, lrow)
-    # 
+    
+    ## @param label [String] a string to use and a label
     attr_property :label              # label of field, just a String  
+
     # if lrow and lcol are specified then label is printed exactly at that spot.
     # If they are omitted, then label is printed on left of field. Omit the lcol if you want
-    #   the fields to be aligned, one under another, with the labels right-aligned.
-    attr_property :lrow, :lcol        # coordinates of the label
+    #  the fields to be aligned, one under another, with the labels right-aligned.
+    # @param lrow [Integer] row for label to print on
+    attr_property :lrow        # coordinates of the label
+    # @param lcol [Integer] column for label to print on
+    attr_property :lcol        # coordinates of the label
+    # @param label_color_pair [Integer] color_pair of label
     attr_property :label_color_pair   # label of field  color_pair
+    # @param label_attr [Integer] attribute of label (NORMAL, BOLD, REVERSE ...)
     attr_property :label_attr         # label of field  attribute
+    # @param label_highlight_color_pair [Integer] color_pair of label when field in focus
     attr_property :label_highlight_color_pair   # label of field  high color_pair
+    # @param label_highlight_attr [Integer] attribute of label when field in focus
     attr_property :label_highlight_attr         # label of field  high attribute
     attr_accessor :mnemonic         # mnemonic of field which shows up on label
     attr_accessor :related_widget         #  to keep sync with label
@@ -45,7 +56,8 @@ module Umbra
       super
     end
 
-    def repaint
+    # paint the widget, called by +Form+.
+    def repaint                                  #:nodoc:
       return unless @repaint_required
       _lrow = @lrow || @row
       # the next was nice, but in some cases this goes out of screen. and the container

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-05-30 10:08
+#  Last update: 2018-06-03 10:39
 # ----------------------------------------------------------------------------- #
 #  listbox.rb  Copyright (C) 2012-2018 j kepler
 #  == TODO 
@@ -25,7 +25,9 @@ module Umbra
     attr_accessor :selection_allowed           # does this class allow row selection (should be class level)
     attr_accessor :selection_key               # key used to select a row
     attr_reader   :selected_index              # row selected, may change to plural
+    # @param selected_color_pair [Integer] color pair of row selected
     attr_property :selected_color_pair         # row selected color_pair
+    # @param selected_attr [Integer] attribute of row selected (default REVERSE)
     attr_property :selected_attr               # row selected color_pair
     attr_accessor :selected_mark               # row selected character
     attr_accessor :unselected_mark             # row unselected character (usually blank)
@@ -47,16 +49,20 @@ module Umbra
     end
 
 
+    # set the list 
+    # @param alist [Array<String>] string array to display as a list
     def list=(alist)
       super
       clear_selection
     end
 
 
+    # clear selected index/indices
     def clear_selection
       @selected_index = nil
     end
 
+    # Binds selection key to +toggle_selection+ if selection enabled. All others pass to parent class.
     def map_keys
       return if @keys_mapped
       if @selection_allowed and @selection_key
@@ -66,6 +72,7 @@ module Umbra
     end
 
     ## Toggle current row's selection status.
+    ## @param _row [Integer] row to toggle, default to current row
     def toggle_selection _row=@current_index
       @repaint_required = true  
       if @selected_index == _row
@@ -75,13 +82,15 @@ module Umbra
       end
     end
 
-    ## select given row
+    ## select given row, and fire SELECT_ROW handler
+    ## @param _row [Integer] row to select, default to current row
     def select_row _row=@current_index
       @selected_index = _row
       fire_handler :SELECT_ROW, self   # use selected_index to know which one
     end
     
-    ## unselect given row
+    ## unselect given row, and fire SELECT_ROW handler
+    ## @param _row [Integer] row to unselect, default to current row
     def unselect_row _row=@current_index
       if _row == @selected_index
         @selected_index = nil
@@ -93,11 +102,11 @@ module Umbra
     ## For any major customization of Listbox output, this method would be overridden.
     ## This method determines state, mark, slice of line item to show.
     ## listbox adds a mark on the side, whether a row is selected or not, and whether it is current.
-    ## @param win - window pointer for printing
-    ## @param [Integer] - row offset on screen
-    ## @param [Integer] - col offset on screen
-    ## @param [String]  - line to print
-    ## @param [Integer] - offset in List array
+    ## @param win [Window] - window pointer for printing
+    ## @param row [Integer] - row offset on screen
+    ## @param col [Integer] - col offset on screen
+    ## @param line [String]  - line to print
+    ## @param index [Integer] - offset in List array
     def paint_row(win, row, col, line, index)
 
       state = state_of_row(index)     
@@ -127,8 +136,9 @@ module Umbra
     ## Determine the mark on the left of the row. 
     ## The mark depends on the state: :SELECTED :HIGHLIGHTED :CURRENT :NORMAL
     ## Listbox adds :SELECTED state to Multiline.
-    ## @param [Integer] offset of row in data
-    ## @return character to be displayed inside left margin
+    ## @param index [Integer] offset of row in data
+    ## @param state [Symbol] state of current row
+    ## @return [String] aracter to be displayed inside left margin
     def mark_of_row index, state
       mark = case state
              when :SELECTED
@@ -147,6 +157,7 @@ module Umbra
     ##  which can be determined using +index+.
     ## Listbox adds :SELECTED state to +Multiline+.
     ## @param [Integer] offset of row in data
+    ## @param state [Symbol] state of current row
     ## @return [Array] color_pair and attrib constant
     def color_of_row index, state
       arr = super

data/lib/umbra/pad.rb

@@ -7,7 +7,7 @@
   * Author:  jkepler
   * Date:    2018-03-28 14:30
   * License: MIT
-  * Last update:  2018-06-01 12:40
+  * Last update:  2018-06-02 10:22
 
   == CHANGES
   == Todo 
@@ -21,6 +21,7 @@
 =end
 require 'ffi-ncurses'
 
+module Umbra
 class Pad
 
   # You may pass height, width, row and col for creating a window otherwise a fullscreen window
@@ -346,3 +347,4 @@ if __FILE__ == $PROGRAM_NAME
     FFI::NCurses.curs_set 1                  # cursor visible again
   end
 end
+end # module

data/lib/umbra/radiobutton.rb

@@ -1,26 +1,33 @@
 # ----------------------------------------------------------------------------- #
 #         File: radiobutton.rb
 #  Description: a member of a group of buttons, only one can be selected at a time.
-#       Author: j kepler  http://github.com/mare-imbrium/canis/
+#       Author: j kepler  http://github.com/mare-imbrium/
 #         Date: 2018-04-02 - 10:37
 #      License: MIT
-#  Last update: 2018-06-01 12:31
+#  Last update: 2018-06-03 11:27
 # ----------------------------------------------------------------------------- #
 #  radiobutton.rb  Copyright (C) 2012-2018 j kepler
 
 module Umbra
   ##
-  # A selectable button that has a text value. It is based on a Variable that
-  # is shared by other radio buttons. Only one is selected at a time, unlike checkbox
-  # +text+ is the value to display, which can include an ampersand for a hotkey
-  # +value+ is the value returned if selected, which usually is similar to text (or a short word)
+  # A selectable button that has a text value. It is linked to a +ButtonGroup+ that
+  # is shared by other radio buttons. Only one is selected at a time, unlike +Checkbox+.
+  # +text+ is the value to display, which can include an ampersand for a hotkey.
+  # +value+ is the value returned if selected, which usually is similar to text (or a short word).
   # +width+ is helpful if placing the brackets to right of text, used to align round brackets
   #   By default, radio buttons place the button on the left of the text.
   #
-  # Typically, the variable's update_command is passed a block to execute whenever any of the 
+  # Typically, the +ButtonGroup+'s `command` is passed a block to execute whenever any of the 
   # radiobuttons of this group is fired.
-
+  # @example
+  #   radio1 = RadioButton.new text: "Red", value: "Red", row: 10, col: 20
+  #   radio2 = RadioButton.new text: "Blue", value: "Blue", row: 11, col: 20
+  #   group = ButtonGroup.new "Color"
+  #   group.add(radio1).add(radio2)
+  #   form.add_widget radio1, radio2
+  #
   class RadioButton < ToggleButton
+    # @param align_right [true, false] set whether button should be on right of text, default false.
     attr_property :align_right    # the button will be on the right 
     attr_accessor :button_group   # group that this button belongs to.
 

data/lib/umbra/togglebutton.rb

@@ -6,7 +6,7 @@ require 'umbra/button'
 #       Author: j kepler  http://github.com/mare-imbrium/umbra/
 #         Date: 2018-03-17 - 22:50
 #      License: MIT
-#  Last update: 2018-05-27 14:21
+#  Last update: 2018-06-03 09:33
 # ----------------------------------------------------------------------------- #
 #  togglebutton.rb Copyright (C) 2018 j kepler
 #
@@ -14,25 +14,30 @@ require 'umbra/button'
 module Umbra
 
   # A button that may be switched off an on. 
-  # Extended by RadioButton and checkbox.
+  # Extended by `RadioButton` and `Checkbox`.
   # WARNING, pls do not override +text+ otherwise checkboxes etc will stop functioning.
   # TODO: add editable here and prevent toggling if not so.
   class ToggleButton < Button 
-    # text to display for on value and off value
+
+    # set or get text to display for on value and off value
     attr_accessor :onvalue, :offvalue
-    # boolean, which value to use currently, onvalue or offvalue
+
+    # @param value [true, false] Which value to use currently, onvalue or offvalue
+    # @return [true, false] current value
     attr_property :value
-    # characters to use for surround, array, default square brackets
-    #attr_property :surround_chars  already in button
-    # 2018-04-02 - removing variable
+
     # background to use when selected, if not set then default
     # 2018-04-02 - unused so commenting off. color_pair is not used here or in checkbox
     #attr_property :selected_color_pair
 
+    ## Just calls super.
+    ## @param config [Hash] config values such as row, col, onvalue, offvalue and value.
     def initialize config={}, &block
       super
 
     end
+
+    # @return [onvalue, offvalue] returns on or off value depending on +@value+.
     def getvalue
       @value ? @onvalue : @offvalue
     end
@@ -42,9 +47,11 @@ module Umbra
     # added for some standardization 2010-09-07 20:28 
     # alias :text :getvalue # NEXT VERSION
     # change existing text to label
+    
+   
     ##
     # is the button on or off
-    # added 2008-12-09 19:05 
+    # @return [true, false] returns +@value+, has the button been checked or not.
     def checked?
       @value
     end
@@ -62,8 +69,8 @@ module Umbra
       @surround_chars[0] + buttontext + @surround_chars[1]
     end
 
-    # toggle button handle key
-    # @param [int] key received
+    # toggle button handle key. Handles only `space` (32), all others are passed to parent classes.
+    # @param ch [Integer] key received
     #
     def handle_key ch
       if ch == 32
@@ -75,12 +82,14 @@ module Umbra
     end
 
     ##
-    # toggle the button value
+    # toggle the button value. Calls +fire+.
     def toggle
       fire
     end
 
-    # called on :PRESS event
+    # Toggles the button's value.
+    # Called by +toggle+ (when users pressed +SPACE+).
+    # Calls :PRESS event
     def fire
       checked(!@value)
       #@item_event = ItemEvent.new self, self if @item_event.nil?
@@ -89,7 +98,8 @@ module Umbra
       ## 2018-05-27 - trying to use self in most cases. Above was not needed.
       fire_handler :PRESS, self
     end
-    ##
+
+
     # set the value to true or false
     # user may programmatically want to check or uncheck
     # ## duplicate of value ??? 2018-05-26 - 

data/lib/umbra/version.rb

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

data/lib/umbra/widget.rb

@@ -9,6 +9,10 @@ require 'umbra/keymappinghandler'    # for bind_key and process_key
 
 class Module # {{{
 
+  # dsl method for declaring attribute setters which result in widget
+  # being repainted. Also, fire a #fire_property_change event.
+  # @param symbols [Symbol] value to be set
+  # @return [Widget] self
   def attr_property(*symbols)
     symbols.each { |sym|
       class_eval %{
@@ -37,58 +41,76 @@ class Module # {{{
   end # def
 end # module }}}
 module Umbra
-class FieldValidationException < RuntimeError
-end
-class Widget   
+
+  ## Exception thrown by Field if validation fails
+  class FieldValidationException < RuntimeError
+  end
+
+
+  ## Parent class of all widgets/controls that are displayed on the screen/window
+  ## and are managed by +Form+.
+  ## Many attributes use `attr_property` instead of `attr_accessor`. This is used for elements
+  ## that must repaint the widget whenever updated. They also fire a property change event.
+  ## These properties may not show up in the generated RDoc.
+  ## This class will not be instantiated by programs, only its subclasses will be.
+  ## Widget registers `:ENTER` `:LEAVE` `:CHANGED` and `:PROPERTY_CHANGE` events.
+  ## Widget defines three states: `:NORMAL` `:HIGHLIGHTED` and `:SELECTED`.
+  ##  `HIGHLIGHTED` refers to the single widget that is focussed. 
+  ##  `SELECTED` is only for Togglebuttons that may be in `SELECTED` state.
+  ##  `NORMAL` state is for all others (the default state).
+  class Widget   
     include EventHandler
     include KeyMappingHandler
-  # common interface for text related to a field, label, textview, button etc
-  attr_property :text
-  attr_property   :width, :height   ## width and height of widget
-
-  # foreground and background colors when focussed. Currently used with buttons and field
-  # Form checks and repaints on entry if these are set.
-  attr_property :highlight_color_pair
-  attr_property :highlight_attr
-
-  # NOTE: 2018-03-04 - user will have to call repaint_required if he changes color or coordinates.
-  attr_accessor  :col                   # location of object
-  attr_writer    :row                   # location of object
-  # moved to a method which calculates color 2011-11-12 
-  attr_property  :color_pair                  # instead of colors give just color_pair
-  attr_property  :attr                        # attribute bold, normal, reverse
-  attr_accessor  :name                        # name to refr to or recall object by_name
-  attr_accessor :curpos                       # cursor position inside object - column, not row.
-  #attr_reader  :config                        # can be used for popping user objects too. NOTE unused
-  #attr_accessor  :form                       # made accessor 2008-11-27 22:32 so menu can set
-  attr_accessor  :graphic                     # window which should be set by form when adding 2018-03-19
-  attr_accessor :state                        # normal, selected, highlighted
-  attr_reader  :row_offset, :col_offset       # where should the cursor be placed to start with
-  attr_property  :visible                     # boolean     # 2008-12-09 11:29 
-  # if changing focusable property of a field after form creation, you may need to call
-  # pack again, or atl east update_focusables
-  attr_reader   :focusable                   # boolean     can this get focus # 2018-03-21 - 23:13 
-  # 2018-03-04 - we should use modified as accessor unless it is due to setting forms modified
-  # 2018-03-22 - making it accessor
-  attr_accessor :modified                     # boolean, value modified or not (moved from field 2009-01-18 00:14 )
-  #attr_accessor  :help_text                   # added 2009-01-22 17:41 can be used for status/tooltips
+
+    ## @param text [String] common interface for text related to a field, label, textview, button etc
+    attr_property :text
+    ## @param width [Integer] width of widget, same for +height+
+    attr_property   :width, :height   ## width and height of widget
+
+    # foreground and background colors when focussed. Currently used with buttons and field
+    # Form checks and repaints on entry if these are set.
+    ## @param highlight_color_pair [Integer] color pair of widget when focussed
+    attr_property :highlight_color_pair
+    ## @param highlight_attr [Integer] visual attribute of widget when focussed
+    attr_property :highlight_attr
+
+    attr_accessor  :col                   # location of object (column)
+    attr_writer    :row                   # location of object
+
+    ## @param color_pair [Integer] color pair of widget (when not focussed)
+    attr_property  :color_pair                  # instead of colors give just color_pair
+    ## @param attr [Integer] visual attribute of widget when not focussed
+    attr_property  :attr                        # attribute bold, normal, reverse
+
+    attr_accessor  :name                        # documentation, used in print statements
+    attr_accessor :curpos                       # cursor position inside object - column, not row.
+
+
+    attr_accessor  :graphic                     # window which should be set by form when adding 
+    attr_accessor :state                        # :NORMAL, :SELECTED, :HIGHLIGHTED
+    attr_reader  :row_offset, :col_offset       # where should the cursor be placed to start with
+
+    ## @param attr [true, false] should the widget be displayed or not
+    attr_property  :visible 
+
+    attr_reader   :focusable                   # boolean     can this get focus or not.
+
+    attr_accessor :modified                     # boolean, value modified or not
 
   #attr_accessor :parent_component  # added 2010-01-12 23:28 BUFFERED - to bubble up
 
-  # NOTE state takes care of this and is set by form. boolean 2018-05-26 - commented since unused
-  #attr_reader :focussed                    # is this widget in focus, so they may paint differently
 
-  # height percent and width percent used in stacks and flows.
-  #attr_accessor :height_pc, :width_pc        # may bring this back
+    # @return [String] descriptions for each key set in _key_map, NOT YET displayed TODO
+    attr_reader :key_label
 
-  # descriptions for each key set in _key_map
-  # 2018-03-07 - NOT_SURE
-  attr_reader :key_label
-  attr_reader :handler                       # event handler
-  # adding as attr_accessor  2018-03-22 - 
-  # is a repaint required or not, boolean
-  attr_accessor  :repaint_required
+    # @return [Hash]  event handler hash containing key and block association
+    attr_reader :handler                       
 
+    # @param repaint_required [true, false] is a repaint required or not, boolean
+    attr_accessor  :repaint_required
+
+    # @param aconfig [Hash] initialization parameters such as row, col, height, width, color_pair, text.
+    # @yield [Widget] self
   def initialize aconfig={}, &block
     @row_offset ||= 0
     @col_offset ||= 0
@@ -112,24 +134,25 @@ class Widget
     end
   end
 
-  def variable_set var, val
+  def variable_set var, val #:nodoc:
     send("#{var}=", val) 
   end
-  def init_vars
+
+  ## Initialise internal variables
+  def init_vars  #:nodoc:
     # just in case anyone does a super. Not putting anything here
     # since i don't want anyone accidentally overriding
   end
 
-  # modified
-  ##
-  # typically read will be overridden to check if value changed from what it was on enter.
-  # getter and setter for modified (added 2009-01-18 12:31 )
+  # Widget modified or not.
+  # typically will be overridden to check if value changed from what it was on enter.
+  # @return [true, false] modified since on_enter or not
   def modified?
     @modified
   end
 
   # triggered whenever a widget is entered.
-  # NOTE should we not fix cursor at this point (on_enter) ?
+  ## Will invoke `:ENTER` handler/event
   def on_enter
     ## Form has already set this, and set modified to false
     @state = :HIGHLIGHTED    # duplicating since often these are inside containers
@@ -138,7 +161,9 @@ class Widget
       fire_handler :ENTER, self
     end
   end
+
   ## Called when user exits a widget
+  ## Will invoke `:LEAVE` handler/event
   def on_leave
     @state = :NORMAL    # duplicating since often these are inside containers
     #@focussed = false
@@ -146,25 +171,32 @@ class Widget
       fire_handler :LEAVE, self
     end
   end
+
+
   ## 
-  # @return row and col of a widget where painting data actually starts
-  # row and col is where a widget starts. offsets usually take into account borders.
+  # Returns row and col is where a widget starts. offsets usually take into account borders.
   # the offsets typically are where the cursor should be positioned inside, upon on_enter.
+  # @return [Integer] row of widget where painting data actually starts
+  # @return [Integer] col of widget where painting data actually starts
   def rowcol
     return self.row+@row_offset, self.col+@col_offset
   end
-  ## return the value of the widget.
+
+  ## @return [String] the value of the widget.
   def getvalue
     @text
   end
+
   ##
   # Am making a separate method since often value for print differs from actual value
+  ## @return [String] the value of the widget for painting.
   def getvalue_for_paint
     getvalue
   end
+
   ##
-  # default repaint method. Called by form for all widgets.
-  #  widget does not have display_length.
+  # Default repaint method. Called by form for all widgets.
+  # widget does not have display_length. This should be overriden by concrete subclasses.
   def repaint
     r,c = rowcol
     $log.debug("widget repaint : r:#{r} c:#{c} col:#{@color_pair}" )
@@ -174,25 +206,18 @@ class Widget
     @graphic.printstring r, c, "%-*s" % [len, value], acolor, attr()
   end
 
-  def destroy
-    raise "what is this dong here still SHOULD Not be CALLED"
-    $log.debug "DESTROY : widget #{@name} "
-    panel = @window.panel
-    Ncurses::Panel.del_panel(panel.pointer) if !panel.nil?   
-    @window.delwin if !@window.nil?
-  end
 
-  # puts cursor on correct row.
-  def set_form_row
+  def set_form_row #:nodoc:
     raise "uncalled set_form_row"
     r, c = rowcol
     setrowcol row, nil  # does not exist any longer
   end
+
   # set cursor on correct column, widget
   # Ideally, this should be overriden, as it is not likely to be correct.
   # NOTE: this is okay for some widgets but NOT for containers
   # that will call their own components SFR and SFC
-  #Currently, Field has overriden this. +setrowcol+ does not exist any longer.
+  # Currently, Field has overriden this. +setrowcol+ does not exist any longer.
   def set_form_col col1=@curpos
     @curpos = col1 || 0 # 2010-01-14 21:02 
     #@form.col = @col + @col_offset + @curpos
@@ -201,8 +226,11 @@ class Widget
     setrowcol nil, c
   end
 
-  ## 
-  # to be added at end of handle_key of widgets so instlalled actions can be checked
+  # Handle keys entered by user when this widget is focussed. Executes blocks bound to given key or 
+  # else returns control to +Form+.
+  # To be called at end of `handle_key` of widgets so installed actions can be executed.
+  # @param ch [Integer] keystroke entered
+  # @return [0, :UNHANDLED] return value of block executed for given keystroke
   def handle_key(ch)
     ret = process_key ch, self
     return :UNHANDLED if ret == :UNHANDLED
@@ -211,23 +239,23 @@ class Widget
 
   # is the entire widget to be repainted including things like borders and titles
   # earlier took a default of true, now must be explicit. Perhaps, not used currently.
-  def repaint_all(tf)
+  def repaint_all(tf)  #:nodoc:
     # NOTE NOT USED
     raise " not used repaint all"
     @repaint_all = tf
     @repaint_required = tf
   end
-  # shortcut for users to indicate that a widget should be redrawn since some property has been changed.
-  # Now that I have created attr_property this may not be needed
+
+  # Shortcut for users to indicate that a widget should be redrawn since some property has been changed.
+  # Now that I have created +attr_property+ this may not be needed
   def touch
     @repaint_required = true
   end
 
 
-  # a general method for all widgets to override with their favorite or most meaninful event
-  # Ideally this is where the block in the constructor should land up.
-  # @since 1.5.0    2011-11-21 
-  # 2018-03-08 - NOT_SURE 
+  ## A general method for all widgets to override with their favorite or most meaninful event
+  ## This is a convenience method. Widgets that have a `PRESS` event will bind the given block to PRESS,
+  ## all others to the `CHANGED` event.
   def command *args, &block
     if event? :PRESS
       bind_event :PRESS, *args, &block
@@ -235,24 +263,31 @@ class Widget
       bind_event :CHANGED, *args, &block
     end
   end
-  def _form=(aform)
+
+  def _form=(aform)    #:nodoc:
     @_form = aform
   end
+
+  ## set focusable property to true or false
+  ## Also updates the focusables array.
   def focusable=(bool)
     #$log.debug "  inside focusable= with #{bool} "
     @focusable = bool
     @_form.update_focusables if @_form
   end
 
-  ## TODO maybe check for decimal between 0 and 1 which will be percentage of width
+  ## Get width of widget, treating negatives as relative width.
+  ## @return [Integer, nil] returns width of widget 
   def width
     return nil unless @width    ## this is required otherwise checking for nil will fail
     if @width < 0
       return ( FFI::NCurses.COLS + @width ) - self.col + 1
-      #return ( FFI::NCurses.COLS + @width ) #- self.col + 1
     end
     @width
   end
+
+  ## Get height of widget. Used only for +Multline+ widgets
+  ## @return [Integer, nil] height of widget if applicable
   def height
     return nil unless @height
     if @height < 0
@@ -261,6 +296,9 @@ class Widget
     end
     @height
   end
+
+  ## get row of widget
+  ## @return [Integer, nil] row of widget 
   def row
     return nil unless @row
     if @row < 0
@@ -268,7 +306,6 @@ class Widget
     end
     @row
   end
-  #
-  ## ADD HERE WIDGET
-end #  
+  
+  end # class  
 end # module

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ncumbra
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - kepler
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-01 00:00:00.000000000 Z
+date: 2018-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler