tung-tea 0.1.0 → 0.1.4

data/doc/example/bitmap_new.rb

@@ -0,0 +1,19 @@
+# Test that Bitmaps can be created without an image file.
+# Expected results are a red square inside a cyan square.
+
+require 'tea'
+
+puts <<TEST
+You should see a red square in a cyan square for 2 seconds.
+TEST
+
+Tea.init
+a = Tea::Bitmap.new(200, 200, 0x00ffffff)
+Tea::Screen.set_mode 400, 300
+b = Tea::Bitmap.new(150, 150, 0xff0000ff)
+
+Tea::Screen.blit a, 100, 50
+Tea::Screen.blit b, 125, 75
+Tea::Screen.update
+
+sleep 2

data/doc/example/smile_move.rb

@@ -1,3 +1,5 @@
+# Move the Smiley face with the arrow keys.  Press Esc to exit.
+
 require 'tea'
 
 class Smile

data/doc/example/smile_move_2.rb

@@ -0,0 +1,78 @@
+# Move the Smiley with the arrow keys, and press Esc to exit.  Identical to
+# smile_move.rb, but uses Tea::Event::Dispatch in a controlling class to handle
+# events.
+
+require 'tea'
+
+class Smile
+  def initialize
+    @bitmap = Tea::Bitmap.new('smile.png')
+    @x = (Tea::Screen.w - @bitmap.w) / 2
+    @y = (Tea::Screen.h - @bitmap.h) / 2
+    @dx = @dy = 0
+  end
+
+  def n(move) @dy += move ? -1 : 1 end
+  def s(move) @dy += move ? 1 : -1 end
+  def e(move) @dx += move ? 1 : -1 end
+  def w(move) @dx += move ? -1 : 1 end
+  def stopped?; @dx == 0 && @dy == 0; end
+
+  def update
+    @x += @dx
+    @y += @dy
+  end
+
+  def draw
+    Tea::Screen.blit @bitmap, @x, @y
+  end
+end
+
+class SmileControllingState
+  def initialize
+    @player = Smile.new
+    @done = false
+  end
+
+  def done?; @done; end
+  def update; @player.update; end
+  def need_update?; !@player.stopped?; end
+  def draw
+    Tea::Screen.clear
+    @player.draw
+  end
+
+  include Tea::Event::Dispatch
+
+  def kbd_down(e)
+    case e.key
+    when Tea::Kbd::UP     then @player.n true
+    when Tea::Kbd::DOWN   then @player.s true
+    when Tea::Kbd::LEFT   then @player.w true
+    when Tea::Kbd::RIGHT  then @player.e true
+    when Tea::Kbd::ESCAPE then @done = true
+    end
+  end
+
+  def kbd_up(e)
+    case e.key
+    when Tea::Kbd::UP    then @player.n false
+    when Tea::Kbd::DOWN  then @player.s false
+    when Tea::Kbd::LEFT  then @player.w false
+    when Tea::Kbd::RIGHT then @player.e false
+    end
+  end
+end
+
+Tea.init
+Tea::Screen.set_mode 640, 480
+state = SmileControllingState.new
+until state.done?
+  state.update
+  state.draw
+  Tea::Screen.update
+
+  if e = Tea::Event.get(!state.need_update?)
+    state.dispatch_event e
+  end
+end

data/doc/reference.textile

@@ -34,9 +34,14 @@ Tea::PrimitiveDrawing:
 
 Note that colours are of the form 0xRRGGBBAA.
 
-h3. Tea::Bitmap.new(image_path)
+h3. Tea::Bitmap.new(*args)
 
-Create a new Bitmap from an image file.  May raise Tea::Error if it fails.
+Create a new Bitmap.  This can be done in 2 ways:
+
+1. Tea::Bitmap.new(image_path): load from an image file.
+2. Tea::Bitmap.new(width, height, color): create with the given size and colour.
+
+ArgumentError is raised if you don't call it in one of these ways.  Tea::Error may be raised if one of these initialisations fail.
 
 h3. Tea::Bitmap#w()
 
@@ -134,6 +139,52 @@ These returned event objects may have methods that give extra information about
 
 May raise Tea::Error if getting an event fails.
 
+h2. Tea::Event::Dispatch mixin
+
+This mixin gives the class a dispatch_event method that, when called, will call a specially-named method that matches the event's class name.
+
+<pre>
+require 'tea'
+
+class MyEventHandler
+  attr_reader :done
+  def initialize; @done = false; end
+
+  include Tea::Event::Dispatch
+
+  def kbd_down(e)
+    puts "You typed: #{e.char}"
+    if e.key == Tea::Kbd::ESCAPE
+      puts 'Bye bye!'
+      @done = true
+    end
+  end
+end
+
+Tea.init
+Tea::Screen.set_mode 400, 300
+
+handler = MyEventHandler.new
+until handler.done
+  handler.dispatch_event Tea::Event.get(true)
+end
+</pre>
+
+This example shows:
+
+1. the Tea::Event::Dispatch mixin being included in a class,
+2. a sample event handling function kbd_down, matching Tea::Kbd::Down, and
+3. dispatch_event being called with an event passed into it.
+
+Event names are matched to method names as follows:
+
+1. Get the original class name, e.g. Tea::Kbd::Down.
+2. Get rid of the 'Tea::' part, e.g. Kbd::Down.
+3. Substitute the '::' for '_', e.g. Kbd_Down.
+4. Convert to all lower case, e.g. kbd_down.
+
+This mixin may not be needed for simpler games, but it can help when using classes to organise game code.
+
 h2. Tea::App
 
 As well as the app-related events that spawn from here, this module also provides some app-related status checking.

data/lib/tea/c_bitmap.rb

@@ -12,21 +12,19 @@ module Tea
   # A Bitmap is a grid of pixels that holds graphics.
   class Bitmap
 
-    # Create a new Bitmap from an image file.
+    # Create a new Bitmap.  This can be done in 2 ways:
     #
-    # May raise Tea::Error if it fails.
-    def initialize(image_path)
-      begin
-        @buffer = SDL::Surface.load(image_path)
-
-        # Optimise for the screen mode, potentially making screen blits faster.
-        if Tea::Screen.mode_set?
-          @buffer = @buffer.display_format_alpha
-        else
-          Tea::Screen.on_set_mode lambda { @buffer = @buffer.display_format_alpha }
-        end
-      rescue SDL::Error => e
-        raise Tea::Error, e.message, e.backtrace
+    # (image_path)::            loads from an image
+    # (width, height, color)::  creates with the given size and color
+    #
+    # May raise ArgumentError if the arguments passed in don't match one of the
+    # above, or Tea::Error if the Bitmap creation fails.
+    def initialize(*args)
+      case args.length
+      when 1 then from_image(*args)
+      when 3 then fresh(*args)
+      else
+        raise ArgumentError, "wrong number of arguments (#{args.length} for 1 or 3)", caller
       end
     end
 
@@ -50,6 +48,53 @@ module Tea
       @buffer
     end
 
+    private
+
+    # Create a new Bitmap from an image file.
+    #
+    # May raise Tea::Error if it fails.
+    def from_image(image_path)
+      @buffer = SDL::Surface.load(image_path)
+
+      # Optimise for the screen mode, potentially making screen blits faster.
+      if Tea::Screen.mode_set?
+        @buffer = @buffer.display_format_alpha
+      else
+        Tea::Screen.on_set_mode lambda { @buffer = @buffer.display_format_alpha }
+      end
+    rescue SDL::Error => e
+      raise Tea::Error, e.message, e.backtrace
+    end
+
+    # Create a new Bitmap of the given size and initialized with the color.
+    #
+    # May raise Tea::Error if it fails.
+    def fresh(width, height, color)
+      if width < 1 || height < 1
+        raise Tea::Error, "can't create bitmap smaller than 1x1 (#{width}x#{height})", caller
+      end
+
+      # Default to little endian pixel format, because it's what Intel uses,
+      # and Intel arches are common.
+      rmask = 0x000000ff
+      gmask = 0x0000ff00
+      bmask = 0x00ff0000
+      amask = 0xff000000
+      @buffer = SDL::Surface.new(SDL::SWSURFACE | SDL::SRCALPHA,
+                                 width, height, 32,
+                                 rmask, gmask, bmask, amask)
+      rect 0, 0, w, h, color
+
+      # Optimise for the screen mode, now or later.
+      if Tea::Screen.mode_set?
+        @buffer = @buffer.display_format_alpha
+      else
+        Tea::Screen.on_set_mode lambda { @buffer = @buffer.display_format_alpha }
+      end
+    rescue SDL::Error => e
+      raise Tea::Error, e.message, e.backtrace
+    end
+
   end
 
 end

data/lib/tea/m_event.rb

@@ -4,6 +4,7 @@ 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'
 

data/lib/tea/m_event_app.rb

@@ -2,15 +2,6 @@
 
 require 'sdl'
 
-# A hot-patch to Ruby/SDL for missing SDL::Event::Active#state constants.
-module SDL
-  class Event
-    APPMOUSEFOCUS = 0x01
-    APPINPUTFOCUS = 0x02
-    APPACTIVE     = 0x04
-  end
-end
-
 #
 module Tea
 
@@ -61,6 +52,11 @@ module Tea
 
   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)
@@ -71,13 +67,13 @@ module Tea
         out_events.push App::Exit.new
 
       when SDL::Event::Active
-        if (sdl_event.state & SDL::Event::APPACTIVE) != 0
+        if (sdl_event.state & APPACTIVE_) != 0
           out_events.push sdl_event.gain ? App::Restored.new : App::Minimized.new
         end
-        if (sdl_event.state & SDL::Event::APPINPUTFOCUS) != 0
+        if (sdl_event.state & APPINPUTFOCUS_) != 0
           out_events.push sdl_event.gain ? Kbd::Gained.new : Kbd::Lost.new
         end
-        if (sdl_event.state & SDL::Event::APPMOUSEFOCUS) != 0
+        if (sdl_event.state & APPMOUSEFOCUS_) != 0
           out_events.push sdl_event.gain ? Mouse::Gained.new : Mouse::Lost.new
         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_mouse.rb

@@ -2,14 +2,6 @@
 
 require 'sdl'
 
-# Hot-patch for Ruby/SDL for missing mouse wheel constants.
-module SDL
-  module Mouse
-    BUTTON_WHEELUP = 4
-    BUTTON_WHEELDOWN = 5
-  end
-end
-
 #
 module Tea
 
@@ -81,8 +73,8 @@ module Tea
         @x = sdl_event.x
         @y = sdl_event.y
         case sdl_event.button
-        when SDL::Mouse::BUTTON_WHEELDOWN then @delta = 1
-        when SDL::Mouse::BUTTON_WHEELUP   then @delta = -1
+        when Event::BUTTON_WHEELDOWN_ then @delta = 1
+        when Event::BUTTON_WHEELUP_   then @delta = -1
         else
           raise Tea::Error, "Tea::Mouse::Scroll given an unexpected event: #{sdl_event.inspect}", caller
         end
@@ -159,6 +151,10 @@ module Tea
 
   module Event
 
+    # Missing mouse wheel button constants from rubysdl.  For internal use only.
+    BUTTON_WHEELUP_ = 4
+    BUTTON_WHEELDOWN_ = 5
+
     # Convert a mouse-related SDL::Event into a Tea event.  For internal use only.
     def Event.translate_mouse_event(sdl_event)
       out_events = []
@@ -170,7 +166,7 @@ module Tea
         case sdl_event.button
         when SDL::Mouse::BUTTON_LEFT, SDL::Mouse::BUTTON_MIDDLE, SDL::Mouse::BUTTON_RIGHT
           out_events.push Mouse::Down.new(sdl_event)
-        when SDL::Mouse::BUTTON_WHEELDOWN, SDL::Mouse::BUTTON_WHEELUP
+        when BUTTON_WHEELDOWN_, BUTTON_WHEELUP_
           out_events.push Mouse::Scroll.new(sdl_event)
         end
       when SDL::Event::MouseButtonUp

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: tung-tea
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.4
 platform: ruby
 authors: 
 - Tung Nguyen
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-26 00:00:00 -07:00
+date: 2009-07-28 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -36,6 +36,7 @@ files:
 - README.rdoc
 - doc/example/bitmap_draw.rb
 - doc/example/bitmap_load.rb
+- doc/example/bitmap_new.rb
 - doc/example/circles.rb
 - doc/example/event_app.rb
 - doc/example/event_keyboard.rb
@@ -49,6 +50,7 @@ files:
 - doc/example/smile.png
 - doc/example/smile_bounce.rb
 - doc/example/smile_move.rb
+- doc/example/smile_move_2.rb
 - doc/example/state_app.rb
 - doc/example/state_keyboard.rb
 - doc/example/state_mouse.rb
@@ -61,12 +63,14 @@ files:
 - lib/tea/m_blitting.rb
 - lib/tea/m_event.rb
 - lib/tea/m_event_app.rb
+- lib/tea/m_event_dispatch.rb
 - lib/tea/m_event_keyboard.rb
 - lib/tea/m_event_mouse.rb
 - lib/tea/m_primitive_drawing.rb
 - lib/tea/screen.rb
 has_rdoc: false
 homepage: http://github.com/tung/tea
+licenses: 
 post_install_message: 
 rdoc_options: 
 - --charset=UTF-8
@@ -87,7 +91,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.2.0
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
 summary: A simple game development library for Ruby.