typr 1.8.0 → 1.9.0

data/lib/stack.rb

@@ -17,10 +17,25 @@ module Typr
   #   KEY_HOME / KEY_END           (jump to first or last pageable row)
 
   class Stack < Space
-    ## Widget configuration. +left+, +top+, +right+, +bottom+ set the viewport; see {Space}.
-    ## +alternate+ toggles striped rows (+:grey10+ background alternating with the default bg).
+    ##
+    # Widget configuration and state: +left+/+top+/+right+/+bottom+ set
+    # the viewport (see {Space}), +alternate+ toggles striped rows
+    # (+:grey10+ against the default bg), +start+ is the scroll offset,
+    # +keymap+ maps key sequences to methods, +selected+ holds picked ids
+    # per type, and +header+ is the top-bar label.
+    #
+    #   stack.start = 3
+    #   stack.header = "Title"
 
     attr_accessor :start, :keymap, :selected, :header
+    ##
+    # +separator+ is the gap between columns, +hints+ the hint characters,
+    # +hints_start+ the offset of the current hint chunk ({#cycle}), and
+    # +modifier+ is +:alt+ after an Alt-digit hint press, +nil+ otherwise.
+    #
+    #   stack.hints = "1234567890"
+    #   stack.modifier   #=> :alt  (after picking with Alt+digit)
+
     attr_accessor :separator, :hints, :hints_start, :modifier
 
     ##
@@ -174,39 +189,57 @@ module Typr
       return response
     end
 
-    ## Scroll to the top of the dataset.
+    ##
+    # Scroll to the top of the dataset.
     #
-    #   stack.to_top
+    #   stack.to_top   # @start => 0
+    #
+    # @return [nil]
 
     def to_top; @start = 0; return end
 
-    ## Scroll to the bottom pageable position (last row minus viewport height).
+    ##
+    # Scroll to the bottom pageable position (last row minus viewport height).
+    #
+    #   stack.to_bottom   # @start => rows - height
     #
-    #   stack.to_bottom
+    # @return [nil]
 
     def to_bottom; @start = rows - height; return end
 
-    ## Step down by one row.
+    ##
+    # Step down by one row.
+    #
+    #   stack.down   # @start += 1
     #
-    #   stack.down
+    # @return [nil]
 
     def down; @start += 1; return end
 
-    ## Step up by one row.
+    ##
+    # Step up by one row.
     #
-    #   stack.up
+    #   stack.up   # @start -= 1
+    #
+    # @return [nil]
 
     def up; @start -= 1; return end
 
-    ## Jump down by one viewport of rows.
+    ##
+    # Jump down by one viewport of rows.
+    #
+    #   stack.page_down   # @start += height
     #
-    #   stack.page_down
+    # @return [nil]
 
     def page_down; @start += height; return end
 
-    ## Jump up by one viewport of rows.
+    ##
+    # Jump up by one viewport of rows.
+    #
+    #   stack.page_up   # @start -= height
     #
-    #   stack.page_up
+    # @return [nil]
 
     def page_up; @start -= height; return end
 
@@ -230,7 +263,14 @@ module Typr
     #   stack.pick :column, 3     # pick a column in row 3
     #   stack.pick "rows"         # multi-select rows
     #
+    # Pressing Alt with a hint digit (ESC + digit) picks that hint row and
+    # sets +modifier+ to +:alt+ for the caller.
+    #
     # Mouse: left-click a row to pick it; wheel up/down scrolls the page.
+    #
+    # @param type [Symbol, String] picker type (table above)
+    # @param row [Integer] starting row for column/field hints
+    # @return [Integer, Array, nil] picked id(s), selection on confirm, or nil on abort
 
     def pick type = :row, row=0 #, key=nil
       type = type.to_s
@@ -298,6 +338,14 @@ module Typr
       return
     end
 
+    ##
+    # Walk the hint characters backwards by one chunk (mirror of {#cycle}),
+    # wrapping to the last full chunk before the start of the list.
+    #
+    #   stack.cycle_back   # hints_start -= hints.size (wraps at 0)
+    #
+    # @return [nil]
+
     def cycle_back
       max = [height-1, rows-1+headspace].min
       @hints_start -= @hints.size