tea 0.6.1

data/lib/tea/c_sound.rb

@@ -0,0 +1,144 @@
+# This file contains the Sound class.
+
+require 'sdl'
+
+require 'tea/c_error'
+
+#
+module Tea
+
+  # The Sound class allows loading and playing of audio files.
+  #
+  # Currently supported formats: OGG, WAV, AIFF, RIFF, VOC.
+  class Sound
+
+    # Sound states returned by Tea::Sound#state.
+    STOPPED = :STOPPED
+    PLAYING = :PLAYING
+    PAUSED = :PAUSED
+
+    # As per Ruby/SDL's mixer API.
+    VOLUME_MAX = 128
+
+    # Tracked because Ruby/SDL's mixer API can't get the channel volumes.
+    @@volume = VOLUME_MAX
+
+    # Tracks which Sound objects are playing in which channels, to report
+    # accurate playing state info.
+    @@channel_sound_ids = []
+
+    # Get the master volume.  Volume ranges from 0..128 inclusive.
+    def Sound.volume
+      @@volume
+    end
+
+    # Set the master volume.  new_volume should be between 0..128 inclusive.
+    def Sound.volume=(new_volume)
+      v = (new_volume >= 0) ? (new_volume <= VOLUME_MAX ? new_volume : VOLUME_MAX) : 0
+      SDL::Mixer.set_volume -1, new_volume
+      @@volume = v
+    end
+
+    # Pause all sound.
+    def Sound.pause_all
+      SDL::Mixer.pause -1
+    end
+
+    # Resume playing all paused sound.
+    def Sound.resume_all
+      SDL::Mixer.resume -1
+    end
+
+    # Stop all sounds, playing or paused.
+    def Sound.stop_all
+      SDL::Mixer.halt -1
+    end
+
+
+    # Load a sound file.
+    #
+    # May raise Tea::Error on failure.
+    def initialize(path)
+      @wave = SDL::Mixer::Wave.load(path)
+      @channel = -1
+
+      # Tracked because Ruby/SDL's mixer API can't get sound volumes.
+      @volume = VOLUME_MAX
+    rescue SDL::Error => e
+      raise Tea::Error, e.message, e.backtrace
+    end
+
+    # Get the sound's volume.  Volume ranges from 0..128 inclusive.
+    def volume
+      @volume
+    end
+
+    # Set the sound's volume.  new_volume should be between 0..128 inclusive.
+    def volume=(new_volume)
+      v = (new_volume >= 0) ? (new_volume <= VOLUME_MAX ? new_volume : VOLUME_MAX) : 0
+      @wave.set_volume v
+      @volume = v
+    end
+
+    # Play the sound.  If this sound is still playing, cut it off and start
+    # playing it from the start.
+    #
+    # loops should be the number of times to repeat playing the sound.  Use -1
+    # to loop the sound forever.
+    def play(loops=0)
+      SDL::Mixer.halt(@channel) if channel_valid?
+
+      @channel = SDL::Mixer.play_channel(-1, @wave, loops)
+      @@channel_sound_ids[@channel] = object_id
+    end
+
+    # Pause the sound if it's playing, otherwise do nothing.
+    def pause
+      SDL::Mixer.pause(@channel) if channel_valid?
+    end
+
+    # Resume the sound if it's paused, otherwise do nothing.
+    def resume
+      SDL::Mixer.resume(@channel) if channel_valid?
+    end
+
+    # Stop the sound if it's playing or paused, otherwise do nothing.
+    def stop
+      SDL::Mixer.halt(@channel) if channel_valid?
+    end
+
+    # Check if the sound is stopped, playing or paused.  Returns one of
+    # Tea::Sound::STOPPED, Tea::Sound::PLAYING or Tea::Sound::PAUSED.  A sound
+    # that isn't playing or paused is considered stopped.
+    def state
+      if channel_valid?
+        if SDL::Mixer.play?(@channel)
+          # For some reason, pause? returns 0 and 1 instead of true and false.
+          if SDL::Mixer.pause?(@channel) != 0
+            PAUSED
+          else
+            PLAYING
+          end
+        else
+          STOPPED
+        end
+      else
+        STOPPED
+      end
+    end
+
+    private
+
+    # Check if @channel really maps to this sound.  Returns the channel number
+    # if so, otherwise nil.
+    def channel_valid?
+      if @channel >= 0 && @@channel_sound_ids[@channel] == object_id
+        @channel
+      else
+        nil
+      end
+    end
+
+  end
+
+end

data/lib/tea/m_color.rb

@@ -0,0 +1,50 @@
+# This file holds the Color module.
+
+#
+module Tea
+
+  # The Color module holds utility methods that can mix and split colors.
+  module Color
+
+    # Create a color from red, green, blue and optionally alpha parts.
+    # All values passed in should be within 0..255 inclusive.
+    def Color.mix(red, green, blue, alpha=255)
+      ((red   & 0xff) << 24) |
+      ((green & 0xff) << 16) |
+      ((blue  & 0xff) <<  8) |
+       (alpha & 0xff)
+    end
+
+    # Break a colour up into its red, green, blue and alpha parts.
+    # Returns a 4-element array of the form [red, green, blue, alpha], where
+    # each element is within 0..255 inclusive.
+    def Color.split(color)
+      [(color & 0xff000000) >> 24,
+       (color & 0x00ff0000) >> 16,
+       (color & 0x0000ff00) >>  8,
+       (color & 0x000000ff)]
+    end
+
+    CLEAR         = Color.mix(  0,   0,   0,   0)
+
+    BLACK         = Color.mix(  0,   0,   0)
+    DARK_RED      = Color.mix(128,   0,   0)
+    DARK_GREEN    = Color.mix(  0, 128,   0)
+    DARK_YELLOW   = Color.mix(128, 128,   0)
+    DARK_BLUE     = Color.mix(  0,   0, 128)
+    DARK_MAGENTA  = Color.mix(128,   0, 128)
+    DARK_CYAN     = Color.mix(  0, 128, 128)
+    DARK_GRAY     = Color.mix(128, 128, 128)
+
+    GRAY          = Color.mix(192, 192, 192)
+    RED           = Color.mix(255,   0,   0)
+    GREEN         = Color.mix(  0, 255,   0)
+    YELLOW        = Color.mix(255, 255,   0)
+    BLUE          = Color.mix(  0,   0, 255)
+    MAGENTA       = Color.mix(255,   0, 255)
+    CYAN          = Color.mix(  0, 255, 255)
+    WHITE         = Color.mix(255, 255, 255)
+
+  end
+
+end

data/lib/tea/m_event.rb

@@ -0,0 +1,65 @@
+# This file holds the core Event module.
+
+require 'sdl'
+
+require 'tea/c_error'
+require 'tea/m_event_app'
+require 'tea/m_event_dispatch'
+require 'tea/m_event_keyboard'
+require 'tea/m_event_mouse'
+
+#
+module Tea
+
+  # The Event module allows access to the event queue, and the classes of
+  # events that come out.
+  module Event
+
+    # Tea's generated event queue.  Add to the back, get from the front.
+    @@event_queue = []
+
+    # Get the next event in the event queue.  If wait is true and there are no
+    # events to return, this method will wait until there is one and return it.
+    # Otherwise, an empty event queue will return nil.
+    #
+    # May raise Tea::Error if getting an event fails.
+    def Event.get(wait=false)
+      if @@event_queue.length == 0
+        if wait
+          begin
+            sdl_event = SDL::Event.wait
+            if (out_events = translate_event(sdl_event))
+              @@event_queue.push *out_events
+            end
+          end until @@event_queue.length > 0
+        else
+          if (out_events = translate_event(SDL::Event.poll))
+            @@event_queue.push *out_events
+          end
+        end
+      end
+
+      tea_event = @@event_queue.shift
+      [App, Mouse, Kbd].each { |state_holder| state_holder.update_state tea_event }
+      tea_event
+    rescue SDL::Error => e
+      raise Tea::Error, e.message, e.backtrace
+    end
+
+    # Convert an SDL::Event into one or more Tea events.  May return nil, a
+    # single event object or multiple events in an array.
+    def Event.translate_event(sdl_event)
+      case sdl_event
+      when SDL::Event::Active, SDL::Event::Quit
+        translate_app_event sdl_event
+      when SDL::Event::MouseMotion, SDL::Event::MouseButtonDown, SDL::Event::MouseButtonUp
+        translate_mouse_event sdl_event
+      when SDL::Event::KeyDown, SDL::Event::KeyUp
+        translate_keyboard_event sdl_event
+      end
+    end
+    private_class_method :translate_event
+
+  end
+
+end

data/lib/tea/m_event_app.rb

@@ -0,0 +1,96 @@
+# This file holds app-related event handling.
+
+require 'sdl'
+
+#
+module Tea
+
+  module Mouse
+    # Event generated when mouse focus is gained.
+    class Gained
+    end
+
+    # Event generated when mouse focus is lost.
+    class Lost
+    end
+  end
+
+  module Kbd
+    # Event generated when keyboard input focus is gained.
+    class Gained
+    end
+
+    # Event generated when keyboard input focus is lost.
+    class Lost
+    end
+  end
+
+  module App
+    # Event generated when the player acts to close the screen window.
+    class Exit
+    end
+
+    # Event generated when the screen window is minimised.
+    class Minimized
+    end
+
+    # Event generated when the screen window is restored from being minimised.
+    class Restored
+    end
+
+    # Default for App.visible?.
+    @visible = true
+
+    # Returns true if the screen window has not been minimised, otherwise
+    # false.
+    def App.visible?
+      @visible
+    end
+
+    # Update the reported app state when a Tea event is retrieved, so
+    # App.visible? returns the right status.  Called automatically by
+    # Event.get.
+    def App.update_state(tea_event)
+      case tea_event
+      when Minimized then @visible = false
+      when Restored  then @visible = true
+      end
+      @visible
+    end
+  end
+
+  module Event
+
+    # APP constants rubysdl is missing.  For internal use only.
+    APPMOUSEFOCUS_ = 0x01
+    APPINPUTFOCUS_ = 0x02
+    APPACTIVE_     = 0x04
+
+    # Translates an app-related SDL::Event into an array of Tea::Event
+    # objects.  For internal use only.
+    def Event.translate_app_event(sdl_event)
+      out_events = []
+
+      case sdl_event
+      when SDL::Event::Quit
+        out_events.push App::Exit.new
+
+      when SDL::Event::Active
+        if (sdl_event.state & APPACTIVE_) != 0
+          out_events.push sdl_event.gain ? App::Restored.new : App::Minimized.new
+        end
+        if (sdl_event.state & APPINPUTFOCUS_) != 0
+          out_events.push sdl_event.gain ? Kbd::Gained.new : Kbd::Lost.new
+        end
+        if (sdl_event.state & APPMOUSEFOCUS_) != 0
+          out_events.push sdl_event.gain ? Mouse::Gained.new : Mouse::Lost.new
+        end
+      end
+
+      out_events
+    end
+    private_class_method :translate_app_event
+
+  end
+
+end

data/lib/tea/m_event_dispatch.rb

@@ -0,0 +1,54 @@
+# This file contains the event dispatch mixin.
+
+require 'tea/c_error'
+
+#
+module Tea
+
+  module Event
+
+    # The Dispatch mixin gives any object the ability to handle Tea events with
+    # method calls.  To use it, include the mixin in your class
+    #
+    #   include Tea::Event::Dispatch
+    #
+    # define the handling methods (all optional)
+    #
+    #   def app_exit; end
+    #   def app_restored; end
+    #   def app_minimized; end
+    #   def kbd_down; end
+    #   def kbd_up; end
+    #   def mouse_move; end
+    #   def mouse_down; end
+    #   def mouse_up; end
+    #   def mouse_scroll; end
+    #
+    # and when you need events handled, call your instance's dispatch_event
+    # method
+    #
+    #   handler = MyEventHandler.new
+    #   ...
+    #   loop do
+    #     event = Tea::Event.get
+    #     handler.dispatch_event event if event
+    #     ...
+    #   end
+    #
+    # Tea will then call the method matching the event received.
+    module Dispatch
+
+      def dispatch_event(tea_event)
+        class_string = tea_event.class.to_s
+        unless class_string =~ /^Tea::(?:App|Kbd|Mouse)::[A-Za-z]+$/
+          raise Tea::Error, "Can't dispatch on class #{class_string}", caller
+        end
+        msg = class_string.split('::', 2)[1].sub('::', '_').downcase.intern
+        send msg, tea_event if respond_to?(msg)
+      end
+
+    end
+
+  end
+
+end

data/lib/tea/m_event_keyboard.rb

@@ -0,0 +1,311 @@
+# This file holds the key press and modifier events.
+
+require 'sdl'
+
+#
+module Tea
+
+  module Kbd
+
+    # Superclass for all Kbd events.
+    class Event
+      @@sdl_key_table = {
+          SDL::Key::BACKSPACE => :BACKSPACE,
+          SDL::Key::TAB => :TAB,
+          #SDL::Key::CLEAR => clear, # ???
+          SDL::Key::RETURN => :ENTER,
+          SDL::Key::PAUSE => :PAUSE,
+          SDL::Key::ESCAPE => :ESCAPE,
+          SDL::Key::SPACE => :SPACE,
+          SDL::Key::EXCLAIM => :EXCLAMATION_MARK,
+          SDL::Key::QUOTEDBL => :DOUBLE_QUOTE,
+          SDL::Key::HASH => :HASH,
+          SDL::Key::DOLLAR => :DOLLAR,
+          SDL::Key::AMPERSAND => :AMPERSAND,
+          SDL::Key::QUOTE => :QUOTE,
+          SDL::Key::LEFTPAREN => :OPEN_PAREN,
+          SDL::Key::RIGHTPAREN => :CLOSE_PAREN,
+          SDL::Key::ASTERISK => :ASTERISK,
+          SDL::Key::PLUS => :PLUS,
+          SDL::Key::COMMA => :COMMA,
+          SDL::Key::MINUS => :MINUS,
+          SDL::Key::PERIOD => :PERIOD,
+          SDL::Key::SLASH => :SLASH,
+          SDL::Key::K0 => :K0,
+          SDL::Key::K1 => :K1,
+          SDL::Key::K2 => :K2,
+          SDL::Key::K3 => :K3,
+          SDL::Key::K4 => :K4,
+          SDL::Key::K5 => :K5,
+          SDL::Key::K6 => :K6,
+          SDL::Key::K7 => :K7,
+          SDL::Key::K8 => :K8,
+          SDL::Key::K9 => :K9,
+          SDL::Key::COLON => :COLON,
+          SDL::Key::SEMICOLON => :SEMICOLON,
+          SDL::Key::LESS => :LESS_THAN,
+          SDL::Key::EQUALS => :EQUALS,
+          SDL::Key::GREATER => :GREATER_THAN,
+          SDL::Key::QUESTION => :QUESTION_MARK,
+          SDL::Key::AT => :AT,
+          SDL::Key::LEFTBRACKET => :OPEN_SQUARE_BRACKET,
+          SDL::Key::BACKSLASH => :BACKSLASH,
+          SDL::Key::RIGHTBRACKET => :CLOSE_SQUARE_BRACKET,
+          SDL::Key::CARET => :CARET,
+          SDL::Key::UNDERSCORE => :UNDERSCORE,
+          SDL::Key::BACKQUOTE => :BACKTICK,
+          SDL::Key::A => :A,
+          SDL::Key::B => :B,
+          SDL::Key::C => :C,
+          SDL::Key::D => :D,
+          SDL::Key::E => :E,
+          SDL::Key::F => :F,
+          SDL::Key::G => :G,
+          SDL::Key::H => :H,
+          SDL::Key::I => :I,
+          SDL::Key::J => :J,
+          SDL::Key::K => :K,
+          SDL::Key::L => :L,
+          SDL::Key::M => :M,
+          SDL::Key::N => :N,
+          SDL::Key::O => :O,
+          SDL::Key::P => :P,
+          SDL::Key::Q => :Q,
+          SDL::Key::R => :R,
+          SDL::Key::S => :S,
+          SDL::Key::T => :T,
+          SDL::Key::U => :U,
+          SDL::Key::V => :V,
+          SDL::Key::W => :W,
+          SDL::Key::X => :X,
+          SDL::Key::Y => :Y,
+          SDL::Key::Z => :Z,
+          SDL::Key::DELETE => :DELETE,
+          SDL::Key::KP0 => :NP0,
+          SDL::Key::KP1 => :NP1,
+          SDL::Key::KP2 => :NP2,
+          SDL::Key::KP3 => :NP3,
+          SDL::Key::KP4 => :NP4,
+          SDL::Key::KP5 => :NP5,
+          SDL::Key::KP6 => :NP6,
+          SDL::Key::KP7 => :NP7,
+          SDL::Key::KP8 => :NP8,
+          SDL::Key::KP9 => :NP9,
+          SDL::Key::KP_PERIOD => :NP_PERIOD,
+          SDL::Key::KP_DIVIDE => :NP_DIVIDE,
+          SDL::Key::KP_MULTIPLY => :NP_MULTIPLY,
+          SDL::Key::KP_MINUS => :NP_MINUS,
+          SDL::Key::KP_PLUS => :NP_PLUS,
+          SDL::Key::KP_ENTER => :NP_ENTER,
+          SDL::Key::KP_EQUALS => :NP_EQUALS,
+          SDL::Key::UP => :UP,
+          SDL::Key::DOWN => :DOWN,
+          SDL::Key::RIGHT => :RIGHT,
+          SDL::Key::LEFT => :LEFT,
+          SDL::Key::INSERT => :INSERT,
+          SDL::Key::HOME => :HOME,
+          SDL::Key::END => :END,
+          SDL::Key::PAGEUP => :PAGE_UP,
+          SDL::Key::PAGEDOWN => :PAGE_DOWN,
+          SDL::Key::F1 => :F1,
+          SDL::Key::F2 => :F2,
+          SDL::Key::F3 => :F3,
+          SDL::Key::F4 => :F4,
+          SDL::Key::F5 => :F5,
+          SDL::Key::F6 => :F6,
+          SDL::Key::F7 => :F7,
+          SDL::Key::F8 => :F8,
+          SDL::Key::F9 => :F9,
+          SDL::Key::F10 => :F10,
+          SDL::Key::F11 => :F11,
+          SDL::Key::F12 => :F12,
+          #SDL::Key::F13 => F13, # Who
+          #SDL::Key::F14 => F14, # has
+          #SDL::Key::F15 => F15, # these?
+          SDL::Key::NUMLOCK => :NUM_LOCK,
+          SDL::Key::CAPSLOCK => :CAPS_LOCK,
+          SDL::Key::SCROLLOCK => :SCROLL_LOCK,
+          SDL::Key::RSHIFT => :R_SHIFT,
+          SDL::Key::LSHIFT => :L_SHIFT,
+          SDL::Key::RCTRL => :R_CTRL,
+          SDL::Key::LCTRL => :L_CTRL,
+          SDL::Key::RALT => :R_ALT,
+          SDL::Key::LALT => :L_ALT,
+          #SDL::Key::RMETA => right meta, # 'meta' should
+          #SDL::Key::LMETA => left meta,  # be 'alt'?
+          SDL::Key::LSUPER => :L_SUPER,
+          SDL::Key::RSUPER => :R_SUPER,
+          SDL::Key::MODE => :ALT_GR,
+          #SDL::Key::HELP => help, # Rare enough to cause problems.
+          SDL::Key::PRINT => :PRINT_SCREEN,
+          SDL::Key::SYSREQ => :SYS_REQ,
+          SDL::Key::BREAK => :BREAK,
+          SDL::Key::MENU => :MENU,
+          #SDL::Key::POWER => power, # "Power Macintosh" power key
+          SDL::Key::EURO => :EURO, # Some European keyboards need this.
+          }
+
+      # Call a block for each defined Tea key constant.
+      def Event.each_key
+        @@sdl_key_table.each_value { |key_const| yield key_const }
+      end
+
+      protected
+
+      # Convert an SDL keysym to a Tea key constant
+      def sdl_keysym_to_key(sdl_keysym)
+        @@sdl_key_table[sdl_keysym]
+      end
+
+      # Convert SDL key modifier info into an array of active key modifiers.
+      def sdl_keymod_to_mods(sdl_keymod)
+        mods = {}
+
+        mods[:L_SHIFT] = (sdl_keymod & SDL::Key::MOD_LSHIFT) != 0
+        mods[:R_SHIFT] = (sdl_keymod & SDL::Key::MOD_RSHIFT) != 0
+        mods[:SHIFT]   = mods[:L_SHIFT] || mods[:R_SHIFT]
+
+        mods[:L_CTRL] = (sdl_keymod & SDL::Key::MOD_LCTRL) != 0
+        mods[:R_CTRL] = (sdl_keymod & SDL::Key::MOD_RCTRL) != 0
+        mods[:CTRL]   = mods[:L_CTRL] || mods[:R_CTRL]
+
+        mods[:L_ALT] = (sdl_keymod & SDL::Key::MOD_LALT) != 0
+        mods[:R_ALT] = (sdl_keymod & SDL::Key::MOD_RALT) != 0
+        mods[:ALT]   = mods[:L_ALT] || mods[:R_ALT]
+
+        mods[:NUM_LOCK]  = (sdl_keymod & SDL::Key::MOD_NUM) != 0
+        mods[:CAPS_LOCK] = (sdl_keymod & SDL::Key::MOD_CAPS) != 0
+        mods[:ALT_GR]    = (sdl_keymod & SDL::Key::MOD_MODE) != 0
+
+        mods
+      end
+    end
+
+    # Event generated when a key is pressed down.
+    #
+    # +key+::   Physical key that was pressed, as a symbol (see key reference).
+    # +mods+::  Hash of the active key modifiers.  Values are +true+ or
+    #           +false+, and the keys can be: +:L_SHIFT+, +:R_SHIFT+,
+    #           +:L_CTRL+, +:R_CTRL+, +:L_ALT+, +:R_ALT+, +:NUM_LOCK+,
+    #           +:CAPS_LOCK+, +:ALT_GR+.  Also, +:SHIFT+, +:CTRL+ and +:ALT+
+    #           are provided for convenience, and Tea key constants with the
+    #           same names can be used instead.
+    # +char+::  String character generated by that key and those modifiers.
+    #           With Ruby >= 1.9, the encoding of this character is UTF-8,
+    #           otherwise it varies with the running environment.
+    class Down < Event
+      attr_reader :key, :mods, :char
+      def initialize(sdl_event)
+        @key = sdl_keysym_to_key(sdl_event.sym)
+        @mods = sdl_keymod_to_mods(sdl_event.mod)
+
+        if sdl_event.unicode != 0
+          unicode_field = "%c"
+          # Ruby 1.9 uses UTF-8 Unicode encoding.  Otherwise, who knows how
+          # Unicode code points are interpreted?
+          unicode_field = unicode_field.encode('utf-8') if RUBY_1_9
+          @char = unicode_field % sdl_event.unicode
+        else
+          @char = ''
+        end
+      end
+    end
+
+    # Event generated when a held-down key is released.  +key+ and +mods+ are
+    # the same as in KeyDown.
+    #
+    # +key+::   Physical key that was pressed, as a symbol (see key reference).
+    # +mods+::  Hash of the active key modifiers.  Values are +true+ or
+    #           +false+, and the keys can be: +:L_SHIFT+, +:R_SHIFT+,
+    #           +:L_CTRL+, +:R_CTRL+, +:L_ALT+, +:R_ALT+, +:NUM_LOCK+,
+    #           +:CAPS_LOCK+, +:ALT_GR+.  Also, +:SHIFT+, +:CTRL+ and +:ALT+
+    #           are provided for convenience, and Tea key constants with the
+    #           same names can be used instead.
+    class Up < Event
+      attr_reader :key, :mods
+      def initialize(sdl_event)
+        @key = sdl_keysym_to_key(sdl_event.sym)
+        @mods = sdl_keymod_to_mods(sdl_event.mod)
+      end
+    end
+
+    # Defaults for Kbd.key_down?, Kbd.mod_active? and Kbd.in_app?.
+    @key_states = {}
+    Event.each_key { |key| @key_states[key] = false }
+
+    @mod_states = { :L_SHIFT => false, :R_SHIFT => false, :SHIFT => false,
+                    :L_CTRL  => false, :R_CTRL  => false, :CTRL  => false,
+                    :L_ALT   => false, :R_ALT   => false, :ALT   => false,
+                    :NUM_LOCK => false,
+                    :CAPS_LOCK => false,
+                    :ALT_GR => false }
+
+    @in_app = true
+
+    # Returns +true+ if +key+ is being pressed down.
+    def Kbd.key_down?(key)
+      if (down = @key_states[key]) == nil
+        raise Tea::Error, "Can't find key #{key} to check", caller
+      end
+      down
+    end
+
+    # Returns true if the modifier is 'active'.  For +:L_SHIFT+, +:R_SHIFT+,
+    # +:L_CTRL+, +:R_CTRL+, +:L_ALT+, and +:ALT_GR+ (and convenience modifier
+    # constants +:SHIFT+, +:CTRL+ and +:ALT+), this means they're being held
+    # down.  For +:NUM_LOCK+ and +:CAPS_LOCK+, this means their toggle is on.
+    def Kbd.mod_active?(mod)
+      if (active = @mod_states[mod]) == nil
+        raise Tea::Error, "Can't find modifier #{mod} to check", caller
+      end
+      active
+    end
+
+    # Returns true if the keyboard is focused in the screen window.
+    def Kbd.in_app?
+      @in_app
+    end
+
+    # Update the keyboard state, so that Kbd.key_down? and Kbd.mod_active?
+    # provide fresh data.  Called automatically by Event.get.
+    def Kbd.update_state(tea_event)
+      case tea_event
+      when Down, Up
+        @key_states[tea_event.key] = (tea_event.class == Down)
+        @mod_states.merge! tea_event.mods
+      when Lost then   @in_app = false
+      when Gained then @in_app = true
+      end
+    end
+
+    # Define Tea key symbols as constants to avoid typo errors.
+    Event.each_key { |key| const_set(key, key) }
+
+    # Extra modifier constants for making modifier detection more consistent.
+    SHIFT = :SHIFT
+    CTRL = :CTRL
+    ALT = :ALT
+
+  end
+
+  module Event
+
+    # Convert a keyboard-related SDL::Event into a Tea event.  For internal use
+    # only.
+    def Event.translate_keyboard_event(sdl_event)
+      out_events = []
+
+      case sdl_event
+      when SDL::Event::KeyDown
+        out_events.push Kbd::Down.new(sdl_event)
+      when SDL::Event::KeyUp
+        out_events.push Kbd::Up.new(sdl_event)
+      end
+
+      out_events
+    end
+    private_class_method :translate_keyboard_event
+
+  end
+
+end