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

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) )

[Source]

# File lib/rubygame/event_hook.rb, line 91
  def initialize( description={} )
    @owner    = description[:owner]
    @trigger  = description[:trigger]
    @action   = description[:action]
    @consumes = (description[:consumes] or false)
    @active   = (description[:active].nil? ? true : description[:active])
  end

Public Instance methods

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.

[Source]

# File lib/rubygame/event_hook.rb, line 102
  def match?( event )
    if (@trigger and @active)
      @trigger.match?( event ) 
    else
      false
    end
  end

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

[Source]

# File lib/rubygame/event_hook.rb, line 111
  def perform( event )
    @action.perform( owner, event ) if @action
  end

[Validate]