NAME

SDL::EventHandler - base class for application-specific SDL event handlers

SYNOPSIS

    # load the event class and this library
    load_bytecode 'library/SDL/Event.pir'
    load_bytecode 'library/SDL/EventHandler.pir'

    # subclass this class
    .local pmc parent_class
    .local pmc class_type

    get_class parent_class, 'SDL::EventHandler'
    subclass class_type, parent_class, 'My::Event::Handler'

    # define your overridden methods
    .sub key_down_down :method
        .param pmc event
        .param pmc event_args

        # ...

    .end

    # create an event handler object
    .local pmc event_handler
    event_handler = new 'My::Event::Handler'

    # create and populate some event_arguments
    .local pmc event_args

    new event_args, 'Hash'
    event_args[ 'main_surface' ] = main_surface
    event_args[ 'sprite_list'  ] = sprites

    # create a new event object
    .local pmc event
    event = new 'SDL::Event'

    # ... and process events
    event.'process_events'( event_handler, handler_args )

DESCRIPTION

SDL::EventHandler is a parent class for all event handlers in SDL Parrot programs. Subclass this class and override the methods that correspond to the events you want to handle.

METHODS

SDL::EventHandler provides the following methods:

key_down( event, event_args )

Dispatches a key down event to the appropriate key_down_keyname method, if one exists. Otherwise, does nothing.Override this if you want to change the way dispatching happens or to do something different for all key down events. In general, you will probably want to override the key_down_* methods instead.XXX The * above i.e. the actually key_name isn't really documented. But:

  $ perldoc SDL::Event

might be helpful (for now), if you remove SDLK_ and lowercase the remainder - sorry.

  .sub key_down_q         # 'q' key
  .sub key_down_down      # <down> arrow key
  .sub key_down_kp_plus   # <keypad-plus> key
  ...

key_up( event, event_args )

Dispatches a key up event to the appropriate key_upkeyname method, if one exists. Otherwise, does nothing.Override this if you want to change the way dispatching happens or to do something different for all key up events. In general, you will probably want to override the key_up_* methods instead.

Key Event Methods

Key event methods have names of the form key_eventtype_keyname. That is, to handle a key down event for the Escape key, override the method key_down_escape. Key names follow the SDL naming convention, except that key names are in all lowercase.

Unless you override key_down or key_up and do something different, all of these methods will receive one argument, the event_args hash passed to SDL::Event::wait_event(). Use this hash to store and to retrieve data between events, particularly your main surface and any sprites or other surfaces.

Other Event Methods

In addition, you can override the following methods to handle their event types.

• active_event
• mouse_motion
• mouse_button_down
• mouse_button_up

Synopsis for mouse event handler:

  .sub mouse_button_up :method
    .param pmc event
    .param pmc args

    .local int b, x, y
    event = event.'event'( 'MouseButton' )
    b = event['state']    # 1 = left, 2 = middle, 3 = right
    x = event['x']
    y = event['y']
    ...

• joy_axis_motion
• joy_ball_motion
• joy_hat_motion
• joy_button_down
• joy_button_up
• quit
• sys_wm_event
• video_resize
• video_expose
• event_reserved_a
• event_reserved_b
• event_reserved_2
• event_reserved_3
• event_reserved_4
• event_reserved_5
• event_reserved_6
• event_reserved_7

By default, these methods do nothing. They all take two arguments, the SDL::Event object representing the incoming event and the event_args hash storing data between events.

At the very least, you should override quit().

AUTHOR

Written and maintained by chromatic, <chromatic at wgz dot org>. Designed by Allison Randal. Please send patches, feedback, and suggestions to the Perl 6 Internals mailing list.

COPYRIGHT

Copyright (C) 2004-2008, Parrot Foundation.