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

def_hotspot def_smartspot defined_hotspot? defined_smartspot? hotspot method_missing smartspot undef_hotspot undef_smartspot

### External Aliases

method_missing | -> | old_method_missing

### Public Instance methods

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 `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] } )

def_smartspot(*labels)

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.

defined_hotspot?(label)

True if `label` has been defined as a simple hotspot.

defined_smartspot?(label)

True if `label` has been defined as a smartspot.

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]

method_missing(symbol,*args)
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.

undef_hotspot(*labels)

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

undef_smartspot(*labels)

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

[Validate]