NAME ^

SDL::Event - Parrot extension representing SDL Events

SYNOPSIS ^

        # load this library
        load_bytecode 'library/SDL/Event.pir'

        # create a new SDL::Event object
        .local pmc event
        .local int event_type

        find_type event_type, 'SDL::Event'
        event = new event_type

        # ... create a new event_handler and its hander_args

        # start the event loop
        event.'process_events'( event_handler, handler_args )

        # or handle one event at a time in your own loop
        event.'handle_event'( event_handler, handler_args )

DESCRIPTION ^

SDL::Event encapsulates event information for SDL. This may change internally as we migrate to Parrot events, but most of the interesting information happens in SDL::EventHandler instead, so go read that first.

You may discover that you don't really care about this class beyond what you've already learned from the SYNOPSIS already.

METHODS ^

The SDL::Event object has the following methods:

init()

Initializes the internal attributes of this object. Trust me, you need to do this, at least for now.

The name of this method may change, per discussion on p6i. It may even go away.

event()

Returns the underlying SDL_Event structure. You probably don't need to use this directly, unless you're working with raw SDL calls.

event_type( event_type )

Given the number of an incoming event type, returns a string name representing that event. The possible event names live in the SDL_Event.h library; they're all lower cased here. For example, a key down event will have the name key_down.

If you pass an unknown event type identifier, you'll receive a string containing unknown.

Note: Arguably, this should operate on the current event, instead of requiring an argument. This may change in the future.

event_keyname()

Returns a string representing the name of the key for the current event. Note that the list of available keys is rather limited at the moment. There's also no error checking that the current event is even a key event.

On the other hand, you probably should define an event handler instead of using these methods directly.

If this method does not recognize the current key, it will return the string unknown instead.

process_events( event_handler, handler_args, [ check_interval ] )

Given an event_handler object (either subclassing SDL::EventHandler or implementing its necessary methods) and a Hash of arguments to pass to all event handlers, loops around SDL's event loop and calls appropriate methods in event_handler corresponding to what happens.

That is, if SDL reports a key down, this will call the key_down method of event_handler, passing handler_args.

If you pass a numeric value as check_interval, this will poll for events every check_interval seconds. This makes it possible to check for events in your main thread, without breaking Parrot's own event loop (used for timers, for example). This is an optional parameter and can be any number of seconds or fractions thereof.

For now, this will return if it detects a quit event. This may not be what you want and it may change in the future. It won't return otherwise. Arguably, it should, somehow.

handle_event( event_handler, handler_args )

Given an event_handler object (either subclass SDL::EventHandler or reimplement the appropriate methods yourself) and a Hash PMC of data to pass to all handler calls, handles one event, if any are present. If there are no events pending, this will return directly.

This returns nothing interesting. Perhaps it should return true or false depending on whether it handled an event. Perhaps not.

Use this method inside your own loop structure.

dispatch_event( event, event_handler, handler_args )

Dispatches an event. You shouldn't call this directly. Instead, call handle_event() or process_events().

AUTHOR ^

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

COPYRIGHT ^

Copyright (C) 2004-2006, The Perl Foundation.


 parrot