rubygame 2.1.0

data/lib/rubygame/hotspot.rb

@@ -0,0 +1,265 @@
+# Hotspot, a mixin module to extend an object with custom, named, relative 
+# position offsets.
+#--
+#	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#	Copyright (C) 2004-2007  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
+
+  # *NOTE*: you must require 'rubygame/hotspot' manually to gain access to
+  # Rubygame::Hotspot. It is not imported with Rubygame by default!
+  # 
+  # Hotspot is a mixin module to extend an object with "hotspots": custom,
+  # named, relative position offsets. Hotspots can be defined relative to the
+  # origin, to another hotspot, or to the results of a method (via a 
+  # 'smart' hotspot).
+  # 
+  # There are two types of hotspots, simple and 'smart'.
+  # 
+  # Simple hotspots are an Array of three values, an x offset, a y offset,
+  # and the label of another hotspot relative to which this hotspot is defined.
+  # If the last argument is omitted or nil, the hotspot is defined relative
+  # to the true origin (i.e. (0,0), the top-left corner of the Screen).
+  # See #new_hotspot.
+  # 
+  # Smart hotspots, or 'smartspots' for short, act as a proxy to the object's
+  # methods. Each time a smartspot is evaluated, it calls the object's method
+  # of the same name as the smartspot, and uses the results of the method as
+  # x and y offsets. Therefore, smartspots only work for methods which:
+  #  1. take no arguments
+  #  2. return an Array with 2 Numeric values (or something else that responds
+  #     to #[]
+  #
+  # By adding a smartspot to a Rect, for example, you could define simple 
+  # hotspots relative to its Rect#center; then, even if the Rect moves or
+  # changes size, the smartspot will always to evaluate to its true center.
+  # See #new_smartspot.
+  # 
+  #--
+  # ((Old documentation/brainstorming))
+  # As an example, consider an object which represents a person's face: eyes, 
+  # ears, nose, mouth, etc. You might make a face and define several hotspots
+  # like so:
+  # 
+  #  myface = Face.new()                # Create a new face, with no hotspots.
+  #  myface.extend(Hotspot)             # Extend myface with hotspot ability.
+  #  myface.new_hotspot \               # Define some new hotspots: ...
+  #   :nose => [10,5, :center],        # the nose, relative to face's center,
+  #   :left_eye => [-5,-2, :nose],     # the left eye, left and above the nose,
+  #   :left_brow => [0,-5, :left_eye], # the left eye-brow, above the left eye.
+  # 
+  # Please note that +:center+ is a "virtual" hotspot. When the coordinates of
+  # +:center+ are requested, +myface+'s #center method is called* and the
+  # results used as the coordinates. (* Technically, +myface+ is sent
+  # +:center+, which is not exactly the same as calling #center.)
+  # 
+  # Now, suppose we want to find out where :left_brow is, in absolute
+  # coordinates (i.e. relative to the origin). We can do this, even if +myface+
+  # has moved, or the hotspots have been changed:
+  # 
+  #  myface.left_brow                   # => [5,-2]
+  #  myface.move(20,-12)                # moves the face right and up
+  #  myface.left_brow                   # => [25,-14]
+  #  myface.new_hotspot \
+  #    :left_eye => [-10,3]             # redefine the left_eye hotspot
+  #  myface.left_brow                   # => [20,-9]
+  # 
+  # Where do [5,-2], [25,-24], and [20,-9] come from? They are the vector sums
+  # of each hotspot in the chain: left_brow, left_eye, nose, and center. See
+  # #hotspot for more information.
+  #++
+  # 
+  module Hotspot
+    # :call-seq: def_hotspot label => [x,y,parent]
+    # 
+    # Define +label+ as a simple hotspot, a custom reference coordinate 
+    # point +x+ pixels to the right and +y+ pixels below the hotspot whose
+    # label is +parent+.
+    # You may omit +parent+, in which case the hotspot will evaluate relative
+    # to the origin, i.e. the top-left corner of the Screen.
+    # 
+    # See also #def_smartspot to create a 'smart hotspot'.
+    # 
+    # +label+ must be usable as a key in a Hash table. Additionally, if you
+    # want <code>myobject.{label}</code> to work like 
+    # <code>myobject.hotspot({label})</code>, +label+ must be a :symbol.
+    # 
+    # *IMPORTANT*: Do NOT create circular hotspot chains (e.g. a -> b -> a).
+    # Doing so will raise SystemStackError when #hotspot is asked to evaluate
+    # any hotspot in that chain. Hotspots are not yet smart enough to detect
+    # circular chains.
+    # 
+    # Hotspots can be defined in any order, as long as you define all the
+    # hotspots in a chain before that chain is evaluated with #hotspot.
+    #
+    # You may define multiple hotspots simultaneously by separating the 
+    # definitions by commas. For example:
+    # 
+    #   def_hotspot label => [x,y,parent], label2 => [x,y,parent]
+    # 
+    # Users of the Rake library will recognize this style of syntax.
+    # It is simply constructing a Hash object and passing it as the
+    # only argument to #new_hotspot. The above code is equivalent to:
+    # 
+    #   def_hotspot( { label => [x,y,parent], label2 => [x,y,parent] } )
+    def def_hotspot(dfn)
+      @hotspots.update(dfn)
+    rescue NoMethodError => e
+      unless defined? @hotspots
+        @hotspots = Hash.new
+        retry
+      else raise e
+      end
+    end
+
+    # Remove all simple hotspots whose label is included in +*labels+.
+    def undef_hotspot(*labels)
+      labels.flatten.each do |l|
+        @hotspots.delete(l)
+      end
+    end
+
+    # True if +label+ has been defined as a simple hotspot.
+    def defined_hotspot?(label)
+      @hotspots.include? label
+    rescue NoMethodError => e
+      unless defined? @hotspots
+        false
+      else raise e
+      end
+    end
+
+    # :call-seq: hotspot(label)
+    # 
+    # Returns the absolute coordinates represented by the hotspot +label+.
+    # Will return nil if the hotspot (or one of its ancestors) does not exist.
+    # 
+    # This method will recursively evaluate the hotspot, it's parent hotspot
+    # (if any), and so on, until a parent-less hotspot or a smartspot is found.
+    # 
+    # (*NOTE*: this means that a circular chains (e.g. a -> b -> a)
+    # will keep going around and around until the ruby interpreter
+    # raises SystemStackError!)
+    #
+    # The final value returned by this method will be the vector component sum
+    # of all the hotspots in the chain. For example, if you have this chain:
+    # 
+    #   :a => [1, 2, :b]
+    #   :b => [4, 8, :c]
+    #   :c => [16,32]
+    # 
+    # the value returned for +:a+ would be [21,42], i.e. [1+4+16, 2+8+32]
+    #--
+    # The x and y arguments are used for recursive accumulation, although
+    # I suppose you could use them to create a temporary offset by giving
+    # something besides zero when you look up a hotspot.
+    #++
+    def hotspot(label,x=0,y=0)
+      a = @hotspots[label]
+      if a[2].nil?              # has no parent
+        [x+a[0],y+a[1]]
+      else                      # has a parent
+        hotspot(a[2],x+a[0],y+a[1])
+      end
+    rescue NoMethodError => e
+      if not(defined? @hotspots)
+        return nil
+      elsif a.nil?
+        smartspot(label,x,y)
+      else raise e
+      end
+    end
+
+    # Define each label in +*labels+ as a smartspot ('smart hotspot').
+    # 
+    # To prevent outside objects from abusing hotspots to call arbitrary 
+    # methods, a smartspot must be defined for each method before it can be 
+    # used as a parent to a hotspot.
+    # 
+    # The label must be a :symbol, and it must be identical to the name of the
+    # method to be called.
+    def def_smartspot(*labels)
+      @smartspots += labels.flatten
+      @smartspots.uniq!
+    rescue NoMethodError => e
+      unless defined? @smartspots
+        @smartspots = Array.new
+        retry
+      else raise e
+      end
+    end
+
+    # Remove all smartspots whose label is included in +*labels+.
+    def undef_smartspot(*labels)
+      @smartspots -= labels.flatten
+    end
+
+    # True if +label+ has been defined as a smartspot.
+    def defined_smartspot?(label)
+      @smartspots.include? label
+    rescue NoMethodError => e
+      unless defined? @smartspots
+        false
+      else raise e
+      end
+    end
+
+    # :call-seq: smartspot(label)
+    # 
+    # Evaluate the smartspot +label+, calling the method of the same name as
+    # +label+. Will return nil if no such smartspot has been defined.
+    #--
+    # The x and y arguments are used for recursive accumulation.
+    #++
+    def smartspot(label,x=0,y=0)
+      if @smartspots.include? label
+        a = self.send(label)
+        [x+a[0],y+a[1]]
+      else
+        nil
+      end
+    rescue NoMethodError => e
+      unless defined? @smartspots
+        nil
+      else raise e
+      end
+    end
+
+    #--
+    # 
+    # TODO:
+    # Methods for changing the position of the object indirectly, 
+    # by saying where the hotspot should be.
+    # You could do this: my_object.foot = [5,3], and if foot was defined
+    # relative to, say, #center, it would set center = [5-x_offset, 3-y_offset]
+    # 
+    # It should be recursive to work with chains of hotspots too.
+    # 
+    #++ 
+
+    alias :old_method_missing :method_missing
+
+    def method_missing(symbol,*args)
+      if have_hotspot?(symbol) 
+        hotspot(symbol)
+      else old_method_missing(symbol,*args)
+      end
+    end
+    
+  end
+end

data/lib/rubygame/keyconstants.rb

@@ -0,0 +1,237 @@
+# :enddoc:
+module Rubygame
+ALL_KEYS = {\
+K_BACKSPACE => ["\b", "backspace"],\
+K_TAB => ["\t", "tab"],\
+K_CLEAR => [nil, "clear"],\
+K_RETURN => ["\n", "return", "enter"],\
+K_PAUSE => [nil, "pause"],\
+K_ESCAPE => ["^[", "escape"],\
+K_SPACE => [" ", "space"],\
+K_EXCLAIM => ["!", "exclamation_mark", "exclaim"],\
+K_QUOTEDBL => ["\"", "double_quote"],\
+K_HASH => ["#", "hash", "pound", "bang"],\
+K_DOLLAR => ["$", "dollar"],\
+K_AMPERSAND => ["&", "ampersand", "and"],\
+K_QUOTE => ["'", "quote"],\
+K_LEFTPAREN => ["(", "left_parenthesis", "lparen"],\
+K_RIGHTPAREN => [")", "right_parenthesis","rparen"],\
+K_ASTERISK => ["*", "asterisk"],\
+K_PLUS => ["+", "plus"],\
+K_COMMA => [",", "comma"],\
+K_MINUS => ["-", "minus"],\
+K_PERIOD => [".", "period"],\
+K_SLASH => ["/", "slash"],\
+K_0 => ["0", "numberline_0"],\
+K_1 => ["1", "numberline_1"],\
+K_2 => ["2", "numberline_2"],\
+K_3 => ["3", "numberline_3"],\
+K_4 => ["4", "numberline_4"],\
+K_5 => ["5", "numberline_5"],\
+K_6 => ["6", "numberline_6"],\
+K_7 => ["7", "numberline_7"],\
+K_8 => ["8", "numberline_8"],\
+K_9 => ["9", "numberline_9"],\
+K_COLON => [":", "colon"],\
+K_SEMICOLON => [";", "semicolon"],\
+K_LESS => ["<", "less_than"],\
+K_EQUALS => ["=", "equals"],\
+K_GREATER => [">", "greater_than"],\
+K_QUESTION => ["?", "question_mark", "question"],\
+K_AT => ["@", "at"],\
+K_LEFTBRACKET => ["[", "left_bracket", "lbracket"],\
+K_BACKSLASH => ["\\", "backslash"],\
+K_RIGHTBRACKET => ["]", "right_bracket", "rbracket"],\
+K_CARET => ["^", "caret"],\
+K_UNDERSCORE => ["_", "underscore"],\
+K_BACKQUOTE => ["`", "backquote", "grave"],\
+K_A => ["a"],\
+K_B => ["b"],\
+K_C => ["c"],\
+K_D => ["d"],\
+K_E => ["e"],\
+K_F => ["f"],\
+K_G => ["g"],\
+K_H => ["h"],\
+K_I => ["i"],\
+K_J => ["j"],\
+K_K => ["k"],\
+K_L => ["l"],\
+K_M => ["m"],\
+K_N => ["n"],\
+K_O => ["o"],\
+K_P => ["p"],\
+K_Q => ["q"],\
+K_R => ["r"],\
+K_S => ["s"],\
+K_T => ["t"],\
+K_U => ["u"],\
+K_V => ["v"],\
+K_W => ["w"],\
+K_X => ["x"],\
+K_Y => ["y"],\
+K_Z => ["z"],\
+K_DELETE => [nil, "delete", "del"],\
+K_KP0 => ["0", "kp0", "keypad_0"],\
+K_KP1 => ["1", "kp1", "keypad_1"],\
+K_KP2 => ["2", "kp2", "keypad_2"],\
+K_KP3 => ["3", "kp3", "keypad_3"],\
+K_KP4 => ["4", "kp4", "keypad_4"],\
+K_KP5 => ["5", "kp5", "keypad_5"],\
+K_KP6 => ["6", "kp6", "keypad_6"],\
+K_KP7 => ["7", "kp7", "keypad_7"],\
+K_KP8 => ["8", "kp8", "keypad_8"],\
+K_KP9 => ["9", "kp9", "keypad_9"],\
+K_KP_PERIOD => [".", "period", "keypad_period"],\
+K_KP_DIVIDE => ["/", "divide", "keypad_divide"],\
+K_KP_MULTIPLY => ["*", "multiply", "keypad_multiply"],\
+K_KP_MINUS => ["-", "minus", "keypad_minus"],\
+K_KP_PLUS => ["+", "plus", "keypad_plus"],\
+K_KP_ENTER => ["\n", "enter", "keypad_enter"],\
+K_KP_EQUALS => ["=", "equals", "keypad_equals"],\
+K_UP => [nil, "up"],\
+K_DOWN => [nil, "down"],\
+K_RIGHT => [nil, "right"],\
+K_LEFT => [nil, "left"],\
+K_INSERT => [nil, "insert", "ins"],\
+K_HOME => [nil, "home"],\
+K_END => [nil, "end"],\
+K_PAGEUP => [nil, "page_up", "pgup"],\
+K_PAGEDOWN => [nil, "page_down", "pgdn"],\
+K_F1 => [nil, "f1", "function_1"],\
+K_F2 => [nil, "f2", "function_2"],\
+K_F3 => [nil, "f3", "function_3"],\
+K_F4 => [nil, "f4", "function_4"],\
+K_F5 => [nil, "f5", "function_5"],\
+K_F6 => [nil, "f6", "function_6"],\
+K_F7 => [nil, "f7", "function_7"],\
+K_F8 => [nil, "f8", "function_8"],\
+K_F9 => [nil, "f9", "function_9"],\
+K_F10 => [nil, "f10", "function_10"],\
+K_F11 => [nil, "f11", "function_11"],\
+K_F12 => [nil, "f12", "function_12"],\
+K_F13 => [nil, "f13", "function_13"],\
+K_F14 => [nil, "f14", "function_14"],\
+K_F15 => [nil, "f15", "function_15"],\
+K_NUMLOCK => [nil, "numlock"],\
+K_CAPSLOCK => [nil, "capslock", "caplock"],\
+K_SCROLLOCK => [nil, "scroll_lock", "scrollock", "scrolllock"],\
+K_LSHIFT => [nil, "left_shift", "lshift"],\
+K_RSHIFT => [nil, "right_shift", "rshift"],\
+K_LCTRL => [nil, "left_control", "lctrl"],\
+K_RCTRL => [nil, "right_control", "rctrl"],\
+K_LALT => [nil, "left_alt", "lalt"],\
+K_RALT => [nil, "right_alt", "ralt"],\
+K_LMETA => [nil, "left_meta", "lmeta"],\
+K_RMETA => [nil, "right_meta", "rmeta"],\
+K_LSUPER => [nil, "left_super", "lsuper"],\
+K_RSUPER => [nil, "right_super", "rsuper"],\
+K_MODE => [nil, "mode"],\
+K_HELP => [nil, "help"],\
+K_PRINT => [nil, "print_screen","prt_scr","print"],\
+K_SYSREQ => [nil, "sysrq", "sysreq", "system_request"],\
+K_BREAK => [nil, "break"],\
+K_MENU => [nil, "menu"],\
+K_POWER => [nil, "power"],\
+# I have no idea how to get a Euro symbol here!
+K_EURO => ["\u20ac", "euro"],\
+# just K_WORLD_0 to K_WORLD_95 after this
+K_WORLD_0 => [nil, "world_0"],\
+K_WORLD_1 => [nil, "world_1"],\
+K_WORLD_2 => [nil, "world_2"],\
+K_WORLD_3 => [nil, "world_3"],\
+K_WORLD_4 => [nil, "world_4"],\
+K_WORLD_5 => [nil, "world_5"],\
+K_WORLD_6 => [nil, "world_6"],\
+K_WORLD_7 => [nil, "world_7"],\
+K_WORLD_8 => [nil, "world_8"],\
+K_WORLD_9 => [nil, "world_9"],\
+K_WORLD_10 => [nil, "world_10"],\
+K_WORLD_11 => [nil, "world_11"],\
+K_WORLD_12 => [nil, "world_12"],\
+K_WORLD_13 => [nil, "world_13"],\
+K_WORLD_14 => [nil, "world_14"],\
+K_WORLD_15 => [nil, "world_15"],\
+K_WORLD_16 => [nil, "world_16"],\
+K_WORLD_17 => [nil, "world_17"],\
+K_WORLD_18 => [nil, "world_18"],\
+K_WORLD_19 => [nil, "world_19"],\
+K_WORLD_20 => [nil, "world_20"],\
+K_WORLD_21 => [nil, "world_21"],\
+K_WORLD_22 => [nil, "world_22"],\
+K_WORLD_23 => [nil, "world_23"],\
+K_WORLD_24 => [nil, "world_24"],\
+K_WORLD_25 => [nil, "world_25"],\
+K_WORLD_26 => [nil, "world_26"],\
+K_WORLD_27 => [nil, "world_27"],\
+K_WORLD_28 => [nil, "world_28"],\
+K_WORLD_29 => [nil, "world_29"],\
+K_WORLD_30 => [nil, "world_30"],\
+K_WORLD_31 => [nil, "world_31"],\
+K_WORLD_32 => [nil, "world_32"],\
+K_WORLD_33 => [nil, "world_33"],\
+K_WORLD_34 => [nil, "world_34"],\
+K_WORLD_35 => [nil, "world_35"],\
+K_WORLD_36 => [nil, "world_36"],\
+K_WORLD_37 => [nil, "world_37"],\
+K_WORLD_38 => [nil, "world_38"],\
+K_WORLD_39 => [nil, "world_39"],\
+K_WORLD_40 => [nil, "world_40"],\
+K_WORLD_41 => [nil, "world_41"],\
+K_WORLD_41 => [nil, "world_41"],\
+K_WORLD_42 => [nil, "world_42"],\
+K_WORLD_43 => [nil, "world_43"],\
+K_WORLD_44 => [nil, "world_44"],\
+K_WORLD_45 => [nil, "world_45"],\
+K_WORLD_46 => [nil, "world_46"],\
+K_WORLD_47 => [nil, "world_47"],\
+K_WORLD_48 => [nil, "world_48"],\
+K_WORLD_49 => [nil, "world_49"],\
+K_WORLD_50 => [nil, "world_50"],\
+K_WORLD_51 => [nil, "world_51"],\
+K_WORLD_52 => [nil, "world_52"],\
+K_WORLD_53 => [nil, "world_53"],\
+K_WORLD_54 => [nil, "world_54"],\
+K_WORLD_55 => [nil, "world_55"],\
+K_WORLD_56 => [nil, "world_56"],\
+K_WORLD_57 => [nil, "world_57"],\
+K_WORLD_58 => [nil, "world_58"],\
+K_WORLD_59 => [nil, "world_59"],\
+K_WORLD_60 => [nil, "world_60"],\
+K_WORLD_61 => [nil, "world_61"],\
+K_WORLD_62 => [nil, "world_62"],\
+K_WORLD_63 => [nil, "world_63"],\
+K_WORLD_64 => [nil, "world_64"],\
+K_WORLD_65 => [nil, "world_65"],\
+K_WORLD_66 => [nil, "world_66"],\
+K_WORLD_67 => [nil, "world_67"],\
+K_WORLD_68 => [nil, "world_68"],\
+K_WORLD_69 => [nil, "world_69"],\
+K_WORLD_70 => [nil, "world_70"],\
+K_WORLD_71 => [nil, "world_71"],\
+K_WORLD_72 => [nil, "world_72"],\
+K_WORLD_73 => [nil, "world_73"],\
+K_WORLD_74 => [nil, "world_74"],\
+K_WORLD_75 => [nil, "world_75"],\
+K_WORLD_76 => [nil, "world_76"],\
+K_WORLD_77 => [nil, "world_77"],\
+K_WORLD_78 => [nil, "world_78"],\
+K_WORLD_79 => [nil, "world_79"],\
+K_WORLD_80 => [nil, "world_80"],\
+K_WORLD_81 => [nil, "world_81"],\
+K_WORLD_82 => [nil, "world_82"],\
+K_WORLD_83 => [nil, "world_83"],\
+K_WORLD_84 => [nil, "world_84"],\
+K_WORLD_85 => [nil, "world_85"],\
+K_WORLD_86 => [nil, "world_86"],\
+K_WORLD_87 => [nil, "world_87"],\
+K_WORLD_88 => [nil, "world_88"],\
+K_WORLD_89 => [nil, "world_89"],\
+K_WORLD_90 => [nil, "world_90"],\
+K_WORLD_91 => [nil, "world_91"],\
+K_WORLD_92 => [nil, "world_92"],\
+K_WORLD_93 => [nil, "world_93"],\
+K_WORLD_94 => [nil, "world_94"],\
+K_WORLD_95 => [nil, "world_95"],\
+}
+end