rubygame 2.3.0 → 2.4.0

data/lib/rubygame/events/misc_events.rb

@@ -0,0 +1,144 @@
+#--
+#  This file is one part of:
+#  Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#
+#  Copyright (C) 2008  John Croisant
+#
+#  This library is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU Lesser General Public
+#  License as published by the Free Software Foundation; either
+#  version 2.1 of the License, or (at your option) any later version.
+#
+#  This library is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#  Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public
+#  License along with this library; if not, write to the Free Software
+#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+# ++
+
+
+module Rubygame
+
+  module Events
+
+    # InputFocusGained is an event that occurs when
+    # the Rubygame application gains input focus.
+    # 
+    # Input focus means that the app will receive events from
+    # input devices, such as the keyboard and joysticks.
+    # 
+    # Usually, an application has input focus when it is the "active"
+    # application (the one the user has clicked on or switched to most
+    # recently).
+    # 
+    class InputFocusGained; end
+
+    # InputFocusLost is an event that occurs when
+    # the Rubygame application loses input focus.
+    # 
+    # See InputFocusGained for a description of "input focus".
+    # 
+    class InputFocusLost; end
+
+
+
+    # MouseFocusGained is an event that occurs when
+    # the Rubygame application gains mouse focus.
+    # 
+    # Mouse focus means that the mouse cursor is inside the
+    # app window. When the app has mouse focus, it will receive
+    # mouse events, particularly MouseMoved.
+    # 
+    class MouseFocusGained; end
+
+    # MouseFocusLost is an event that occurs when
+    # the Rubygame application loses mouse focus.
+    # 
+    # See MouseFocusGained for a description of "mouse focus".
+    # 
+    class MouseFocusLost; end
+
+
+
+    # WindowMinimized is an event that occurs when
+    # the Rubygame application window becomes minimized (also
+    # called 'iconified').
+    # 
+    class WindowMinimized; end
+
+    # WindowRestored is an event that occurs when the
+    # Rubygame application window is restored after it had been
+    # minimized.
+    # 
+    class WindowUnminimized; end
+
+
+
+    # WindowExposed is an event that occurs in
+    # certain situations when the Rubygame application
+    # window is exposed after being covered by another
+    # application.
+    # 
+    # This event may not occur on all platforms, but
+    # when it does occur, your app should refresh the
+    # entire window via Screen#flip (or 
+    # Rubygame::GL.swap_buffers, if using OpenGL).
+    # 
+    class WindowExposed; end
+
+
+
+    # QuitRequested is an event that occurs when the
+    # application receives a quit request, usually due to the
+    # user clicking the "Close" button on the app window.
+    # 
+    # Almost always, your application should respond to this
+    # event by quitting or by displaying a "Quit/Cancel"
+    # dialog. If you ignore this event, the user may become
+    # frustrated that your app won't close properly!
+    # 
+    class QuitRequested; end
+
+
+
+    # WindowResized is an event that occurs when the
+    # Rubygame application window is resized by the user.
+    # This can only happen if the Screen mode was set with
+    # the "resizable" flag.
+    # 
+    # Your application should respond to this event by
+    # setting the Screen mode again with the new #size and
+    # redrawing.
+    # 
+    # If you ignore this event, the "active" area of the
+    # Screen will stay the same size, and the rest (if the
+    # window was enlarged) will be black and won't receive
+    # any changes (blits, drawing, etc.).
+    # 
+    class WindowResized
+      attr_reader :size
+
+      def initialize( size )
+
+        @size = size.to_ary.dup
+        @size.freeze
+
+        unless @size.length == 2
+          raise ArgumentError, "size must have exactly 2 parts (got %s)"%@size.length
+        end
+
+        @size.each do |part|
+          if part <= 0
+            raise ArgumentError, "size must be positive (got %s)"%part
+          end
+        end
+
+      end
+    end
+
+
+  end
+end

data/lib/rubygame/events/mouse_events.rb

@@ -0,0 +1,155 @@
+#--
+#  This file is one part of:
+#  Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#
+#  Copyright (C) 2008  John Croisant
+#
+#  This library is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU Lesser General Public
+#  License as published by the Free Software Foundation; either
+#  version 2.1 of the License, or (at your option) any later version.
+#
+#  This library is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#  Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public
+#  License along with this library; if not, write to the Free Software
+#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+# ++
+
+
+module Rubygame
+
+  module Events
+
+    # 
+    # MouseButtonEvent is a mixin module included in the MousePressed
+    # and MouseReleased classes. It defines the #button and #pos
+    # attribute readers.
+    # 
+    module MouseButtonEvent
+      attr_reader :button, :pos
+
+      # 
+      # Initialize the MouseButtonEvent.
+      # 
+      # button:: a symbol for the button that was pressed or
+      #          released. (Symbol, required)
+      # 
+      # pos::    an Array for the position of the mouse cursor
+      #          when the event occured. [0,0] is the top-left
+      #          corner of the window (or the screen if running 
+      #          full-screen). (Array, required)
+      # 
+      def initialize( pos, button )
+
+        unless button.kind_of? Symbol
+          raise ArgumentError, "button must be a :symbol"
+        end
+
+        @button = button
+
+        @pos = pos.to_ary.dup
+        @pos.freeze
+
+      end
+    end
+
+
+    # 
+    # MousePressed is an event class which occurs when a button
+    # on the mouse is pressed down. 
+    # 
+    # This class gains #button and #pos attribute readers from
+    # the MouseButtonEvent mixin module.
+    # 
+    class MousePressed
+      include MouseButtonEvent
+
+      # 
+      # Create a new MousePressed instance.
+      # 
+      # button:: a symbol for the button that was pressed or
+      #          released. (Symbol, required)
+      # 
+      # pos::    an Array for the position of the mouse cursor
+      #          when the event occured. [0,0] is the top-left
+      #          corner of the window (or the screen if running 
+      #          full-screen). (Array, required)
+      # 
+      def initialize( pos, button )
+        super
+      end
+    end
+
+
+    # 
+    # MouseReleased is an event class which occurs when a button
+    # on the mouse is released (no longer being pressed). 
+    # 
+    # This class gains #button and #pos attribute readers from
+    # the MouseButtonEvent mixin module.
+    # 
+    class MouseReleased
+      include MouseButtonEvent
+
+      # 
+      # Create a new MouseReleased instance.
+      # 
+      # button:: a symbol for the button that was pressed or
+      #          released. (Symbol, required)
+      # 
+      # pos::    an Array for the position of the mouse cursor
+      #          when the event occured. [0,0] is the top-left
+      #          corner of the window (or the screen if running 
+      #          full-screen). (Array, required)
+      # 
+      def initialize( pos, button )
+        super
+      end
+    end
+
+
+    # 
+    # MouseMoved is an event class which occurs when the mouse
+    # cursor moves. It has attribute readers for #pos (new position),
+    # #rel (change since the last MouseMoved event), and #buttons
+    # (an Array of the mouse buttons that were held down while moving).
+    # 
+    class MouseMoved
+      
+      attr_reader :pos, :rel, :buttons
+
+      # 
+      # Create a new MouseReleased instance.
+      # 
+      # pos::     an Array for the new position of the mouse cursor.
+      #           The point [0,0] is the top-left corner of the window
+      #           (or the screen if running full-screen).
+      #           (Array, required)
+      # 
+      # rel::     an Array for the position change since the last
+      #           MouseMoved event, in pixels. (Array, required)
+      # 
+      # buttons:: an Array of symbols for the mouse buttons that were
+      #           being held down while the mouse was moving. [] if
+      #           no buttons were being held. (Array, optional)
+      # 
+      def initialize( pos, rel, buttons=[] )
+
+        @pos = pos.to_ary.dup
+        @pos.freeze
+
+        @rel = rel.to_ary.dup
+        @rel.freeze
+
+        @buttons = buttons.to_ary.dup
+        @buttons.freeze
+
+      end
+    end
+
+  end
+end

data/lib/rubygame/ftor.rb

@@ -80,7 +80,7 @@ class Ftor
 	# Create a new Ftor by specifying its #angle (in radians) and #magnitude.
   # See also #new.
 	def self.new_am(a,m)
-		v = Ftor.new(1,0)
+		v = self.new(1,0)
     v.a, v.m = a, m
 		return v
 	end
@@ -92,7 +92,7 @@ class Ftor
   # In other words, assuming +v+ is the Ftor returned by this function:
   #   p1 + v = p2
   def self.new_from_to(p1,p2)
-    return self.class.new(p2[0]-p1[0],p2[1]-p1[1])
+    return self.new(p2[0]-p1[0],p2[1]-p1[1])
   end
 
 	attr_reader :x                # The x component of the Ftor.

data/lib/rubygame/queue.rb

@@ -1,6 +1,9 @@
 #--
-#	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
-#	Copyright (C) 2004-2007  John Croisant
+# 
+# This file is one part of:
+#	  Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+# 
+#	Copyright (C) 2004-2008  John Croisant
 #
 #	This library is free software; you can redistribute it and/or
 #	modify it under the terms of the GNU Lesser General Public
@@ -15,6 +18,7 @@
 #	You should have received a copy of the GNU Lesser General Public
 #	License along with this library; if not, write to the Free Software
 #	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+# 
 #++
 
 require "rubygame/event"
@@ -26,16 +30,17 @@ module Rubygame
 	# joystick movement, etc. You can also post custom events to the
   # EventQueue to help manage the game state.
   # 
-  # This class replaces the old Rubygame::Queue class, which is no longer
-  # available. While EventQueue class serves the same purpose as the old
-  # class, they are somewhat different in behavior. Please note that while
-  # the old class was a Singleton, this class is not; you may have as many
-  # separate instances of EventQueue as you wish (although it is strongly
-  # recommended that only one be used to #fetch_sdl_events).
-  # 
   # For basic usage, create a #new EventQueue with autofetch, then call the
   # #each method once per game loop, passing a block which handles events.
   # See the sample applications for examples of this.
+  # 
+  # In Rubygame 2.4 and later, you can call #enable_new_style_events to make
+  # EventQueue fetch the new event classes (in the Rubygame::Events module).
+  # Otherwise, the old classes will be used, for backwards compatibility.
+  # 
+  # It is **strongly recommended** that you use the new event classes.
+  # The old classes are deprecated as of Rubygame 2.4, and will be removed
+  # entirely in Rubygame 3.0.
   #
   # If you wish to ignore all events of a certain class, append those classes
   # the instance variable @ignore (accessors are provided). You can ignore as
@@ -45,22 +50,6 @@ module Rubygame
   # If the program has to pause and wait for an event (for example, if the
   # player must press a button to begin playing), you might find the #wait
   # method to be convenient.
-	# 
-	# For reference, the full list of SDL events is:
-	# - Event (base class, not used by itself)
-	# - ActiveEvent
-	# - JoyAxisEvent
-	# - JoyBallEvent
-	# - JoyDownEvent
-	# - JoyHatEvent
-	# - JoyUpEvent
-	# - KeyDownEvent
-	# - KeyUpEvent
-	# - MouseDownEvent
-	# - MouseMotionEvent
-	# - MouseUpEvent
-	# - QuitEvent
-	# - ResizeEvent
 	# 
 	class EventQueue < Array
     # Array of classes to be ignored by #push.
@@ -74,9 +63,27 @@ module Rubygame
     def initialize()
       @autofetch = true
       @ignore = []
+      @new_style_events = false
       yield self if block_given?
     end
 
+
+    # Enable new-style events. These are the event classes in the 
+    # Rubygame::Events module, which were added in Rubygame 2.4.
+    # 
+    # If you call this method, the new event classes will be used.
+    # Otherwise, the old classes will be used, for backwards
+    # compatibility.
+    # 
+    # It is **strongly recommended** that you use the new event
+    # classes. The old classes are deprecated as of Rubygame 2.4,
+    # and will be removed entirely in Rubygame 3.0.
+    # 
+    def enable_new_style_events
+      @new_style_events = true
+    end
+
+
     # Append events to the EventQueue.
     # Silently ignores events whose class is in @ignore.
     def push(*events)
@@ -88,7 +95,9 @@ module Rubygame
 
     alias post push
 
-    alias peek_each each        # Iterate through all events without removing.
+
+    alias :_old_each :each
+    private :_old_each
 
     # Iterate through all events in the EventQueue, yielding them one at a time
     # to the given block. The EventQueue is flushed after all events have been
@@ -96,19 +105,31 @@ module Rubygame
     #
     # If the internal variable @autofetch is true, this method will call
     # #fetch_sdl_events once before iterating.
-    def each(&block)
+    def each( &block )
       fetch_sdl_events if @autofetch
-      super
+      _old_each( &block )
       self.clear
     end
 
+    # Like #each, but doesn't remove the events from the queue after
+    # iterating. 
+    def peek_each( &block )
+      fetch_sdl_events if @autofetch
+      _old_each( &block )
+    end
+
+
     # Posts pending SDL hardware events to the EventQueue. Only one EventQueue
     # should call this method per application, and only if you are not using
     # Rubygame#fetch_sdl_events to manually process events! Otherwise, some
     # events may be removed from SDL's event stack before they can be properly
     # processed!
 		def fetch_sdl_events
-			self.push(Rubygame.fetch_sdl_events())
+      if @new_style_events
+        self.push( Rubygame::Events.fetch_sdl_events() )
+      else
+        self.push( Rubygame.fetch_sdl_events() )
+      end
 		end
 
     # Wait for an event to be posted, then return that event.