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 )



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

def append_hook( hook )
	hook = _prepare_hook( hook )
	@event_handler.append_hook( hook )
rescue NoMethodError
	_make_event_handler
	retry
end

#handle(event) ⇒ Object

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



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

def handle( event )
	@event_handler.handle( event )
rescue NoMethodError
	_make_event_handler
	retry
end

#has_hook?(hook) ⇒ Boolean

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

Returns:

  • (Boolean) 


228
229
230
231
232
233
 
# File 'lib/rubygame/event_handler.rb', line 228

def has_hook?( hook )
	@event_handler.has_hook?( hook )
rescue NoMethodError
	_make_event_handler
	retry
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 )



292
293
294
295
296
297
 
# File 'lib/rubygame/event_handler.rb', line 292

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.



304
305
306
307
308
309
310
 
# File 'lib/rubygame/event_handler.rb', line 304

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.



318
319
320
321
322
323
324
 
# File 'lib/rubygame/event_handler.rb', line 318

def prepend_hook( hook )
	hook = _prepare_hook( hook )
	@event_handler.prepend_hook( hook )
rescue NoMethodError
	_make_event_handler
	retry
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.



333
334
335
336
337
338
 
# File 'lib/rubygame/event_handler.rb', line 333

def remove_hook( hook )
	@event_handler.remove_hook( hook )
rescue NoMethodError
	_make_event_handler
	retry
end