Module: Rubygame::EventHandler::HasEventHandler

Defined in:
lib/rubygame/event_handler.rb

Overview

HasEventHandler is a mixin module to conveniently integrate EventHandler into any class, allowing instances of the class to hold event hooks and handle incoming events.

To use HasEventHandler, you simply ‘include’ it in your class:

class Player
  include Rubygame::EventHandler::HasEventHandler

  # ... the rest of your class ...

end

You can then use all of the functionality of HasEventHandler.

HasEventHandler provides several methods for adding new event hooks to the object. The two basic methods for that are #append_hook and #prepend_hook. The #make_magic_hooks method can create multiple hooks very simply and conveniently.

HasEventHandler also defines the #handle method, which accepts an event and gives it to the object’s event handler. This is the recommended way to make the object process an event.

Instance Method Summary collapse

Instance Method Details

#append_hook(hook) ⇒ Object

Appends a new hook to the end of the list. If the hook does not have an owner, the owner is set to this object before appending.

hook

the hook to append. (EventHook or Hash description, required)

See also EventHandler#append_hook.

Example:

# Create and append new hook from a description:
trigger = KeyPressedTrigger.new(:space)
action  = MethodAction.new(:jump)
player.append_hook( :trigger => trigger, :action  => action )

# You can also give it an EventHook instance, if you want.
hook = EventHook.new( :trigger => trigger, :action => action )
player.append_hook( hook )



212
213
214
215
216
 
# File 'lib/rubygame/event_handler.rb', line 212

def append_hook( hook )
  _make_event_handler if @event_handler.nil?
  hook = _prepare_hook( hook )
  @event_handler.append_hook( hook )
end

#handle(event) ⇒ Object

Passes the given event to the object’s event handler.



219
220
221
222
 
# File 'lib/rubygame/event_handler.rb', line 219

def handle( event )
  _make_event_handler if @event_handler.nil?
  @event_handler.handle( event )
end

#has_hook?(hook) ⇒ Boolean

Returns true if the object’s event handler includes the given EventHook instance.

Returns:

  • (Boolean) 


226
227
228
229
 
# File 'lib/rubygame/event_handler.rb', line 226

def has_hook?( hook )
  _make_event_handler if @event_handler.nil?
  @event_handler.has_hook?( hook )
end

#make_magic_hooks(hooks_hash) ⇒ Object

Convenience method for creating and appending hooks easily. It takes a Hash of => action_seed pairs, and creates and appends a new EventHook for each pair.

Returns

an Array of the EventHook instances that were created and appended.

May raise

ArgumentError, if an object doesn’t match any conversion rules.

Trigger and action can be symbols, classes, or other types of object. The method uses simple rules to convert the “seed” objects into appropriate event triggers or event actions.

By default, triggers are converted according to these rules:

* Symbols starting with "mouse" become a MouseClickTrigger.
* The symbol :tick becomes a TickTrigger. (Rubygame 2.5+)
* Keyboard symbols become a KeyPressTrigger.
* Classes become an InstanceOfTrigger.
* Objects with a #match? method are duplicated and used
  as the trigger without being converted.

By default, actions are converted according to these rules:

* Symbols become a MethodAction.
* Proc and Method instances become a BlockAction.
* Objects with a #perform method are duplicated and used
  as the action without being converted.

This method raises ArgumentError if an object doesn’t match any of the conversion rules.

You can define your own custom conversion rules by overriding the private methods #_make_magic_trigger and #make_magic_action in your class.

NOTE: Additional default rules may be added in the future, but objects which match the existing rules will continue to match them. However, objects which are invalid in one version might become valid in future versions, if a new rule is added. So, you should never depend on ArgumentError being raised for a paricular object!

Example:

died_action = proc { |owner, event| 
  owner.say "Blargh, I'm dead!" if event.who_died == owner
}

player.make_magic_hooks( :space      => :jump,
                         :left       => :move_left,
                         :right      => :move_right,
                         :mouse_left => :shoot,
                         DiedEvent   => died_action )



288
289
290
291
292
293
 
# File 'lib/rubygame/event_handler.rb', line 288

def make_magic_hooks( hooks_hash )
  hooks_hash.collect do |trigger, action|
    append_hook( :trigger => _make_magic_trigger( trigger ),
                 :action  => _make_magic_action(  action  ))
  end
end

#make_magic_hooks_for(owner, hooks_hash) ⇒ Object

Exactly like #make_magic_hooks, but the hooks’ owner will be the given object, instead of self. See EventHook for more information about hook owners.



300
301
302
303
304
305
306
 
# File 'lib/rubygame/event_handler.rb', line 300

def make_magic_hooks_for( owner, hooks_hash )
  hooks_hash.collect do |trigger, action|
    append_hook( :owner   => owner,
                 :trigger => _make_magic_trigger( trigger ),
                 :action  => _make_magic_action(  action  ) )
  end
end

#prepend_hook(hook) ⇒ Object

Exactly like #append_hook, except that the hook is put at the top of the stack (it will be handled first).

See also EventHandler#prepend_hook.



314
315
316
317
318
 
# File 'lib/rubygame/event_handler.rb', line 314

def prepend_hook( hook )
  _make_event_handler if @event_handler.nil?
  hook = _prepare_hook( hook )
  @event_handler.prepend_hook( hook )
end

#remove_hook(hook) ⇒ Object

Remove the given EventHook instance from the stack, if it exists on the stack. See EventHandler#remove_hook for details and restrictions.

Returns

the hook that was removed, or nil if the hook did not exist on the stack.



327
328
329
330
 
# File 'lib/rubygame/event_handler.rb', line 327

def remove_hook( hook )
  _make_event_handler if @event_handler.nil?
  @event_handler.remove_hook( hook )
end