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

Public Instance methods

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 )

[Source]

# 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

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

[Source]

# File lib/rubygame/event_handler.rb, line 219
        def handle( event )
                _make_event_handler if @event_handler.nil?
                @event_handler.handle( event )
        end

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

[Source]

# 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

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 )

[Source]

# 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

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.

[Source]

# 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

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.

[Source]

# 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 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.

[Source]

# 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

[Validate]