Module | Rubygame::EventHandler::HasEventHandler
In: | lib/rubygame/event_handler.rb

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.

### Methods

append_hook handle has_hook? make_magic_hooks make_magic_hooks_for prepend_hook remove_hook

### Public Instance methods

append_hook( hook )

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 )

handle( event )

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

has_hook?( hook )

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

make_magic_hooks( hooks_hash )

Convenience method for creating and appending hooks easily. It takes a Hash of {trigger_seed => 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 )

make_magic_hooks_for( owner, hooks_hash )

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.

prepend_hook( hook )

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.

remove_hook( hook )

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.

[Validate]