### Home Classes Methods

### In Files

- lib/rubygame/event_handler.rb

### Methods

- #append_hook
- #handle
- #has_hook?
- #make_magic_hooks
- #make_magic_hooks_for
- #prepend_hook
- #remove_hook

### Files

- CREDITS
- LICENSE
- NEWS
- README
- ROADMAP
- custom_sdl_load_paths.rdoc
- getting_started.rdoc
- keyboard_symbols.rdoc
- macosx_install.rdoc
- managing_framerate.rdoc
- surface_palettes.rdoc
- windows_install.rdoc

### Class/Module Index

Quicksearch

- Rubygame
- Rubygame::ActiveEvent
- Rubygame::Clock
- Rubygame::Color
- Rubygame::Color::ColorBase
- Rubygame::Color::ColorHSL
- Rubygame::Color::ColorHSV
- Rubygame::Color::ColorRGB
- Rubygame::Color::Palette
- Rubygame::Event
- Rubygame::EventActions
- Rubygame::EventActions::BlockAction
- Rubygame::EventActions::MethodAction
- Rubygame::EventActions::MultiAction
- Rubygame::EventHandler
- Rubygame::EventHandler::HasEventHandler
- Rubygame::EventHook
- Rubygame::EventQueue
- Rubygame::EventTriggers
- Rubygame::EventTriggers::AndTrigger
- Rubygame::EventTriggers::AttrTrigger
- Rubygame::EventTriggers::BlockTrigger
- Rubygame::EventTriggers::InstanceOfTrigger
- Rubygame::EventTriggers::KeyPressTrigger
- Rubygame::EventTriggers::KeyReleaseTrigger
- Rubygame::EventTriggers::KindOfTrigger
- Rubygame::EventTriggers::MouseMoveTrigger
- Rubygame::EventTriggers::MousePressTrigger
- Rubygame::EventTriggers::MouseReleaseTrigger
- Rubygame::EventTriggers::OrTrigger
- Rubygame::EventTriggers::TickTrigger
- Rubygame::EventTriggers::YesTrigger
- Rubygame::Events
- Rubygame::Events::ClockTicked
- Rubygame::Events::InputFocusGained
- Rubygame::Events::InputFocusLost
- Rubygame::Events::JoystickAxisMoved
- Rubygame::Events::JoystickBallMoved
- Rubygame::Events::JoystickButtonEvent
- Rubygame::Events::JoystickButtonPressed
- Rubygame::Events::JoystickButtonReleased
- Rubygame::Events::JoystickHatMoved
- Rubygame::Events::KeyPressed
- Rubygame::Events::KeyReleased
- Rubygame::Events::KeyboardEvent
- Rubygame::Events::MouseButtonEvent
- Rubygame::Events::MouseFocusGained
- Rubygame::Events::MouseFocusLost
- Rubygame::Events::MouseMoved
- Rubygame::Events::MousePressed
- Rubygame::Events::MouseReleased
- Rubygame::Events::QuitRequested
- Rubygame::Events::WindowExposed
- Rubygame::Events::WindowMinimized
- Rubygame::Events::WindowResized
- Rubygame::Events::WindowUnminimized
- Rubygame::ExposeEvent
- Rubygame::Ftor
- Rubygame::GL
- Rubygame::Hotspot
- Rubygame::JoyAxisEvent
- Rubygame::JoyBallEvent
- Rubygame::JoyDownEvent
- Rubygame::JoyHatEvent
- Rubygame::JoyUpEvent
- Rubygame::Joystick
- Rubygame::Key
- Rubygame::KeyDownEvent
- Rubygame::KeyUpEvent
- Rubygame::MailQueue
- Rubygame::MediaBag
- Rubygame::Mixer
- Rubygame::Mixer::Music
- Rubygame::Mixer::Sample
- Rubygame::Mouse
- Rubygame::MouseDownEvent
- Rubygame::MouseMotionEvent
- Rubygame::MouseUpEvent
- Rubygame::Music
- Rubygame::NamedResource
- Rubygame::NamedResource::NamedResourceClassMethods
- Rubygame::QuitEvent
- Rubygame::Rect
- Rubygame::ResizeEvent
- Rubygame::SDLError
- Rubygame::SFont
- Rubygame::Screen
- Rubygame::Sound
- Rubygame::Sprites
- Rubygame::Sprites::DepthSortGroup
- Rubygame::Sprites::Group
- Rubygame::Sprites::LimitGroup
- Rubygame::Sprites::Sprite
- Rubygame::Sprites::UpdateGroup
- Rubygame::Surface
- Rubygame::TTF

No matching classes.

# Rubygame::EventHandler::HasEventHandler

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.

### Public Instance Methods

append_hook( hook ) click to toggle source

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 )

    # 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

handle( event ) click to toggle source

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

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

has_hook?( hook ) click to toggle source

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

    # 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

make_magic_hooks( hooks_hash ) click to toggle source

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 )

    # 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

make_magic_hooks_for( owner, hooks_hash ) click to toggle source

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.

    # 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

prepend_hook( hook ) click to toggle source

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.

    # 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_hook( hook ) click to toggle source

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.

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

Generated with the Darkfish Rdoc Generator 2.