ncumbra 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 6154c2af0ffac0eba6eb146efb61ee935b01b95299f828231e62ece1aa52760b
4
- data.tar.gz: bb37af7243be9f5ba18252592a9a1a95b74157e66d5bb07d1ca1c3fd7cdb46fe
3
+ metadata.gz: ca4311543d96466d546a976b01991af75abb649575d862cd6d9c9b94bd7a3833
4
+ data.tar.gz: 6f56247dc1b5dfd77cb1d8fa0de95b275010ca276906c3ec88ac8119b6df134b
5
5
  SHA512:
6
- metadata.gz: cae7cbbc5818c5831f02bf7aa94d44c2912420f2ddb4dea18ff35fc0fff011e557ca5de83fb98e9d950086fa75f01fa160f91eceb02c8b9a118e62dffa72afb2
7
- data.tar.gz: 39bf8e78fddcde77125371be0a8b9a71bd70f59c242c2328c54ea1cf26d031218e532f41dacdbfd3fd34d521ee9869d7ffb856bfbf7d3f1b6ef7b0539b16c76f
6
+ metadata.gz: 749b3f931e2fbf3fc32176711207edb52f0794082f579b037f942a7e2cb47bdbd3136035faceb395f3f55015a9ec212c6ac7995a0d0e10197932e04e0c1bc4b4
7
+ data.tar.gz: c0e1e0e7bf83fa0a16f91b26495ffb93823ba614f6216438337beb3ab31958775e79b240aab1277fdab2d03cec6c2279c405a95b811dd2be2b1c527412079374
data/CHANGELOG CHANGED
@@ -1,3 +1,8 @@
1
+ 2018-06-03
2
+ - for 0.1.3
3
+ - YARD Documentation of attr_property
4
+ - Moved ButtonGroup and ItemEvent to module Umbra.
5
+
1
6
  2018-06-01
2
7
  - for 0.1.2
3
8
  - much cleaning up and some renaming of methods and properties
data/README.md CHANGED
@@ -440,8 +440,50 @@ The above is similar to:
440
440
 
441
441
  ### RadioButton
442
442
 
443
+ A +ToggleButton+ button that may have an on or off value. Usually, several related radio buttons are created and only one may be +on+.
444
+ Here, we create a +ButtonGroup+ and then `add` radio buttons to it.
443
445
 
446
+ ```ruby
447
+ radio1 = RadioButton.new text: "Red", value: "R", row: 5, col: 20
448
+ radio2 = RadioButton.new text: "Green", value: "G", row: 6, col: 20
449
+ group = ButtonGroup.new "Color"
450
+ group.add(radio1).add(radio2)
451
+ form.add_widget radio1, radio2
452
+ ```
453
+
454
+ 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.
455
+
456
+ A block may be attached to the group which will be called if any of its buttons is clicked.
457
+
458
+
459
+ ```ruby
460
+ group.command do
461
+ message_label.text = "#{group.name} #{group.value} has been selected"
462
+ end
463
+ ```
444
464
 
465
+ ### ButtonGroup
466
+
467
+ A ButtonGroup is a collection of RadioButtons.
468
+
469
+ group = ButtonGroup.new "Color"
470
+
471
+ Methods:
472
+
473
+ - `add` - add a +RadioButton+ to the group.
474
+ - `selection` - return the button that is selected
475
+ - `value` - get the value of the selected button
476
+ - `select?` - ask if given button is selected
477
+ - `select` - select the given button
478
+ - `elements` - get an array of buttons added
479
+ - `command` - supply a block to be called whenever a button in the group is clicked.
480
+
481
+
482
+ ```ruby
483
+ group.command do
484
+ alert "#{group.name} #{group.value} has been selected"
485
+ end
486
+ ```
445
487
 
446
488
  ### Multiline
447
489
 
data/examples/ex3.rb CHANGED
@@ -105,7 +105,7 @@ begin
105
105
  form.add_widget radio1, radio2
106
106
  group.command do
107
107
  message_label.text = "#{group.name} #{group.value} has been selected"
108
- message_label.repaint_required = true
108
+ #message_label.repaint_required = true
109
109
  end
110
110
 
111
111
  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 CHANGED
@@ -4,38 +4,42 @@
4
4
  # Author: j kepler http://github.com/mare-imbrium/canis/
5
5
  # Date: 2018-04-07
6
6
  # License: MIT
7
- # Last update: 2018-05-27 16:14
7
+ # Last update: 2018-06-02 19:01
8
8
  # ----------------------------------------------------------------------------- #
9
9
  # box.rb Copyright (C) 2018 j kepler
10
10
  module Umbra
11
11
  ##
12
- # A box is a container around one, maybe more, widgets.
12
+ # A box is a container around one, or more, widgets.
13
+ # Properties include #visible, #justify and #title.
13
14
  ## FIXME box needs to resize components if it's dimensions are changed.
14
- ## Or should components have a link to parent, so they can resize themselves ?
15
+ ## Or should components have a link to parent, so they can resize themselves ?
15
16
  #
16
17
  class Box < Widget
18
+ # @param title [String] set and return title of box
17
19
  attr_property :title
18
- #attr_property :width
19
- #attr_property :height
20
- attr_accessor :row_offset # not used yet
21
- attr_accessor :col_offset # not used yet
22
- attr_property :visible
23
- attr_reader :widgets
24
- attr_reader :widget
25
- attr_property :justify # right, left or center TODO
20
+ # @param visible [true, false] set and return border visibility
21
+ attr_property :visible # Is the border visible or not
22
+ # @return [Array<Widget>] return widgets added to this box
23
+ attr_reader :widgets # widgets added to this box
24
+ # @return [Widget] return widget added to this box
25
+ attr_reader :widget # single widget component
26
+ # @param justify [Symbol] set and return alignment of box :right :left :center
27
+ attr_property :justify
26
28
 
27
29
  def initialize config={}, &block
28
30
  @focusable = false
29
31
  @visible = true
30
32
  super
31
- #@int_height = @height - 2
33
+
32
34
  @int_height = self.height - 2
33
- #@int_width = @width - 2
35
+
34
36
  @int_width = self.width - 2
35
37
  @hlines = []
36
38
  #@vlines = [] # UNUSED. TODO ???
37
39
  end
38
- def repaint
40
+
41
+ # paint border and title, called by +Form+.
42
+ def repaint #:nodoc:
39
43
  return unless @visible
40
44
  print_border self.row, self.col, self.height, self.width, @color_pair || CP_BLACK, @attr || NORMAL
41
45
  print_title @title
@@ -47,7 +51,7 @@ module Umbra
47
51
 
48
52
  ##
49
53
  ## Add a variable list of components to a box, which are stacked horizontally by the box.
50
- ## @param comma separated list of widgets
54
+ ## @param w [Array<Widget>] comma separated list of widgets
51
55
  def add *w
52
56
  @widgets = w
53
57
  num = w.size
@@ -71,8 +75,8 @@ module Umbra
71
75
 
72
76
  ##
73
77
  ## Horizontally place an array of widgets
74
- ## @param comma separated list of widgets
75
- ## NOTE: this is best used for widgets that can be resized.
78
+ ## @param w [Array<Widget>] comma separated list of widgets
79
+ ## @note this is best used for widgets that can be resized.
76
80
  # Prefer not to use for buttons since the looks gets messed (inconsistency between button and highlight).
77
81
  # Therefore now, button calculates its own width which means that this program cannot determine what the width is
78
82
  # and thus cannot center it.
data/lib/umbra/button.rb CHANGED
@@ -5,7 +5,7 @@
5
5
  # Author: j kepler http://github.com/mare-imbrium/canis/
6
6
  # Date: 2018-03-16
7
7
  # License: MIT
8
- # Last update: 2018-06-01 12:37
8
+ # Last update: 2018-06-02 19:28
9
9
  # ----------------------------------------------------------------------------- #
10
10
  # button.rb Copyright (C) 2012-2018 j kepler
11
11
  # == Todo
@@ -16,6 +16,7 @@ require 'umbra/widget'
16
16
  module Umbra
17
17
 
18
18
 
19
+ ## Widget that has an action associated with `:PRESS` event.
19
20
  class Button < Widget
20
21
  attr_accessor :surround_chars # characters to use to surround the button, def is square brackets
21
22
 
@@ -41,7 +42,7 @@ module Umbra
41
42
 
42
43
  ##
43
44
  # set button based on Action
44
- # 2018-03-22 - is this still used ? XXX
45
+ # 2018-03-22 - is this still used ?
45
46
  # This allows action objects to be used in multiple places such as buttons, menus, popups etc.
46
47
  def action a
47
48
  text a.name
@@ -95,12 +96,13 @@ module Umbra
95
96
  @repaint_required = false
96
97
  end
97
98
 
98
- ## fires PRESS event of button
99
+ ## fires `PRESS` event of button
99
100
  def fire
100
101
  fire_handler :PRESS, ActionEvent.new(self, :PRESS, text)
101
102
  end
102
103
 
103
104
  # for campatibility with all buttons, will apply to radio buttons mostly
105
+ # @return [false]
104
106
  def selected?; false; end
105
107
 
106
108
  def map_keys
@@ -108,7 +110,7 @@ module Umbra
108
110
  bind_key(32, "fire") { fire } if respond_to? :fire
109
111
  end
110
112
 
111
- # Button
113
+ # Button's key handler, just calls super
112
114
  def handle_key ch
113
115
  super
114
116
  end
@@ -4,93 +4,101 @@
4
4
  # Author: j kepler http://github.com/mare-imbrium/canis/
5
5
  # Date: 2018-04-02 - 08:47
6
6
  # License: MIT
7
- # Last update: 2018-04-02 23:30
7
+ # Last update: 2018-06-03 12:18
8
8
  # ----------------------------------------------------------------------------- #
9
9
  # buttongroup.rb Copyright (C) 2012-2018 j kepler
10
- # This is not a visual class or a widget.
11
- # This class allows us to attach several RadioButtons to it, so it can maintain which one is the
12
- # selected one. It also allows for assigning of commands to be executed whenever a button is pressed,
13
- # akin to binding to the +fire+ of the button, except that one would not have to bind to each button,
14
- # but only once here.
15
- #
16
- # @example
17
- # group = ButtonGroup.new
18
- # group.add(r1).add(r2).add(r3)
19
- # group.command(somelabel) do |grp, label| label.text = grp.value; end
10
+
20
11
  #
21
- class ButtonGroup
12
+ module Umbra
22
13
 
23
- # Array of buttons that have been added.
24
- attr_reader :elements
25
- # name for group, can be used in messages
26
- attr_accessor :name
14
+ # This is not a visual class or a widget.
15
+ # This class allows us to attach several RadioButtons to it, so it can maintain which one is the
16
+ # selected one. It also allows for assigning of commands to be executed whenever a button is pressed,
17
+ # akin to binding to the +fire+ of the button, except that one would not have to bind to each button,
18
+ # but only once here.
19
+ #
20
+ # @example
21
+ # group = ButtonGroup.new
22
+ # group.add(r1).add(r2).add(r3)
23
+ # group.command(somelabel) do |grp, label| label.text = grp.value; end
24
+ class ButtonGroup
27
25
 
28
- # the value of the radio button that is selected. To get the button itself, use +selection+.
29
- attr_reader :value
26
+ # Array of buttons that have been added.
27
+ attr_reader :elements
28
+ # name for group, can be used in messages
29
+ attr_accessor :name
30
30
 
31
- def initialize name="Buttongroup"
32
- @elements = []
33
- @hash = {}
34
- @name = name
35
- end
31
+ # the value of the radio button that is selected. To get the button itself, use +selection+.
32
+ attr_reader :value
36
33
 
37
- # add a radio button to the group.
38
- def add e
39
- @elements << e
40
- @hash[e.value] = e
41
- e.button_group=(self)
42
- self
43
- end
44
- # remove button from group
45
- def remove e
46
- @elements.delete e
47
- @hash.delete e.value
48
- self
49
- end
34
+ # @param name [String] a name which is used more for documenting/debugging.
35
+ def initialize name="Buttongroup"
36
+ @elements = []
37
+ @hash = {}
38
+ @name = name
39
+ end
50
40
 
51
- # @return the radiobutton that is selected
52
- def selection
53
- @hash[@value]
54
- end
41
+ # Add a radio button to the group.
42
+ # @note Maybe we should allow adding multiple, and alias to add_widget.
43
+ # @param e [RadioButton] button to add.
44
+ def add e
45
+ @elements << e
46
+ @hash[e.value] = e
47
+ e.button_group=(self)
48
+ self
49
+ end
55
50
 
56
- # @param [String, RadioButton] +value+ of a button, or +Button+ itself to check if selected.
57
- # @return [true or false] for whether the given value or button is the selected one
58
- def selected? val
59
- if val.is_a? String
60
- @value == val
61
- else
62
- @hash[@value] == val
51
+ # remove button from group
52
+ def remove e
53
+ @elements.delete e
54
+ @hash.delete e.value
55
+ self
56
+ end
57
+
58
+ # @return the radiobutton that is selected
59
+ def selection
60
+ @hash[@value]
61
+ end
62
+
63
+ # @param val [String, RadioButton] +value+ of a button, or +Button+ itself to check if selected.
64
+ # @return [true or false] for whether the given value or button is the selected one
65
+ def selected? val
66
+ if val.is_a? String
67
+ @value == val
68
+ else
69
+ @hash[@value] == val
70
+ end
71
+ end
72
+ # install trigger to call whenever a value is updated
73
+ # @public called by user components
74
+ def command *args, &block
75
+ @commands ||= []
76
+ @args ||= []
77
+ @commands << block
78
+ @args << args
63
79
  end
64
- end
65
- # install trigger to call whenever a value is updated
66
- # @public called by user components
67
- def command *args, &block
68
- @commands ||= []
69
- @args ||= []
70
- @commands << block
71
- @args << args
72
- end
73
- # select the given button or value.
74
- # This may be called by user programs to programmatically select a button
75
- def select button
76
- if button.is_a? String
77
- ;
78
- else
79
- button = button.value
80
+ # select the given button or value.
81
+ # This may be called by user programs to programmatically select a button
82
+ def select button
83
+ if button.is_a? String
84
+ ;
85
+ else
86
+ button = button.value
87
+ end
88
+ self.value = button
80
89
  end
81
- self.value = button
82
- end
83
- # whenever a radio button is pressed, it updates the value of the group with it;s value.
84
- # since only one is true at a time.
85
- def value=(value)
86
- @value = value
87
- # 2018-04-02 - need to repaint all the radio buttons so they become off
88
- @elements.each {|e| e.repaint_required = true }
90
+ # whenever a radio button is pressed, it updates the value of the group with it;s value.
91
+ # since only one is true at a time.
92
+ def value=(value)
93
+ @value = value
94
+ # 2018-04-02 - need to repaint all the radio buttons so they become off
95
+ @elements.each {|e| e.repaint_required = true }
89
96
 
90
- return unless @commands
91
- @commands.each_with_index do |comm, ix|
92
- comm.call(self, *@args[ix]) unless comm.nil?
97
+ return unless @commands
98
+ @commands.each_with_index do |comm, ix|
99
+ comm.call(self, *@args[ix]) unless comm.nil?
100
+ end
93
101
  end
94
- end
95
102
 
96
- end
103
+ end
104
+ end # module
data/lib/umbra/field.rb CHANGED
@@ -1,14 +1,15 @@
1
1
  # ----------------------------------------------------------------------------- #
2
2
  # File: field.rb
3
3
  # Description: text input field or widget
4
- # Author: j kepler http://github.com/mare-imbrium/canis/
4
+ # Author: j kepler http://github.com/mare-imbrium/
5
5
  # Date: 2018-03
6
6
  # License: MIT
7
- # Last update: 2018-05-26 11:21
7
+ # Last update: 2018-06-02 10:26
8
8
  # ----------------------------------------------------------------------------- #
9
9
  # field.rb Copyright (C) 2012-2018 j kepler
10
10
  #
11
11
 
12
+ module Umbra
12
13
  class InputDataEvent # {{{
13
14
  attr_accessor :index0, :index1, :source, :type, :row, :text
14
15
  def initialize index0, index1, source, type, row, text
@@ -35,7 +36,8 @@ class InputDataEvent # {{{
35
36
  def getvalue
36
37
  @source.getvalue
37
38
  end
38
- end # }}}
39
+ end # class }}}
40
+ end # module
39
41
  # Text edit field
40
42
  # Todo :
41
43
  # NOTE: +width+ is the length of the display whereas +maxlen+ is the maximum size that the value
data/lib/umbra/label.rb CHANGED
@@ -5,7 +5,7 @@
5
5
  # Author: j kepler http://github.com/mare-imbrium/canis/
6
6
  # Date: 2018-03-08 - 14:04
7
7
  # License: MIT
8
- # Last update: 2018-05-22 23:36
8
+ # Last update: 2018-06-02 19:25
9
9
  # ----------------------------------------------------------------------------- #
10
10
  # label.rb Copyright (C) 2018- j kepler
11
11
  #
@@ -15,7 +15,8 @@ module Umbra
15
15
  # when creating use +text=+ to set text. Optionally use +justify+ and +width+.
16
16
  class Label < Widget
17
17
 
18
- # justify required a display length, esp if center.
18
+ # @note `justify` requires a display length, esp if center.
19
+ # @param justify [true, false] aliignment of label :right, :left or :center
19
20
  attr_property :justify #:right, :left, :center
20
21
  attr_accessor :mnemonic # alt-key that passes focus to related field
21
22
  attr_accessor :related_widget # field related to this label. See +mnemonic+.
@@ -4,12 +4,12 @@
4
4
  # Author: j kepler http://github.com/mare-imbrium/canis/
5
5
  # Date: 2018-04-12 - 23:35
6
6
  # License: MIT
7
- # Last update: 2018-05-14 14:34
7
+ # Last update: 2018-06-03 09:58
8
8
  # ----------------------------------------------------------------------------- #
9
9
  # labeledfield.rb Copyright (C) 2018 j kepler
10
10
  require 'umbra/field'
11
11
  module Umbra
12
- # TODO we should consider creating a Label, so user can have more control. Or allow user
12
+ # TODO we should consider creating a `Label`, so user can have more control. Or allow user
13
13
  # to supply a Label i/o a String ???
14
14
  #
15
15
  # NOTE: If using LabeledField in a messagebox, pls specify messagebox width explicitly
@@ -20,23 +20,34 @@ module Umbra
20
20
  # This could contain a Labal and a Field and extend Widget. Actually, it could be LabeledWidget
21
21
  # so that any other widget is sent in and associated with a a label.
22
22
  #
23
+
24
+ ## A widget that has an entry +Field+ and an associated +String+.
25
+ # This stores a +String+ and prints it before the +Field+.
26
+ # This label is gauranteed to print to the left of the Field.
27
+ # This label prints on +lrow+ and +lcol+ if supplied, else it will print on the left of the field
28
+ # at +col+ minus the width of the label.
29
+ #
30
+ # It is initialized exactly like a Field, with the addition of `:label` (and optionally label_color_pair,
31
+ # label_attr, and lcol, lrow)
23
32
  class LabeledField < Field
24
- # This stores a +String+ and prints it before the +Field+.
25
- # This label is gauranteed to print to the left of the Field.
26
- # This label prints on +lrow+ and +lcol+ if supplied, else it will print on the left of the field
27
- # at +col+ minus the width of the label.
28
- #
29
- # It is initialized exactly like a Field, with the addition of label (and optionally label_color_pair,
30
- # label_attr, and lcol, lrow)
31
- #
33
+
34
+ ## @param label [String] a string to use and a label
32
35
  attr_property :label # label of field, just a String
36
+
33
37
  # if lrow and lcol are specified then label is printed exactly at that spot.
34
38
  # If they are omitted, then label is printed on left of field. Omit the lcol if you want
35
- # the fields to be aligned, one under another, with the labels right-aligned.
36
- attr_property :lrow, :lcol # coordinates of the label
39
+ # the fields to be aligned, one under another, with the labels right-aligned.
40
+ # @param lrow [Integer] row for label to print on
41
+ attr_property :lrow # coordinates of the label
42
+ # @param lcol [Integer] column for label to print on
43
+ attr_property :lcol # coordinates of the label
44
+ # @param label_color_pair [Integer] color_pair of label
37
45
  attr_property :label_color_pair # label of field color_pair
46
+ # @param label_attr [Integer] attribute of label (NORMAL, BOLD, REVERSE ...)
38
47
  attr_property :label_attr # label of field attribute
48
+ # @param label_highlight_color_pair [Integer] color_pair of label when field in focus
39
49
  attr_property :label_highlight_color_pair # label of field high color_pair
50
+ # @param label_highlight_attr [Integer] attribute of label when field in focus
40
51
  attr_property :label_highlight_attr # label of field high attribute
41
52
  attr_accessor :mnemonic # mnemonic of field which shows up on label
42
53
  attr_accessor :related_widget # to keep sync with label
@@ -45,7 +56,8 @@ module Umbra
45
56
  super
46
57
  end
47
58
 
48
- def repaint
59
+ # paint the widget, called by +Form+.
60
+ def repaint #:nodoc:
49
61
  return unless @repaint_required
50
62
  _lrow = @lrow || @row
51
63
  # the next was nice, but in some cases this goes out of screen. and the container
data/lib/umbra/listbox.rb CHANGED
@@ -5,7 +5,7 @@ require 'umbra/multiline'
5
5
  # Author: j kepler http://github.com/mare-imbrium/umbra
6
6
  # Date: 2018-03-19
7
7
  # License: MIT
8
- # Last update: 2018-05-30 10:08
8
+ # Last update: 2018-06-03 10:39
9
9
  # ----------------------------------------------------------------------------- #
10
10
  # listbox.rb Copyright (C) 2012-2018 j kepler
11
11
  # == TODO
@@ -25,7 +25,9 @@ module Umbra
25
25
  attr_accessor :selection_allowed # does this class allow row selection (should be class level)
26
26
  attr_accessor :selection_key # key used to select a row
27
27
  attr_reader :selected_index # row selected, may change to plural
28
+ # @param selected_color_pair [Integer] color pair of row selected
28
29
  attr_property :selected_color_pair # row selected color_pair
30
+ # @param selected_attr [Integer] attribute of row selected (default REVERSE)
29
31
  attr_property :selected_attr # row selected color_pair
30
32
  attr_accessor :selected_mark # row selected character
31
33
  attr_accessor :unselected_mark # row unselected character (usually blank)
@@ -47,16 +49,20 @@ module Umbra
47
49
  end
48
50
 
49
51
 
52
+ # set the list
53
+ # @param alist [Array<String>] string array to display as a list
50
54
  def list=(alist)
51
55
  super
52
56
  clear_selection
53
57
  end
54
58
 
55
59
 
60
+ # clear selected index/indices
56
61
  def clear_selection
57
62
  @selected_index = nil
58
63
  end
59
64
 
65
+ # Binds selection key to +toggle_selection+ if selection enabled. All others pass to parent class.
60
66
  def map_keys
61
67
  return if @keys_mapped
62
68
  if @selection_allowed and @selection_key
@@ -66,6 +72,7 @@ module Umbra
66
72
  end
67
73
 
68
74
  ## Toggle current row's selection status.
75
+ ## @param _row [Integer] row to toggle, default to current row
69
76
  def toggle_selection _row=@current_index
70
77
  @repaint_required = true
71
78
  if @selected_index == _row
@@ -75,13 +82,15 @@ module Umbra
75
82
  end
76
83
  end
77
84
 
78
- ## select given row
85
+ ## select given row, and fire SELECT_ROW handler
86
+ ## @param _row [Integer] row to select, default to current row
79
87
  def select_row _row=@current_index
80
88
  @selected_index = _row
81
89
  fire_handler :SELECT_ROW, self # use selected_index to know which one
82
90
  end
83
91
 
84
- ## unselect given row
92
+ ## unselect given row, and fire SELECT_ROW handler
93
+ ## @param _row [Integer] row to unselect, default to current row
85
94
  def unselect_row _row=@current_index
86
95
  if _row == @selected_index
87
96
  @selected_index = nil
@@ -93,11 +102,11 @@ module Umbra
93
102
  ## For any major customization of Listbox output, this method would be overridden.
94
103
  ## This method determines state, mark, slice of line item to show.
95
104
  ## listbox adds a mark on the side, whether a row is selected or not, and whether it is current.
96
- ## @param win - window pointer for printing
97
- ## @param [Integer] - row offset on screen
98
- ## @param [Integer] - col offset on screen
99
- ## @param [String] - line to print
100
- ## @param [Integer] - offset in List array
105
+ ## @param win [Window] - window pointer for printing
106
+ ## @param row [Integer] - row offset on screen
107
+ ## @param col [Integer] - col offset on screen
108
+ ## @param line [String] - line to print
109
+ ## @param index [Integer] - offset in List array
101
110
  def paint_row(win, row, col, line, index)
102
111
 
103
112
  state = state_of_row(index)
@@ -127,8 +136,9 @@ module Umbra
127
136
  ## Determine the mark on the left of the row.
128
137
  ## The mark depends on the state: :SELECTED :HIGHLIGHTED :CURRENT :NORMAL
129
138
  ## Listbox adds :SELECTED state to Multiline.
130
- ## @param [Integer] offset of row in data
131
- ## @return character to be displayed inside left margin
139
+ ## @param index [Integer] offset of row in data
140
+ ## @param state [Symbol] state of current row
141
+ ## @return [String] aracter to be displayed inside left margin
132
142
  def mark_of_row index, state
133
143
  mark = case state
134
144
  when :SELECTED
@@ -147,6 +157,7 @@ module Umbra
147
157
  ## which can be determined using +index+.
148
158
  ## Listbox adds :SELECTED state to +Multiline+.
149
159
  ## @param [Integer] offset of row in data
160
+ ## @param state [Symbol] state of current row
150
161
  ## @return [Array] color_pair and attrib constant
151
162
  def color_of_row index, state
152
163
  arr = super
data/lib/umbra/pad.rb CHANGED
@@ -7,7 +7,7 @@
7
7
  * Author: jkepler
8
8
  * Date: 2018-03-28 14:30
9
9
  * License: MIT
10
- * Last update: 2018-06-01 12:40
10
+ * Last update: 2018-06-02 10:22
11
11
 
12
12
  == CHANGES
13
13
  == Todo
@@ -21,6 +21,7 @@
21
21
  =end
22
22
  require 'ffi-ncurses'
23
23
 
24
+ module Umbra
24
25
  class Pad
25
26
 
26
27
  # You may pass height, width, row and col for creating a window otherwise a fullscreen window
@@ -346,3 +347,4 @@ if __FILE__ == $PROGRAM_NAME
346
347
  FFI::NCurses.curs_set 1 # cursor visible again
347
348
  end
348
349
  end
350
+ end # module
@@ -1,26 +1,33 @@
1
1
  # ----------------------------------------------------------------------------- #
2
2
  # File: radiobutton.rb
3
3
  # Description: a member of a group of buttons, only one can be selected at a time.
4
- # Author: j kepler http://github.com/mare-imbrium/canis/
4
+ # Author: j kepler http://github.com/mare-imbrium/
5
5
  # Date: 2018-04-02 - 10:37
6
6
  # License: MIT
7
- # Last update: 2018-06-01 12:31
7
+ # Last update: 2018-06-03 11:27
8
8
  # ----------------------------------------------------------------------------- #
9
9
  # radiobutton.rb Copyright (C) 2012-2018 j kepler
10
10
 
11
11
  module Umbra
12
12
  ##
13
- # A selectable button that has a text value. It is based on a Variable that
14
- # is shared by other radio buttons. Only one is selected at a time, unlike checkbox
15
- # +text+ is the value to display, which can include an ampersand for a hotkey
16
- # +value+ is the value returned if selected, which usually is similar to text (or a short word)
13
+ # A selectable button that has a text value. It is linked to a +ButtonGroup+ that
14
+ # is shared by other radio buttons. Only one is selected at a time, unlike +Checkbox+.
15
+ # +text+ is the value to display, which can include an ampersand for a hotkey.
16
+ # +value+ is the value returned if selected, which usually is similar to text (or a short word).
17
17
  # +width+ is helpful if placing the brackets to right of text, used to align round brackets
18
18
  # By default, radio buttons place the button on the left of the text.
19
19
  #
20
- # Typically, the variable's update_command is passed a block to execute whenever any of the
20
+ # Typically, the +ButtonGroup+'s `command` is passed a block to execute whenever any of the
21
21
  # radiobuttons of this group is fired.
22
-
22
+ # @example
23
+ # radio1 = RadioButton.new text: "Red", value: "Red", row: 10, col: 20
24
+ # radio2 = RadioButton.new text: "Blue", value: "Blue", row: 11, col: 20
25
+ # group = ButtonGroup.new "Color"
26
+ # group.add(radio1).add(radio2)
27
+ # form.add_widget radio1, radio2
28
+ #
23
29
  class RadioButton < ToggleButton
30
+ # @param align_right [true, false] set whether button should be on right of text, default false.
24
31
  attr_property :align_right # the button will be on the right
25
32
  attr_accessor :button_group # group that this button belongs to.
26
33
 
@@ -6,7 +6,7 @@ require 'umbra/button'
6
6
  # Author: j kepler http://github.com/mare-imbrium/umbra/
7
7
  # Date: 2018-03-17 - 22:50
8
8
  # License: MIT
9
- # Last update: 2018-05-27 14:21
9
+ # Last update: 2018-06-03 09:33
10
10
  # ----------------------------------------------------------------------------- #
11
11
  # togglebutton.rb Copyright (C) 2018 j kepler
12
12
  #
@@ -14,25 +14,30 @@ require 'umbra/button'
14
14
  module Umbra
15
15
 
16
16
  # A button that may be switched off an on.
17
- # Extended by RadioButton and checkbox.
17
+ # Extended by `RadioButton` and `Checkbox`.
18
18
  # WARNING, pls do not override +text+ otherwise checkboxes etc will stop functioning.
19
19
  # TODO: add editable here and prevent toggling if not so.
20
20
  class ToggleButton < Button
21
- # text to display for on value and off value
21
+
22
+ # set or get text to display for on value and off value
22
23
  attr_accessor :onvalue, :offvalue
23
- # boolean, which value to use currently, onvalue or offvalue
24
+
25
+ # @param value [true, false] Which value to use currently, onvalue or offvalue
26
+ # @return [true, false] current value
24
27
  attr_property :value
25
- # characters to use for surround, array, default square brackets
26
- #attr_property :surround_chars already in button
27
- # 2018-04-02 - removing variable
28
+
28
29
  # background to use when selected, if not set then default
29
30
  # 2018-04-02 - unused so commenting off. color_pair is not used here or in checkbox
30
31
  #attr_property :selected_color_pair
31
32
 
33
+ ## Just calls super.
34
+ ## @param config [Hash] config values such as row, col, onvalue, offvalue and value.
32
35
  def initialize config={}, &block
33
36
  super
34
37
 
35
38
  end
39
+
40
+ # @return [onvalue, offvalue] returns on or off value depending on +@value+.
36
41
  def getvalue
37
42
  @value ? @onvalue : @offvalue
38
43
  end
@@ -42,9 +47,11 @@ module Umbra
42
47
  # added for some standardization 2010-09-07 20:28
43
48
  # alias :text :getvalue # NEXT VERSION
44
49
  # change existing text to label
50
+
51
+
45
52
  ##
46
53
  # is the button on or off
47
- # added 2008-12-09 19:05
54
+ # @return [true, false] returns +@value+, has the button been checked or not.
48
55
  def checked?
49
56
  @value
50
57
  end
@@ -62,8 +69,8 @@ module Umbra
62
69
  @surround_chars[0] + buttontext + @surround_chars[1]
63
70
  end
64
71
 
65
- # toggle button handle key
66
- # @param [int] key received
72
+ # toggle button handle key. Handles only `space` (32), all others are passed to parent classes.
73
+ # @param ch [Integer] key received
67
74
  #
68
75
  def handle_key ch
69
76
  if ch == 32
@@ -75,12 +82,14 @@ module Umbra
75
82
  end
76
83
 
77
84
  ##
78
- # toggle the button value
85
+ # toggle the button value. Calls +fire+.
79
86
  def toggle
80
87
  fire
81
88
  end
82
89
 
83
- # called on :PRESS event
90
+ # Toggles the button's value.
91
+ # Called by +toggle+ (when users pressed +SPACE+).
92
+ # Calls :PRESS event
84
93
  def fire
85
94
  checked(!@value)
86
95
  #@item_event = ItemEvent.new self, self if @item_event.nil?
@@ -89,7 +98,8 @@ module Umbra
89
98
  ## 2018-05-27 - trying to use self in most cases. Above was not needed.
90
99
  fire_handler :PRESS, self
91
100
  end
92
- ##
101
+
102
+
93
103
  # set the value to true or false
94
104
  # user may programmatically want to check or uncheck
95
105
  # ## duplicate of value ??? 2018-05-26 -
data/lib/umbra/version.rb CHANGED
@@ -1,3 +1,3 @@
1
1
  module Umbra
2
- VERSION = "0.1.2"
2
+ VERSION = "0.1.3"
3
3
  end
data/lib/umbra/widget.rb CHANGED
@@ -9,6 +9,10 @@ require 'umbra/keymappinghandler' # for bind_key and process_key
9
9
 
10
10
  class Module # {{{
11
11
 
12
+ # dsl method for declaring attribute setters which result in widget
13
+ # being repainted. Also, fire a #fire_property_change event.
14
+ # @param symbols [Symbol] value to be set
15
+ # @return [Widget] self
12
16
  def attr_property(*symbols)
13
17
  symbols.each { |sym|
14
18
  class_eval %{
@@ -37,58 +41,76 @@ class Module # {{{
37
41
  end # def
38
42
  end # module }}}
39
43
  module Umbra
40
- class FieldValidationException < RuntimeError
41
- end
42
- class Widget
44
+
45
+ ## Exception thrown by Field if validation fails
46
+ class FieldValidationException < RuntimeError
47
+ end
48
+
49
+
50
+ ## Parent class of all widgets/controls that are displayed on the screen/window
51
+ ## and are managed by +Form+.
52
+ ## Many attributes use `attr_property` instead of `attr_accessor`. This is used for elements
53
+ ## that must repaint the widget whenever updated. They also fire a property change event.
54
+ ## These properties may not show up in the generated RDoc.
55
+ ## This class will not be instantiated by programs, only its subclasses will be.
56
+ ## Widget registers `:ENTER` `:LEAVE` `:CHANGED` and `:PROPERTY_CHANGE` events.
57
+ ## Widget defines three states: `:NORMAL` `:HIGHLIGHTED` and `:SELECTED`.
58
+ ## `HIGHLIGHTED` refers to the single widget that is focussed.
59
+ ## `SELECTED` is only for Togglebuttons that may be in `SELECTED` state.
60
+ ## `NORMAL` state is for all others (the default state).
61
+ class Widget
43
62
  include EventHandler
44
63
  include KeyMappingHandler
45
- # common interface for text related to a field, label, textview, button etc
46
- attr_property :text
47
- attr_property :width, :height ## width and height of widget
48
-
49
- # foreground and background colors when focussed. Currently used with buttons and field
50
- # Form checks and repaints on entry if these are set.
51
- attr_property :highlight_color_pair
52
- attr_property :highlight_attr
53
-
54
- # NOTE: 2018-03-04 - user will have to call repaint_required if he changes color or coordinates.
55
- attr_accessor :col # location of object
56
- attr_writer :row # location of object
57
- # moved to a method which calculates color 2011-11-12
58
- attr_property :color_pair # instead of colors give just color_pair
59
- attr_property :attr # attribute bold, normal, reverse
60
- attr_accessor :name # name to refr to or recall object by_name
61
- attr_accessor :curpos # cursor position inside object - column, not row.
62
- #attr_reader :config # can be used for popping user objects too. NOTE unused
63
- #attr_accessor :form # made accessor 2008-11-27 22:32 so menu can set
64
- attr_accessor :graphic # window which should be set by form when adding 2018-03-19
65
- attr_accessor :state # normal, selected, highlighted
66
- attr_reader :row_offset, :col_offset # where should the cursor be placed to start with
67
- attr_property :visible # boolean # 2008-12-09 11:29
68
- # if changing focusable property of a field after form creation, you may need to call
69
- # pack again, or atl east update_focusables
70
- attr_reader :focusable # boolean can this get focus # 2018-03-21 - 23:13
71
- # 2018-03-04 - we should use modified as accessor unless it is due to setting forms modified
72
- # 2018-03-22 - making it accessor
73
- attr_accessor :modified # boolean, value modified or not (moved from field 2009-01-18 00:14 )
74
- #attr_accessor :help_text # added 2009-01-22 17:41 can be used for status/tooltips
64
+
65
+ ## @param text [String] common interface for text related to a field, label, textview, button etc
66
+ attr_property :text
67
+ ## @param width [Integer] width of widget, same for +height+
68
+ attr_property :width, :height ## width and height of widget
69
+
70
+ # foreground and background colors when focussed. Currently used with buttons and field
71
+ # Form checks and repaints on entry if these are set.
72
+ ## @param highlight_color_pair [Integer] color pair of widget when focussed
73
+ attr_property :highlight_color_pair
74
+ ## @param highlight_attr [Integer] visual attribute of widget when focussed
75
+ attr_property :highlight_attr
76
+
77
+ attr_accessor :col # location of object (column)
78
+ attr_writer :row # location of object
79
+
80
+ ## @param color_pair [Integer] color pair of widget (when not focussed)
81
+ attr_property :color_pair # instead of colors give just color_pair
82
+ ## @param attr [Integer] visual attribute of widget when not focussed
83
+ attr_property :attr # attribute bold, normal, reverse
84
+
85
+ attr_accessor :name # documentation, used in print statements
86
+ attr_accessor :curpos # cursor position inside object - column, not row.
87
+
88
+
89
+ attr_accessor :graphic # window which should be set by form when adding
90
+ attr_accessor :state # :NORMAL, :SELECTED, :HIGHLIGHTED
91
+ attr_reader :row_offset, :col_offset # where should the cursor be placed to start with
92
+
93
+ ## @param attr [true, false] should the widget be displayed or not
94
+ attr_property :visible
95
+
96
+ attr_reader :focusable # boolean can this get focus or not.
97
+
98
+ attr_accessor :modified # boolean, value modified or not
75
99
 
76
100
  #attr_accessor :parent_component # added 2010-01-12 23:28 BUFFERED - to bubble up
77
101
 
78
- # NOTE state takes care of this and is set by form. boolean 2018-05-26 - commented since unused
79
- #attr_reader :focussed # is this widget in focus, so they may paint differently
80
102
 
81
- # height percent and width percent used in stacks and flows.
82
- #attr_accessor :height_pc, :width_pc # may bring this back
103
+ # @return [String] descriptions for each key set in _key_map, NOT YET displayed TODO
104
+ attr_reader :key_label
83
105
 
84
- # descriptions for each key set in _key_map
85
- # 2018-03-07 - NOT_SURE
86
- attr_reader :key_label
87
- attr_reader :handler # event handler
88
- # adding as attr_accessor 2018-03-22 -
89
- # is a repaint required or not, boolean
90
- attr_accessor :repaint_required
106
+ # @return [Hash] event handler hash containing key and block association
107
+ attr_reader :handler
91
108
 
109
+ # @param repaint_required [true, false] is a repaint required or not, boolean
110
+ attr_accessor :repaint_required
111
+
112
+ # @param aconfig [Hash] initialization parameters such as row, col, height, width, color_pair, text.
113
+ # @yield [Widget] self
92
114
  def initialize aconfig={}, &block
93
115
  @row_offset ||= 0
94
116
  @col_offset ||= 0
@@ -112,24 +134,25 @@ class Widget
112
134
  end
113
135
  end
114
136
 
115
- def variable_set var, val
137
+ def variable_set var, val #:nodoc:
116
138
  send("#{var}=", val)
117
139
  end
118
- def init_vars
140
+
141
+ ## Initialise internal variables
142
+ def init_vars #:nodoc:
119
143
  # just in case anyone does a super. Not putting anything here
120
144
  # since i don't want anyone accidentally overriding
121
145
  end
122
146
 
123
- # modified
124
- ##
125
- # typically read will be overridden to check if value changed from what it was on enter.
126
- # getter and setter for modified (added 2009-01-18 12:31 )
147
+ # Widget modified or not.
148
+ # typically will be overridden to check if value changed from what it was on enter.
149
+ # @return [true, false] modified since on_enter or not
127
150
  def modified?
128
151
  @modified
129
152
  end
130
153
 
131
154
  # triggered whenever a widget is entered.
132
- # NOTE should we not fix cursor at this point (on_enter) ?
155
+ ## Will invoke `:ENTER` handler/event
133
156
  def on_enter
134
157
  ## Form has already set this, and set modified to false
135
158
  @state = :HIGHLIGHTED # duplicating since often these are inside containers
@@ -138,7 +161,9 @@ class Widget
138
161
  fire_handler :ENTER, self
139
162
  end
140
163
  end
164
+
141
165
  ## Called when user exits a widget
166
+ ## Will invoke `:LEAVE` handler/event
142
167
  def on_leave
143
168
  @state = :NORMAL # duplicating since often these are inside containers
144
169
  #@focussed = false
@@ -146,25 +171,32 @@ class Widget
146
171
  fire_handler :LEAVE, self
147
172
  end
148
173
  end
174
+
175
+
149
176
  ##
150
- # @return row and col of a widget where painting data actually starts
151
- # row and col is where a widget starts. offsets usually take into account borders.
177
+ # Returns row and col is where a widget starts. offsets usually take into account borders.
152
178
  # the offsets typically are where the cursor should be positioned inside, upon on_enter.
179
+ # @return [Integer] row of widget where painting data actually starts
180
+ # @return [Integer] col of widget where painting data actually starts
153
181
  def rowcol
154
182
  return self.row+@row_offset, self.col+@col_offset
155
183
  end
156
- ## return the value of the widget.
184
+
185
+ ## @return [String] the value of the widget.
157
186
  def getvalue
158
187
  @text
159
188
  end
189
+
160
190
  ##
161
191
  # Am making a separate method since often value for print differs from actual value
192
+ ## @return [String] the value of the widget for painting.
162
193
  def getvalue_for_paint
163
194
  getvalue
164
195
  end
196
+
165
197
  ##
166
- # default repaint method. Called by form for all widgets.
167
- # widget does not have display_length.
198
+ # Default repaint method. Called by form for all widgets.
199
+ # widget does not have display_length. This should be overriden by concrete subclasses.
168
200
  def repaint
169
201
  r,c = rowcol
170
202
  $log.debug("widget repaint : r:#{r} c:#{c} col:#{@color_pair}" )
@@ -174,25 +206,18 @@ class Widget
174
206
  @graphic.printstring r, c, "%-*s" % [len, value], acolor, attr()
175
207
  end
176
208
 
177
- def destroy
178
- raise "what is this dong here still SHOULD Not be CALLED"
179
- $log.debug "DESTROY : widget #{@name} "
180
- panel = @window.panel
181
- Ncurses::Panel.del_panel(panel.pointer) if !panel.nil?
182
- @window.delwin if !@window.nil?
183
- end
184
209
 
185
- # puts cursor on correct row.
186
- def set_form_row
210
+ def set_form_row #:nodoc:
187
211
  raise "uncalled set_form_row"
188
212
  r, c = rowcol
189
213
  setrowcol row, nil # does not exist any longer
190
214
  end
215
+
191
216
  # set cursor on correct column, widget
192
217
  # Ideally, this should be overriden, as it is not likely to be correct.
193
218
  # NOTE: this is okay for some widgets but NOT for containers
194
219
  # that will call their own components SFR and SFC
195
- #Currently, Field has overriden this. +setrowcol+ does not exist any longer.
220
+ # Currently, Field has overriden this. +setrowcol+ does not exist any longer.
196
221
  def set_form_col col1=@curpos
197
222
  @curpos = col1 || 0 # 2010-01-14 21:02
198
223
  #@form.col = @col + @col_offset + @curpos
@@ -201,8 +226,11 @@ class Widget
201
226
  setrowcol nil, c
202
227
  end
203
228
 
204
- ##
205
- # to be added at end of handle_key of widgets so instlalled actions can be checked
229
+ # Handle keys entered by user when this widget is focussed. Executes blocks bound to given key or
230
+ # else returns control to +Form+.
231
+ # To be called at end of `handle_key` of widgets so installed actions can be executed.
232
+ # @param ch [Integer] keystroke entered
233
+ # @return [0, :UNHANDLED] return value of block executed for given keystroke
206
234
  def handle_key(ch)
207
235
  ret = process_key ch, self
208
236
  return :UNHANDLED if ret == :UNHANDLED
@@ -211,23 +239,23 @@ class Widget
211
239
 
212
240
  # is the entire widget to be repainted including things like borders and titles
213
241
  # earlier took a default of true, now must be explicit. Perhaps, not used currently.
214
- def repaint_all(tf)
242
+ def repaint_all(tf) #:nodoc:
215
243
  # NOTE NOT USED
216
244
  raise " not used repaint all"
217
245
  @repaint_all = tf
218
246
  @repaint_required = tf
219
247
  end
220
- # shortcut for users to indicate that a widget should be redrawn since some property has been changed.
221
- # Now that I have created attr_property this may not be needed
248
+
249
+ # Shortcut for users to indicate that a widget should be redrawn since some property has been changed.
250
+ # Now that I have created +attr_property+ this may not be needed
222
251
  def touch
223
252
  @repaint_required = true
224
253
  end
225
254
 
226
255
 
227
- # a general method for all widgets to override with their favorite or most meaninful event
228
- # Ideally this is where the block in the constructor should land up.
229
- # @since 1.5.0 2011-11-21
230
- # 2018-03-08 - NOT_SURE
256
+ ## A general method for all widgets to override with their favorite or most meaninful event
257
+ ## This is a convenience method. Widgets that have a `PRESS` event will bind the given block to PRESS,
258
+ ## all others to the `CHANGED` event.
231
259
  def command *args, &block
232
260
  if event? :PRESS
233
261
  bind_event :PRESS, *args, &block
@@ -235,24 +263,31 @@ class Widget
235
263
  bind_event :CHANGED, *args, &block
236
264
  end
237
265
  end
238
- def _form=(aform)
266
+
267
+ def _form=(aform) #:nodoc:
239
268
  @_form = aform
240
269
  end
270
+
271
+ ## set focusable property to true or false
272
+ ## Also updates the focusables array.
241
273
  def focusable=(bool)
242
274
  #$log.debug " inside focusable= with #{bool} "
243
275
  @focusable = bool
244
276
  @_form.update_focusables if @_form
245
277
  end
246
278
 
247
- ## TODO maybe check for decimal between 0 and 1 which will be percentage of width
279
+ ## Get width of widget, treating negatives as relative width.
280
+ ## @return [Integer, nil] returns width of widget
248
281
  def width
249
282
  return nil unless @width ## this is required otherwise checking for nil will fail
250
283
  if @width < 0
251
284
  return ( FFI::NCurses.COLS + @width ) - self.col + 1
252
- #return ( FFI::NCurses.COLS + @width ) #- self.col + 1
253
285
  end
254
286
  @width
255
287
  end
288
+
289
+ ## Get height of widget. Used only for +Multline+ widgets
290
+ ## @return [Integer, nil] height of widget if applicable
256
291
  def height
257
292
  return nil unless @height
258
293
  if @height < 0
@@ -261,6 +296,9 @@ class Widget
261
296
  end
262
297
  @height
263
298
  end
299
+
300
+ ## get row of widget
301
+ ## @return [Integer, nil] row of widget
264
302
  def row
265
303
  return nil unless @row
266
304
  if @row < 0
@@ -268,7 +306,6 @@ class Widget
268
306
  end
269
307
  @row
270
308
  end
271
- #
272
- ## ADD HERE WIDGET
273
- end #
309
+
310
+ end # class
274
311
  end # module
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ncumbra
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.2
4
+ version: 0.1.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - kepler
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2018-06-01 00:00:00.000000000 Z
11
+ date: 2018-06-03 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: bundler