### Home Classes Methods

### In Files

- lib/rubygame/event_handler.rb

### Parent

Object

### Namespace

- MODULE Rubygame::EventHandler::HasEventHandler

### Methods

- ::new
- #append_hook
- #handle
- #has_hook?
- #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

EventHandler provides a simple, extensible system for hook-based event handling.

An EventHandler holds a list of EventHook objects. When the EventHandler receives a new event (passed to handle), it tests the event against each EventHook. If the event matches the EventHook, the EventHandler passes the event to the EventHook to perform an action (such as calling a method or executing a block).

Although the EventHandler and EventHook classes are very simple in themselves, they can be used as building blocks to create flexible and complex systems, whatever is needed by your application.

Here are a few ways you could use EventHandler:

- One central EventHandler with EventHooks to perform all types of actions. This is good for simple apps.

- Multiple EventHandlers, one for each category of event. For example, one for keyboard input, one for mouse input, one for game logic events, etc.

- An EventHandler in every game object (using the HasEventHandler mixin module), being fed events from a central EventHandler.

You can also extend the possibilities of EventHandler and EventHook by creating your own event trigger and action classes. See EventHook for more information.

### Attributes

hooks[RW]

### Public Class Methods

new { |handler| ... } → new_handler click to toggle source

Create a new EventHandler. The optional block can be used for further initializing the EventHandler.

    # File lib/rubygame/event_handler.rb, line 67
    def initialize(&block)
            @hooks = []
            yield self if block_given?
    end

### Public Instance Methods

append_hook( hook ) → hook click to toggle source
append_hook( description ) → hook

Puts an EventHook at the bottom of the stack (it will be handled last). If the EventHandler already has that hook, it is moved to the bottom. See EventHook and handle.

This method has two distinct forms. The first form adds an existing Hook instance; the second form constructs a new EventHook instance and adds it.

hook | the hook to add. (EventHook, for first form only)
description | a Hash to initialize a new EventHook. (Hash, for second form only)
Returns | the hook that was added. (EventHook)

Contrast this method with prepend, which puts the EventHook at the top of the stack.

    # File lib/rubygame/event_handler.rb, line 95
    def append_hook( hook )
            hook = Rubygame::EventHook.new( hook ) if hook.kind_of?( Hash )
            @hooks = (@hooks - [hook]) | [hook]
            return hook
    end

handle( event ) → nil click to toggle source

Triggers every hook in the stack which matches the given event. See EventHook.

If one of the matching hooks has @consumes enabled, no hooks after it will receive that event. (Example use: a mouse click that only affects the top-most object it hits, not any below it.)

event: the event to handle. (Object, required)

Returns | nil.

    # File lib/rubygame/event_handler.rb, line 129
    def handle( event )
            matching_hooks = @hooks.select { |hook| hook.match?( event ) }

            catch :event_consumed do
                    matching_hooks.each do |hook|
                            hook.perform( event )
                            throw :event_consumed if hook.consumes
                    end
            end

            return nil
    end

has_hook?( hook ) click to toggle source

Returns true if the given EventHook instance is on the stack.

    # File lib/rubygame/event_handler.rb, line 143
    def has_hook?( hook )
            @hooks.include?( hook )
    end

prepend_hook( hook ) → hook click to toggle source
prepend_hook( description ) → hook

Exactly like append_hook, except that the EventHook is put at the top of the stack (it will be handled first). If the EventHandler already has that hook, it is moved to the top.

    # File lib/rubygame/event_handler.rb, line 109
    def prepend_hook( hook )
            hook = Rubygame::EventHook.new( hook ) if hook.kind_of?( Hash )
            @hooks = [hook] | @hooks
            return hook
    end

remove_hook( hook ) click to toggle source

Removes the given EventHook instance from the stack, if it exists on the stack.

Returns | the hook that was removed, or nil if the hook did not exist on the stack.

NOTE: You must pass the exact EventHook instance to remove it! Passing another EventHook that is "similar" will not work. So, you should store a reference to the hook when it is returned by append_hook or prepend_hook.

    # File lib/rubygame/event_handler.rb, line 158
    def remove_hook( hook )
            @hooks.delete( hook )
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.