Make @text_keys available in handle_keyboard and write up docs on special keyboard handling

Author: marcheiligers

CHANGELOG.md

@@ -1,3 +1,8 @@
+# v0.0.23 - 16 February 2025
+
+* Made `@text_keys` instance variable instead of local
+* Wrote up notes on special keyboard handling with filtering example
+
 # v0.0.22 - 9 February 2025
 
 * Fixed a bug when using `max_length` where `selection_end` (and `selection_start`) where incorrectly set (thanks to @TheCire for reporting in Discord).

README.md

@@ -148,6 +148,31 @@ The argument list below will list `prompt_color` but not the individual `prompt_
 * `#focussed?` - Returns true if the input is focussed, false otherwise
 * `#value_changed?` - Returns true if the input value changed in the last tick, false otherwise
 
+## Special keyboard handling
+
+There may be cases where you want to do some special keyboard handling, like filtering out certain characters. In order to do this, create a subclass of `Input::Text` or `Input::Multiline` and override the `handle_keyboard` method, calling `super` when your special handling is done. The following instance variables are available:
+
+* `@meta` - true if the Meta key is down (the Command key on a Mac, or Windows key on Windows)
+* `@alt` - true if the Alt key is down
+* `@shift` - true if the Shift key is down or `shift_lock` is set
+* `@ctrl` - true if the Control key is down
+* `@down_keys` - an `Array` of `Symbol`s of keys that are down excluding the special keys above
+* `@text_keys` - an `Array` of printable characters that has been typed this tick
+
+### Example: filtering
+
+``` ruby
+class FilenameInput < Input::Text
+  ALLOWED_CHARS = ('a'..'z').to_a + ('A'..'Z').to_a + ('0'..'9').to_a + ['_', '-', '.']
+
+  def handle_keyboard
+    @text_keys.select! { |key| ALLOWED_CHARS.include?(key) }
+
+    super
+  end
+end
+```
+
 ## Console replacement
 
 This library includes the ability to replace the default DragonRuby Console (`~`). Simply call `Input.replace_console!` once to enable this.

lib/keyboard.rb

@@ -31,6 +31,8 @@ def prepare_special_keys # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       @alt = (special_keys & ALT_KEYS).any?
       @shift = @shift_lock || (special_keys & SHIFT_KEYS).any?
       @ctrl = (special_keys & CTRL_KEYS).any?
+
+      @text_keys = $args.inputs.text
     end
   end
 end

lib/multiline.rb

@@ -65,7 +65,6 @@ def draw_override(ffi)
     end
 
     def handle_keyboard
-      text_keys = $args.inputs.text
       # On a Mac:
       # Home is Cmd + ↑ / Fn + ←
       # End is Cmd + ↓ / Fn + →
@@ -103,7 +102,7 @@ def handle_keyboard
         else
           @on_unhandled_key.call(@down_keys.first, self)
         end
-      elsif text_keys.empty?
+      elsif @text_keys.empty?
         if @down_keys.include?(:delete)
           delete_forward unless @readonly
           @ensure_cursor_visible = true
@@ -164,7 +163,7 @@ def handle_keyboard
           @on_unhandled_key.call(@down_keys.first, self)
         end
       else
-        insert(text_keys.join('')) unless @readonly
+        insert(@text_keys.join('')) unless @readonly
         @ensure_cursor_visible = true
       end
     end

lib/text.rb

@@ -29,8 +29,6 @@ def draw_override(ffi)
     end
 
     def handle_keyboard
-      text_keys = $args.inputs.text
-
       if @meta || @ctrl
         # TODO: undo/redo
         if @down_keys.include?(:a)
@@ -57,7 +55,7 @@ def handle_keyboard
         else
           @on_unhandled_key.call(@down_keys.first, self)
         end
-      elsif text_keys.empty?
+      elsif @text_keys.empty?
         if @down_keys.include?(:delete)
           delete_forward unless @readonly
         elsif @down_keys.include?(:backspace)
@@ -88,7 +86,7 @@ def handle_keyboard
           @on_unhandled_key.call(@down_keys.first, self)
         end
       else
-        insert(text_keys.join('')) unless @readonly
+        insert(@text_keys.join('')) unless @readonly
         @ensure_cursor_visible = true
       end
     end

metadata/game_metadata.txt

@@ -3,7 +3,7 @@ devid=fascinationworks
 devtitle=Fascination Works
 gameid=dr-input
 gametitle=Dragon Ruby Input
-version=0.0.22
+version=0.0.23
 icon=metadata/icon.png
 
 # === Flags available at all licensing tiers ===