From: Tobias Leich Date: Tue, 10 Nov 2009 23:24:34 +0000 (+0100) Subject: basics for the event structure X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ac4125ab6828cae333bbca64a474d303a19d309a;p=sdlgit%2FSDL_perl.git basics for the event structure --- diff --git a/lib/pods/SDL/Event.pod b/lib/pods/SDL/Event.pod index 6d5e35f..a670aea 100644 --- a/lib/pods/SDL/Event.pod +++ b/lib/pods/SDL/Event.pod @@ -2,178 +2,287 @@ =head1 NAME -SDL::Event - a SDL perl extension +SDL::Event - General event structure =head1 SYNOPSIS - use SDL::Event; - my $event = new SDL::Event; # create a new event - $event->pump(); # pump all events from SDL Event Queue - $event->poll(); # Get the top one from the queue - while ($event->wait()) { - my $type = $event->type(); # get event type - # ... handle event - exit if $type == SDL_QUIT; + use SDL::Event; # for the event object itself + use SDL::Events qw(pump_events poll_event); # functions for event queue handling + + SDL::init(SDL_INIT_VIDEO); + my $event = SDL::Event->new(); + + while(1) + { + pump_events(); + + if(poll_event($event)) + { + if($event->type == SDL_MOUSEBUTTONDOWN) + { + # now you can handle the details + $event->button_which; + $event->button_button; + $event->button_x; + $event->button_y; + } + + last if $event->type == SDL_QUIT; + } + + # your screen drawing code will be here } =head1 DESCRIPTION -C offers an object-oriented approach to SDL events. By creating -an instance of SDL::Event via new() you can wait for events, and then determine -the type of the event and take an appropriate action. +Event handling allows your application to receive input from the user. +Event handling is initalised (along with video) with a call to: + +C -=head1 EXAMPLE +Internally, SDL stores all the events waiting to be handled in an event queue. +Using functions like C, C +and C you can observe and handle waiting input events. -Here is an example of a simple event handler loop routine. -See also L. +The key to event handling in SDL is the C union. +The event queue itself is composed of a series of C unions, one for each waiting event. +C unions are read from the queue with the C function +and it is then up to the application to process the information stored with them. - sub loop { - my ($self,$href) = @_; - my $event = new SDL::Event; - while ( $event->wait() ) { - # ... insert here your event handling like: - if ( ref($$href{$event->type()}) eq "CODE" ) { - &{$$href{$event->type()}}($event); - $self->sync(); - } - } - } +=head1 METHODS -=head1 METHODS +=head2 new -=head2 new() +C creates an empty event-object, which can be used store information. +Either by calling C that transferes one event from the queue into our object +or by setting all the needed data manually in order to push the event to the queue. -Create a new event object.It returns a SDL::Event. + use SDL::Event; + + my $event = SDL::Event->new(); + +=head2 type -=head2 type(event) +SDL::Event is a union of all event structures used in SDL, using it is a simple matter of knowing +which union member relates to which event C. -Returns the type of the SDL::Event given as first parameter, see list of exported symbols for which are -available. + print 'heureka' if $event->type = SDL_MOUSEBUTTONDOWN; -=head2 pump() +Available type constants: -SDL::Events::pump gathers all the pending input information from devices and places -it on the event queue. -Without calls to pump no events would ever be placed on the queue. -Often the need for calls to pump is hidden from the user -since C and C - Application visibility event structure -=head2 poll(event) +=item * -Polls for currently pending events. -If event is not undef, the next event is removed from the queue and returned as a C< SDL::Event>. -As this function implicitly calls C, you can only call this function in the thread that set the video mode. -it take a SDL::Event as first parameter. +L - Keyboard event structure -=head2 wait(event) +=item * -Waits indefinitely for the next available event, returning undef if there was an error while waiting for events, -a L< SDL::Event> otherwise. -If event is not NULL, the next event is removed. -As this function implicitly calls L, you can only call this function in the thread that set the video mode. -WaitEvent take a SDL::Event as first parameter. +L - Keyboard event structure -=head2 set( type, state ) +=item * -Set the state for all events of the given event's type +L - Mouse motion event structure -=head2 set_unicode( toggle ) +=item * -Toggle unicode on the event. +L - Mouse button event structure -=head2 set_key_repeat( delay, interval) +=item * -Sets the delay and intervall of the key repeat rate (e.g. when a user -holds down a key on the keyboard). +L - Mouse button event structure -=head2 active_gain(event) +=item * -active_gain return the active gain from the SDL::Event given as first parameter. +L - Joystick axis motion event structure -=head2 active_state(event) +=item * -active_state return the active state from the SDL::Event given as first parameter. +L - Joystick trackball motion event structure -=head2 key_state(event) +=item * -key_state return the active key state from the SDL::Event given as first parameter. +L - Joystick hat position change event structure +=item * -=head2 key_sym(key) +L - Joystick button event structure -key_sym return the key pressed/released information from the SDL::Event given as first parameter. +=item * -=head2 get_key_name(key) +L - Joystick button event structure -get_key_name get the name of an SDL virtual keysym. -it returns the key name. +=item * -=head2 key_mod(event) +L - Window resize event structure -key_mod return the mod keys pressed information from the SDL::Event given as first parameter. +=item * -=head2 key_unicode(event) +L - Window expose event -key_unicode return the unicode translated keys pressed/released information from the SDL::Event given as first parameter. +=item * -=head2 key_scancode(event) * to move in SDL::Game::Keyboard +L - Quit requested event -key_scancode return the hardware specific keyboard scan code from the SDL::Event given as first parameter. +=item * -=head2 motion_state(event) * to move in SDL::Game::Mouse +L - A user-defined event type -motion_state return the state of the mouse button from the SDL::Event given as first parameter. +=item * -=head2 motion_x(event) * to move in SDL::Game::Mouse +L - Platform-dependent window manager event. -Returns the motion of the mouse in X direction as an absolute value. -It take a SDL::Event as first parameter. +=back -=head2 motion_y(event) * to move in SDL::Game::Mouse +TODO: SDL_EVENTMASK() -Returns the motion of the mouse in Y direction as an absolute value. -It take a SDL::Event as first parameter. +=head2 active -=head2 motion_xrel(event) * to move in SDL::Game::Mouse +C is a member of the C union and is used when an event of type C is reported. -Returns the motion of the mouse in X direction as a relative value. -It take a SDL::Event as first parameter. +When the mouse leaves or enters the window area a C type activation event occurs, +if the mouse entered the window then B will be 1, otherwise B will be 0. -=head2 motion_yrel(event) * to move in SDL::Game::Mouse +A C type activation event occurs when the application loses or gains keyboard focus. +This usually occurs when another application is made active. -Returns the motion of the mouse in Y direction as a relative value. -It take a SDL::Event as first parameter. +Finally, a C type event occurs when the application is either minimised/iconified (B=0) or restored. -=head2 button_state(event) * to move in SDL::Game::Mouse +A single event can have multiple values set in B. -Returns the state of the mouse buttons. -It take a SDL::Event as first parameter. +B This event does not occur when an application window is first created. -=head2 button_x(event) * to move in SDL::Game::Mouse +A new ActiveEvent (to fake focus loss) will be created like this: -Return the X position of the mouse at keypress.it take a SDL::Event as first parameter. + my $event = SDL::Event->new(); + $event->type(SDL_ACTIVEEVENT); + $event->active_gain(0); + $event->active_state(SDL_APPMOUSEFOCUS); -=head2 button_y(event) * to move in SDL::Game::Mouse + # I think this is wrong, ->active_type() should get SDL_APPMOUSEFOCUS, but what state gets? -Return the Y position of the mouse at keypress.it take a SDL::Event as first parameter. +=head3 active_type -=head2 button(event) * to move in SDL::Game::Mouse +=head3 active_gain -Return the mouse button index (SDL_BUTTON_LEFT, SDL_BUTTON_MIDDLE, SDL_BUTTON_RIGHT, SDL_BUTTON_WHEELUP, SDL_BUTTON_WHEELDOWN) +=head3 active_state -=head1 AUTHOR +=head2 key + +=head3 key_type + +=head3 key_state + +=head3 key_keysym + +=head3 key_scancode + +=head3 key_sym + +=head3 key_mod + +=head3 key_unicode + +=head2 motion + +=head3 motion_type + +=head3 motion_state + +=head3 motion_x, motion_y + +=head3 motion_xrel, motion_yrel + +=head2 button + +=head3 button_type + +=head3 button_which + +=head3 button_button + +=head3 button_state + +=head3 button_x, button_y + +=head2 jaxis + +=head3 jaxis_type + +=head3 jaxis_which + +=head3 jaxis_axis + +=head3 jaxis_value -David J. Goehrig -Documentation by Tels +=head2 jbutton + +=head3 jbutton_type + +=head3 jbutton_which + +=head3 jbutton_button + +=head3 jbutton_state + +=head2 jhat + +=head3 jhat_type + +=head3 jhat_which + +=head3 jhat_hat + +=head3 jhat_value + +=head2 jball + +=head3 jball_type + +=head3 jball_which + +=head3 jball_ball + +=head3 jball_xrel, jball_yrel + +=head2 resize + +=head3 resize_type + +=head3 resize_x, resize_y + +=head2 expose + +=head3 expose_type + +=head2 syswm + +=head3 syswm_type + +=head3 syswm_msg + +=head2 user + +=head3 user_type + +=head3 user_code + +=head3 user_data1, user_data2 + +=head2 quit + +=head3 quit_type + +Create a new SDL::Event object. + +=head1 AUTHOR =head1 SEE ALSO -L L +L =cut