rndk 0.1.0 → 0.2.0

data/lib/rndk/entry.rb

@@ -2,11 +2,118 @@ require 'rndk'
 
 module RNDK
 
-  class ENTRY < RNDK::Widget
+  # A text-entry box with a label and an entry field.
+  #
+  # ## Keybindings
+  #
+  # Left Arrow::  Moves the cursor to the left.
+  # CTRL-B::      Moves the cursor to the left.
+  # Right Arrow:: Moves the cursor to the right.
+  # CTRL-F::      Moves the cursor to the right.
+  # Delete::      Deletes the character at the cursor.
+  # Backspace::   Deletes the character before cursor,
+  #               moves cursor left.
+  # CTRL-V::      Pastes from the paste buffer into the widget
+  # CTRL-X::      Cuts the contents from the widget into the
+  #               paste buffer.
+  # CTRL-Y::      Copies the contents of the widget into the
+  #               paste buffer.
+  # CTRL-U::      Erases the contents of the widget.
+  # CTRL-A::      Moves the cursor to the beginning of the entry field.
+  # CTRL-E::      Moves the cursor to the end of the entry field.
+  # CTRL-T::      Transposes the character under the cursor
+  #               with the character to the right.
+  # Return::      Exits the widget and returns the text typed
+  #               into the field.
+  #               It also sets the widget data exitType to `:NORMAL`.
+  # Tab::         Exits the widget and returns the text typed
+  #               into the field.
+  #               It also sets the widget data exitType to `:NORMAL`.
+  # Escape::      Exits the widget and returns `nil`.
+  #               It also sets the widget data exitType to `:ESCAPE_HIT`.
+  # Ctrl-L::      Refreshes the screen.
+  #
+  # ## Behavior
+  #
+  # When passing the `disp_type` argument to Entry#initialize,
+  # you can modify the Entry behavior when receiving chars
+  # from the user.
+  #
+  # Send one of those for an action:
+  #
+  # `:CHAR`::     Only accepts alphabetic characters.
+  # `:LCHAR`::    Only accepts alphabetic characters.
+  #               Maps the character to lower case when a character
+  #               has been accepted.
+  # `:UCHAR`::    Only accepts alphabetic characters.
+  #               Maps the  character to upper case when a character
+  #               has been accepted.
+  # `:HCHAR`::    Only accepts alphabetic characters.  Displays
+  #               a period  (.)  when  a  character  has  been
+  #               accepted.
+  # `:UHCHAR`::   Only accepts alphabetic characters.  Displays
+  #               a period (.) and maps the character to upper
+  #               case when a character has been accepted.
+  # `:LHCHAR`::   Only accepts alphabetic characters.  Displays
+  #               a period (.) and maps the character to lower
+  #               case when a character has been accepted.
+  # `:INT`::      Only accepts numeric characters.
+  # `:HINT`::     Only accepts numeric characters.  Displays  a
+  #               period   (.)  when   a  character     has  been
+  #               accepted.
+  # `:MIXED`::    Accepts any character types.
+  # `:LMIXED`::   Accepts any character types.  Maps the  char-
+  #               acter  to lower case when an alphabetic char-
+  #               acter has been accepted.
+  # `:UMIXED`::   Accepts any character types.  Maps the  char-
+  #               acter  to upper case when an alphabetic char-
+  #               acter has been accepted.
+  # `:HMIXED`::   Accepts  any  character  types.   Displays  a
+  #               period   (.)   when   a  character     has  been
+  #               accepted.
+  # `:LHMIXED`::  Accepts  any  character  types.   Displays  a
+  #               period  (.)  and  maps the character to lower
+  #               case when a character has been accepted.
+  # `:UHMIXED`::  Accepts  any  character  types.   Displays  a
+  #               period  (.)  and  maps the character to upper
+  #               case when a character has been accepted.
+  # `:VIEWONLY`:: Uneditable field.
+  #
+  class Entry < Widget
     attr_accessor :info, :left_char, :screen_col
     attr_reader :win, :box_height, :box_width, :max, :field_width
     attr_reader :min, :max
 
+
+    # Creates an Entry Widget.
+    #
+    # ## Arguments
+    #
+    # * `xplace` is the x position - can be an integer or
+    #   `RNDK::LEFT`, `RNDK::RIGHT`, `RNDK::CENTER`.
+    # * `yplace` is the y position - can be an integer or
+    #   `RNDK::TOP`, `RNDK::BOTTOM`, `RNDK::CENTER`.
+    # * `title` can be more than one line - just split them
+    #   with `\n`s.
+    # * `label` is the String that will appear on the label
+    #   of the Entry field.
+    # * `field_attr` is the attribute/color of the characters
+    #   that are typed in.
+    # * `filler_char` is the character to display on the
+    #   empty spaces in the entry field.
+    # * `disp_type` tells how the entry field will behave.
+    #   _See main Entry documentation_.
+    # * `f_width` is the width of the field. It it's 0,
+    #   will be created with full width of the screen.
+    #   If it's a negative value, will create with full width
+    #   minus that value.
+    # * `min` is the minimum number of characters the user
+    #   must insert before can exit the entry field.
+    # * `max` is the maximum number of characters the user
+    #   can enter on the entry field.
+    # * `box` if the Widget is drawn with a box outside it.
+    # * `shadow` turns on/off the shadow around the Widget.
+    #
     def initialize(rndkscreen,
                    xplace,
                    yplace,
@@ -21,20 +128,23 @@ module RNDK
                    box,
                    shadow)
       super()
-      parent_width = Ncurses.getmaxx rndkscreen.window
+
+      parent_width  = Ncurses.getmaxx rndkscreen.window
       parent_height = Ncurses.getmaxy rndkscreen.window
+
       field_width = f_width
-      box_width = 0
+      box_width   = 0
+
       xpos = xplace
       ypos = yplace
 
-      self.set_box(box)
-      box_height = @border_size * 2 + 1
+      self.set_box box
+      box_height = @border_size*2 + 1
 
       # If the field_width is a negative value, the field_width will be
       # COLS-field_width, otherwise the field_width will be the given width.
       field_width = RNDK.setWidgetDimension(parent_width, field_width, 0)
-      box_width = field_width + 2 * @border_size
+      box_width = field_width + 2*@border_size
 
       # Set some basic values of the entry field.
       @label = 0
@@ -128,16 +238,16 @@ module RNDK
           # Update the screen and pointer
           if entry.screen_col != entry.field_width - 1
             front = (entry.info[0...(entry.screen_col + entry.left_char)] or '')
-            back = (entry.info[(entry.screen_col + entry.left_char)..-1] or '')
+            back  = (entry.info[(entry.screen_col + entry.left_char)..-1] or '')
+
             entry.info = front + plainchar.chr + back
             entry.screen_col += 1
+
           else
             # Update the character pointer.
             entry.info << plainchar
             # Do not update the pointer if it's the last character
-            if entry.info.size < entry.max
-              entry.left_char += 1
-            end
+            entry.left_char += 1 if (entry.info.size < entry.max)
           end
 
           # Update the entry field.
@@ -147,17 +257,25 @@ module RNDK
 
       # Do we want a shadow?
       if shadow
-        @shadow_win = Ncurses.subwin(rndkscreen.window, box_height, box_width,
-            ypos + 1, xpos + 1)
+        @shadow_win = Ncurses.subwin(rndkscreen.window,
+                                     box_height,
+                                     box_width,
+                                     ypos + 1,
+                                     xpos + 1)
       end
 
-      rndkscreen.register(:ENTRY, self)
+      rndkscreen.register(:entry, self)
     end
 
-    # This means you want to use the given entry field. It takes input
-    # from the keyboard, and when it's done, it fills the entry info
-    # element of the structure with what was typed.
-    def activate(actions)
+    # Activates the Entry Widget, letting the user interact with it.
+    #
+    # `actions` is an Array of characters. If it's non-null,
+    # will #inject each char on it into the Widget.
+    #
+    # @return The text currently inside the entry field (and
+    #         `exit_type` will be `:NORMAL`) or `nil` (and
+    #         `exit_type` will be `:ESCAPE_HIT`).
+    def activate(actions=[])
       input = 0
       ret = 0
 
@@ -192,24 +310,8 @@ module RNDK
       end
     end
 
-    def setPositionToEnd
-      if @info.size >= @field_width
-        if @info.size < @max
-          char_count = @field_width - 1
-          @left_char = @info.size - char_count
-          @screen_col = char_count
-        else
-          @left_char = @info.size - @field_width
-          @screen_col = @info.size - 1
-        end
-      else
-        @left_char = 0
-        @screen_col = @info.size
-      end
-    end
-
-    # This injects a single character into the widget.
-    def inject(input)
+    # @see Widget#inject
+    def inject input
       pp_return = 1
       ret = 1
       complete = false
@@ -221,25 +323,29 @@ module RNDK
       self.drawField
 
       unless @pre_process_func.nil?
-        pp_return = @pre_process_func.call(:ENTRY, self,
+        pp_return = @pre_process_func.call(:entry, self,
             @pre_process_data, input)
       end
 
       # Should we continue?
       if pp_return != 0
+
         # Check a predefined binding
-        if self.checkBind(:ENTRY, input)
+        if self.checkBind(:entry, input)
           complete = true
+
         else
           curr_pos = @screen_col + @left_char
 
           case input
           when Ncurses::KEY_UP, Ncurses::KEY_DOWN
             RNDK.beep
+
           when Ncurses::KEY_HOME
             @left_char = 0
             @screen_col = 0
             self.drawField
+
           when RNDK::TRANSPOSE
             if curr_pos >= @info.size - 1
               RNDK.beep
@@ -249,9 +355,11 @@ module RNDK
               @info[curr_pos + 1] = holder
               self.drawField
             end
+
           when Ncurses::KEY_END
             self.setPositionToEnd
             self.drawField
+
           when Ncurses::KEY_LEFT
             if curr_pos <= 0
               RNDK.beep
@@ -263,6 +371,7 @@ module RNDK
               @screen_col -= 1
               Ncurses.wmove(@field_win, 0, @screen_col)
             end
+
           when Ncurses::KEY_RIGHT
             if curr_pos >= @info.size
               RNDK.beep
@@ -275,6 +384,7 @@ module RNDK
               @screen_col += 1
               Ncurses.wmove(@field_win, 0, @screen_col)
             end
+
           when Ncurses::KEY_BACKSPACE, Ncurses::KEY_DC
             if @disp_type == :VIEWONLY
               RNDK.beep
@@ -310,11 +420,13 @@ module RNDK
           when RNDK::KEY_ESC
             self.set_exit_type(input)
             complete = true
+
           when RNDK::ERASE
             if @info.size != 0
               self.clean
               self.drawField
             end
+
           when RNDK::CUT
             if @info.size != 0
               @@g_paste_buffer = @info.clone
@@ -323,19 +435,22 @@ module RNDK
             else
               RNDK.beep
             end
+
           when RNDK::COPY
             if @info.size != 0
               @@g_paste_buffer = @info.clone
             else
               RNDK.beep
             end
+
           when RNDK::PASTE
             if @@g_paste_buffer != 0
-              self.setValue(@@g_paste_buffer)
+              self.set_text(@@g_paste_buffer)
               self.drawField
             else
               RNDK.beep
             end
+
           when RNDK::KEY_TAB, RNDK::KEY_RETURN, Ncurses::KEY_ENTER
             if @info.size >= @min
               self.set_exit_type(input)
@@ -344,9 +459,11 @@ module RNDK
             else
               RNDK.beep
             end
+
           when Ncurses::ERR
             self.set_exit_type(input)
             complete = true
+
           when RNDK::REFRESH
             @screen.erase
             @screen.refresh
@@ -356,7 +473,7 @@ module RNDK
         end
 
         if !complete && !(@post_process_func.nil?)
-          @post_process_func.call(:ENTRY, self, @post_process_data, input)
+          @post_process_func.call(:entry, self, @post_process_data, input)
         end
       end
 
@@ -368,15 +485,14 @@ module RNDK
       return ret
     end
 
-    # This moves the entry field to the given location.
+    # @see Widget#move
     def move(xplace, yplace, relative, refresh_flag)
       windows = [@win, @field_win, @label_win, @shadow_win]
-      self.move_specific(xplace, yplace, relative, refresh_flag,
-          windows, [])
+
+      self.move_specific(xplace, yplace, relative, refresh_flag, windows, [])
     end
 
-    # This erases the information in the entry field and redraws
-    # a clean and empty entry field.
+    # Clears the text from the entry field.
     def clean
       width = @field_width
 
@@ -393,20 +509,17 @@ module RNDK
       Ncurses.wrefresh @field_win
     end
 
-    # This draws the entry field.
-    def draw(box)
+    # Draws the Widget on the Screen.
+    #
+    # If `box` is true, it is drawn with a box.
+    def draw box
       # Did we ask for a shadow?
-      unless @shadow_win.nil?
-        Draw.drawShadow @shadow_win
-      end
+      Draw.drawShadow @shadow_win unless @shadow_win.nil?
 
       # Box the widget if asked.
-      if box
-        Draw.drawObjBox(@win, self)
-      end
+      Draw.drawObjBox(@win, self) if box
 
       self.drawTitle @win
-
       Ncurses.wrefresh @win
 
       # Draw in the label to the widget.
@@ -418,35 +531,14 @@ module RNDK
                          RNDK::HORIZONTAL,
                          0,
                          @label_len)
+
         Ncurses.wrefresh @label_win
       end
 
       self.drawField
     end
 
-    def drawField
-      # Draw in the filler characters.
-      Ncurses.mvwhline(@field_win, 0, 0, @filler.ord, @field_width)
-
-      # If there is information in the field then draw it in.
-      if !(@info.nil?) && @info.size > 0
-        # Redraw the field.
-        if Display.is_hidden_display_type(@disp_type)
-          (@left_char...@info.size).each do |x|
-            Ncurses.mvwaddch(@field_win, 0, x - @left_char, @hidden)
-          end
-        else
-          (@left_char...@info.size).each do |x|
-            Ncurses.mvwaddch(@field_win, 0, x - @left_char, @info[x].ord | @field_attr)
-          end
-        end
-        Ncurses.wmove(@field_win, 0, @screen_col)
-      end
-
-      Ncurses.wrefresh @field_win
-    end
-
-    # This erases an entry widget from the screen.
+    # @see Widget#erase
     def erase
       if self.valid_widget?
         RNDK.window_erase(@field_win)
@@ -456,7 +548,7 @@ module RNDK
       end
     end
 
-    # This destroys an entry widget.
+    # @see Widget#destroy
     def destroy
       self.cleanTitle
 
@@ -465,21 +557,25 @@ module RNDK
       RNDK.window_delete(@shadow_win)
       RNDK.window_delete(@win)
 
-      self.clean_bindings(:ENTRY)
+      self.clean_bindings(:entry)
 
-      RNDK::Screen.unregister(:ENTRY, self)
+      RNDK::Screen.unregister(:entry, self)
     end
 
-    # This sets specific attributes of the entry field.
-    def set(value, min, max, box)
-      self.setValue(value)
-      self.setMin(min)
-      self.setMax(max)
+    # Sets multiple attributes of the Widget.
+    #
+    # See Entry#initialize.
+    def set(text, min, max, box)
+      self.set_text text
+      self.set_min min
+      self.set_max max
+
+      ## FIXME TODO
+      ## what about the `box`?
     end
 
-    # This removes the old information in the entry field and keeps
-    # the new information given.
-    def setValue(new_value)
+    # Sets the current text on the entry field.
+    def set_text new_value
       if new_value.nil?
         @info = ''
 
@@ -492,66 +588,70 @@ module RNDK
       end
     end
 
-    def getValue
+    # Returns the current text on the entry field.
+    def get_text
       return @info
     end
 
-    # This sets the maximum length of the string that will be accepted
-    def setMax(max)
+    # Sets the maximum length of the string that
+    # will be accepted.
+    def set_max max
       @max = max
     end
 
-    def getMax
+    def get_max
       @max
     end
 
-    # This sets the minimum length of the string that will be accepted.
-    def setMin(min)
+    # Sets the minimum length of the string that
+    # will be accepted.
+    def set_min min
       @min = min
     end
 
-    def getMin
+    def get_min
       @min
     end
 
-    # This sets the filler character to be used in the entry field.
-    def setFillerChar(filler_char)
+    # Sets the character to draw unused space on the field.
+    def set_filler_char(filler_char)
       @filler = filler_char
     end
 
-    def getFillerChar
+    def get_filler_char
       @filler
     end
 
-    # This sets the character to use when a hidden type is used.
-    def setHiddenChar(hidden_characer)
-      @hidden = hidden_character
+    # Sets the character to hide input when a hidden
+    # type is used.
+    #
+    # See Entry#initialize
+    def set_hidden_char char
+      @hidden = char
     end
 
-    def getHiddenChar
+    def get_hidden_char
       @hidden
     end
 
-    # This sets the background attribute of the widget.
-    def set_bg_attrib(attrib)
+    # Sets the background attribute/color of the widget.
+    def set_bg_attrib attrib
       Ncurses.wbkgd(@win, attrib)
       Ncurses.wbkgd(@field_win, attrib)
-      unless @label_win.nil?
-        @label_win.wbkgd(attrib)
-      end
+
+      @label_win.wbkgd(attrib) unless @label_win.nil?
     end
 
-    # This sets the attribute of the entry field.
+    # Sets the background attribute/color of the entry field.
+    #
+    # `cursor` tells if we hide the blinking cursor or not.
+    # See Ncurses#curs_set.
     def set_highlight(highlight, cursor)
       Ncurses.wbkgd(@field_win, highlight)
       @field_attr = highlight
-      Ncurses.curs_set(cursor)
-      # FIXME(original) - if (cursor) { move the cursor to this widget }
-    end
+      Ncurses.curs_set cursor
 
-    # This sets the entry field callback function.
-    def setCB(callback)
-      @callbackfn = callback
+      # FIXME(original) - if (cursor) { move the cursor to this widget }
     end
 
     def focus
@@ -560,16 +660,66 @@ module RNDK
     end
 
     def unfocus
-      self.draw(box)
+      self.draw box
       Ncurses.wrefresh @field_win
     end
 
+    # @see Widget#position
     def position
-      super(@win)
+      super @win
     end
 
     def object_type
-      :ENTRY
+      :entry
+    end
+
+    # Allows the programmer to set a different widget input handler.
+    #
+    # @note Unless you're very low-level and know what you're doing
+    #       you shouldn't need this.
+    def setCB(callback)
+      @callbackfn = callback
+    end
+
+    protected
+
+    def drawField
+      # Draw in the filler characters.
+      Ncurses.mvwhline(@field_win, 0, 0, @filler.ord, @field_width)
+
+      # If there is information in the field then draw it in.
+      if (not @info.nil?) and (@info.size > 0)
+        # Redraw the field.
+        if Display.is_hidden_display_type(@disp_type)
+          (@left_char...@info.size).each do |x|
+            Ncurses.mvwaddch(@field_win, 0, x - @left_char, @hidden)
+          end
+        else
+          (@left_char...@info.size).each do |x|
+            Ncurses.mvwaddch(@field_win, 0, x - @left_char, @info[x].ord | @field_attr)
+          end
+        end
+        Ncurses.wmove(@field_win, 0, @screen_col)
+      end
+
+      Ncurses.wrefresh @field_win
     end
+
+    def setPositionToEnd
+      if @info.size >= @field_width
+        if @info.size < @max
+          char_count = @field_width - 1
+          @left_char = @info.size - char_count
+          @screen_col = char_count
+        else
+          @left_char = @info.size - @field_width
+          @screen_col = @info.size - 1
+        end
+      else
+        @left_char = 0
+        @screen_col = @info.size
+      end
+    end
+
   end
 end

data/lib/rndk/fscale.rb

@@ -1,7 +1,7 @@
 require 'rndk/scale'
 
 module RNDK
-  class FSCALE < RNDK::SCALE
+  class FSCALE < SCALE
     def initialize(rndkscreen,
                    xplace,
                    yplace,