Module Rubygame::Hotspot
In: lib/rubygame/hotspot.rb

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.

Methods

Public Instance methods

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 myobject.{label} to work like myobject.hotspot({label}), 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] } )

[Source]

# File lib/rubygame/hotspot.rb, line 120
    def def_hotspot(dfn)
      @hotspots.update(dfn)
    rescue NoMethodError => e
      unless defined? @hotspots
        @hotspots = Hash.new
        retry
      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.

[Source]

# File lib/rubygame/hotspot.rb, line 196
    def def_smartspot(*labels)
      @smartspots += labels.flatten
      @smartspots.uniq!
    rescue NoMethodError => e
      unless defined? @smartspots
        @smartspots = Array.new
        retry
      else raise e
      end
    end

True if label has been defined as a simple hotspot.

[Source]

# File lib/rubygame/hotspot.rb, line 138
    def defined_hotspot?(label)
      @hotspots.include? label
    rescue NoMethodError => e
      unless defined? @hotspots
        false
      else raise e
      end
    end

True if label has been defined as a smartspot.

[Source]

# File lib/rubygame/hotspot.rb, line 213
    def defined_smartspot?(label)
      @smartspots.include? label
    rescue NoMethodError => e
      unless defined? @smartspots
        false
      else raise e
      end
    end

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]

[Source]

# File lib/rubygame/hotspot.rb, line 172
    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

[Source]

# File lib/rubygame/hotspot.rb, line 257
    def method_missing(symbol,*args)
      if have_hotspot?(symbol) 
        hotspot(symbol)
      else old_method_missing(symbol,*args)
      end
    end
old_method_missing(symbol,*args)

Alias for method_missing

Evaluate the smartspot label, calling the method of the same name as label. Will return nil if no such smartspot has been defined.

[Source]

# File lib/rubygame/hotspot.rb, line 229
    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

Remove all simple hotspots whose label is included in +*labels+.

[Source]

# File lib/rubygame/hotspot.rb, line 131
    def undef_hotspot(*labels)
      labels.flatten.each do |l|
        @hotspots.delete(l)
      end
    end

Remove all smartspots whose label is included in +*labels+.

[Source]

# File lib/rubygame/hotspot.rb, line 208
    def undef_smartspot(*labels)
      @smartspots -= labels.flatten
    end

[Validate]