Class | Rubygame::EventHook
In: | lib/rubygame/event_hook.rb
Parent: | Object

The EventHook class provides the bare framework for event hooks used by EventHandler. Each hook has a trigger, which controls what types of events cause the hook to engage, and an action, which controls what should happen when the hook engages.

An instance of EventHook has these attributes:

owner: | the object that this hook applies to. This value will be provided to the action when the hook engages.
trigger: | an instance of a trigger class, used to test every event to check whether the hook should engage. A valid trigger must have a match? method which accepts an event and returns either true or false.
action: | an instance of an action class, which is performed when the trigger matches an event. A valid action must have a perform method which accepts two values: the hook‘s owner and the matching event.
consumes: | if true, the event hook "eats" every event that it matches, so that hooks that come after it will not see the event. Has no effect on non-matching events.
active: | if false, the event hook is disabled, and will not match any event until it is set to true again. You can use this to temporarily disable the hook.

### Methods

match? new perform

### Attributes

action | [RW] |
active | [RW] |
consumes | [RW] |
owner | [RW] |
trigger | [RW] |

### Public Class methods

new( description={} )

Create a new instance of EventHook. Description is a Hash with the following keys. See the class documentation for EventHook for more information about what these mean.

:owner : | the hook‘s owner. (any object, required)
:trigger : | an event trigger which matches certain events. (Object with +match?(event)+, required)
:action : | an event action to do when an event matches. (Object with +perform(owner,event)+, required)
:consumes : | if true, the hook will "eat" matching so later hooks won‘t see them. Default: false. (true or false, optional)
:active : | if false, the hook will ignore all events. Default: true. (true or false, optional)

NOTE: None of the attributes are truly required to create a hook. But, the hook will do nothing unless both @trigger and @action are set. Setting @owner is also highly recommended, because some types of actions use the owner, and may raise an error if it is nil.

TIP: It‘s possible to set these attributes at any time using the accessors. For example, You could change keyboard controls on the fly, or temporarily deactivate a hook to stop it from engaging.

Example:

      # Call player1.jump() when the space bar is pressed.
      EventHook.new( :owner   => player1,
                     :trigger => KeyPressTrigger.new(:space)
                     :action  => MethodAction.new(:jump) )

### Public Instance methods

match?( event )

Passes the event to @trigger‘s match? method, and returns the result. If there is no @trigger or if @active is false, returns nil immediately.

perform( event )

Passes @owner and event to the @action‘s perform method.

[Validate]