lib/SDL/Event.pm

   1 #!/usr/bin/env perl
   2 #
   3 # Event.pm
   4 #
   5 # Copyright (C) 2005 David J. Goehrig <dgoehrig@cpan.org>
   6 #
   7 # ------------------------------------------------------------------------------
   8 #
   9 # This library is free software; you can redistribute it and/or
  10 # modify it under the terms of the GNU Lesser General Public
  11 # License as published by the Free Software Foundation; either
  12 # version 2.1 of the License, or (at your option) any later version.
  13 #
  14 # This library is distributed in the hope that it will be useful,
  15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 # Lesser General Public License for more details.
  18 #
  19 # You should have received a copy of the GNU Lesser General Public
  20 # License along with this library; if not, write to the Free Software
  21 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  22 #
  23 # ------------------------------------------------------------------------------
  24 #
  25 # Please feel free to send questions, suggestions or improvements to:
  26 #
  27 #       David J. Goehrig
  28 #       dgoehrig@cpan.org
  29 #
  30
  31 package SDL::Event;
  32
  33 use strict;
  34 use warnings;
  35 use Carp;
  36
  37 use SDL;
  38
  39 sub new {
  40         my $proto = shift;
  41         my $class = ref($proto) || $proto;
  42         my $self;
  43         $self = \SDL::NewEvent();
  44         bless $self, $class;
  45         return $self;
  46 }
  47
  48 sub DESTROY {
  49         my $self = shift;
  50         SDL::FreeEvent($$self);
  51 }
  52
  53 sub type {
  54         my $self = shift;
  55         if (@_) {
  56                 SDL::SetEventType($$self,$_[0]);
  57         }
  58         return SDL::EventType($$self);
  59 }
  60
  61 sub pump {
  62         SDL::PumpEvents();
  63 }
  64
  65 sub poll {
  66         my $self = shift;
  67         return SDL::PollEvent($$self);
  68 }
  69
  70 sub push {
  71         my $self = shift;
  72         return SDL::PushEvent($$self);
  73 }
  74
  75 sub wait {
  76         my $self = shift;
  77         return SDL::WaitEvent($$self);
  78 }
  79
  80 sub set {
  81         my $self = shift;
  82         my $state = shift;
  83         return SDL::EventState($self->type(),$state);
  84 }
  85
  86 sub set_unicode {
  87         my $self = shift;
  88         my $toggle = shift;
  89         return SDL::EnableUnicode($toggle);
  90 }
  91
  92 sub set_key_repeat {
  93         my $self = shift;
  94         my $delay = shift;
  95         my $interval = shift;
  96         return SDL::EnableKeyRepeat($delay,$interval);
  97 }
  98
  99 sub active_gain {
 100         my $self = shift;
 101         return SDL::ActiveEventGain($$self);
 102 }
 103
 104 sub active_state {
 105         my $self = shift;
 106         return SDL::ActiveEventState($$self);
 107 }
 108
 109 sub key_state {
 110         my $self = shift;
 111         return SDL::KeyEventState($$self);
 112 }
 113
 114 sub key_sym {
 115         my $self = shift;
 116         return SDL::KeyEventSym($$self);
 117 }
 118
 119 sub key_name {
 120         my $self = shift;
 121         return SDL::GetKeyName(SDL::KeyEventSym($$self));
 122 }
 123
 124 sub key_mod {
 125         my $self = shift;
 126         return SDL::KeyEventMod($$self);
 127 }
 128
 129 sub key_unicode {
 130         my $self = shift;
 131         return SDL::KeyEventUnicode($$self);
 132 }
 133
 134 sub key_scancode {
 135         my $self = shift;
 136         return SDL::KeyEventScanCode($$self);
 137 }
 138
 139 sub motion_state {
 140         my $self = shift;
 141         return SDL::MouseMotionState($$self);
 142 }
 143
 144 sub motion_x {
 145         my $self = shift;
 146         return SDL::MouseMotionX($$self);
 147 }
 148
 149 sub motion_y {
 150         my $self = shift;
 151         return SDL::MouseMotionY($$self);
 152 }
 153
 154 sub motion_xrel {
 155         my $self = shift;
 156         return SDL::MouseMotionXrel($$self);
 157 }
 158
 159 sub motion_yrel {
 160         my $self = shift;
 161         return SDL::MouseMotionYrel($$self);
 162 }
 163
 164 sub button_state {
 165         my $self = shift;
 166         return SDL::MouseButtonState($$self);
 167 }
 168
 169 sub button_x {
 170         my $self = shift;
 171         return SDL::MouseButtonX($$self);
 172 }
 173
 174 sub button_y {
 175         my $self = shift;
 176         return SDL::MouseButtonY($$self);
 177 }
 178
 179 sub button {
 180         my $self = shift;
 181         return SDL::MouseButton($$self);
 182 }
 183
 184 sub resize_w {
 185         my $self = shift;
 186         SDL::ResizeEventW($$self);
 187 }
 188
 189 sub resize_h {
 190         my $self = shift;
 191         SDL::ResizeEventH($$self);
 192 }
 193
 194 1;
 195
 196 __END__;
 197
 198 =pod
 199
 200 =head1 NAME
 201
 202 SDL::Event - a SDL perl extension
 203
 204 =head1 SYNOPSIS
 205
 206  use SDL::Event;
 207  my $event = new SDL::Event;             # create a new event
 208  $event->pump();                         # pump all events from SDL Event Queue
 209  $event->poll();                         # Get the top one from the queue
 210  while ($event->wait()) {
 211         my $type = $event->type();      # get event type
 212         # ... handle event
 213         exit if $type == SDL_QUIT;
 214  }
 215
 216 =head1 DESCRIPTION
 217
 218 C<SDL::Event> offers an object-oriented approach to SDL events. By creating
 219 an instance of SDL::Event via new() you can wait for events, and then determine
 220 the type of the event and take an appropriate action.
 221
 222 =head1 EXAMPLE
 223
 224 Here is an example of a simple event handler loop routine.
 225 See also L<SDL::App::loop>.
 226
 227        sub loop {
 228                my ($self,$href) = @_;
 229                my $event = new SDL::Event;
 230                while ( $event->wait() ) {
 231                        # ... insert here your event handling like:
 232                        if ( ref($$href{$event->type()}) eq "CODE" ) {
 233                                &{$$href{$event->type()}}($event);
 234                                $self->sync();
 235                        }
 236                }
 237        }
 238
 239 =head1 METHODS
 240
 241 =head2 new()
 242
 243 Create a new event object.It returns a SDL::Event.
 244
 245 =head2 type()
 246
 247 Returns the type of the event, see list of exported symbols for which are
 248 available.
 249
 250 =head2 pump()
 251
 252 SDL::Events::pump gathers all the pending input information from devices and places
 253 it on the event queue.
 254 Without calls to pump no events would ever be placed on the queue.
 255 Often the need for calls to pump is hidden from the user
 256 since C</SDL::Events::poll> and C<SDL::Events::wait_event implicitly call pump.
 257 However, if you are not polling or waiting for events (e.g. you are filtering them),
 258 then you must call pump force an event queue update.
 259 pump doesn't return any value and doesn't take any parameters.
 260
 261 Note: You can only call this function in the thread that set the video mode.
 262
 263
 264 =head2 poll(event)
 265
 266 Polls for currently pending events.
 267 If event is not undef, the next event is removed from the queue and returned as a C< SDL::Event>.
 268 As this function implicitly calls C<SDL::Events::pump>, you can only call this function in the thread that set the video mode.
 269 it take a SDL::Event as first parameter.
 270
 271 =head2 wait(event)
 272
 273 Waits indefinitely for the next available event, returning undef if there was an error while waiting for events,
 274 a L< SDL::Event> otherwise.
 275 If event is not NULL, the next event is removed.
 276 As this function implicitly calls L<SDL::Events::pump>, you can only call this function in the thread that set the video mode.
 277 WaitEvent take a SDL::Event as first parameter.
 278
 279 =head2 set( type, state )
 280
 281 Set the state for all events of the given event's type
 282
 283 =head2 set_unicode( toggle )
 284
 285 Toggle unicode on the event.
 286
 287 =head2 set_key_repeat( delay, interval)
 288
 289 Sets the delay and intervall of the key repeat rate (e.g. when a user
 290 holds down a key on the keyboard).
 291
 292 =head2 active_gain(event)
 293
 294 active_gain return the active gain from the SDL::Event given as first parameter.
 295
 296 =head2 active_state(event)
 297
 298 active_state return the active state from the SDL::Event given as first parameter.
 299
 300 =head2 key_state(event)
 301
 302 key_state return the active key state from the SDL::Event given as first parameter.
 303
 304
 305 =head2 key_sym(key)
 306
 307 key_sym return the key pressed/released  information from the SDL::Event given as first parameter.
 308
 309 =head2 get_key_name(key)
 310
 311 get_key_name get the name of an SDL virtual keysym.
 312 it returns the key name.
 313
 314 =head2 key_mod(event)
 315
 316 key_mod return the mod keys pressed information from the SDL::Event given as first parameter.
 317
 318 =head2 key_unicode(event)
 319
 320 key_unicode return the unicode translated keys pressed/released information from the SDL::Event given as first parameter.
 321
 322 =head2 key_scancode(event) * to move in SDL::Game::Keyboard
 323
 324 key_scancode return the hardware specific keyboard scan code from the SDL::Event given as first parameter.
 325
 326 =head2 motion_state(event) * to move in SDL::Game::Mouse
 327
 328 motion_state return the state of the mouse button from the SDL::Event given as first parameter.
 329
 330 =head2 motion_x(event) * to move in SDL::Game::Mouse
 331
 332 Returns the motion of the mouse in X direction as an absolute value.
 333 It take a SDL::Event as first parameter.
 334
 335 =head2 motion_y(event) * to move in SDL::Game::Mouse
 336
 337 Returns the motion of the mouse in Y direction as an absolute value.
 338 It take a SDL::Event as first parameter.
 339
 340 =head2 motion_xrel(event) * to move in SDL::Game::Mouse
 341
 342 Returns the motion of the mouse in X direction as a relative value.
 343 It take a SDL::Event as first parameter.
 344
 345 =head2 motion_yrel(event) * to move in SDL::Game::Mouse
 346
 347 Returns the motion of the mouse in Y direction as a relative value.
 348 It take a SDL::Event as first parameter.
 349
 350 =head2 button_state(event) * to move in SDL::Game::Mouse
 351
 352 Returns the state of the mouse buttons.
 353 It take a SDL::Event as first parameter.
 354
 355 =head2 button_x(event) * to move in SDL::Game::Mouse
 356
 357 Return the X position of the mouse at keypress.it take a SDL::Event as first parameter.
 358
 359 =head2 button_y(event) * to move in SDL::Game::Mouse
 360
 361 Return the Y position of the mouse at keypress.it take a SDL::Event as first parameter.
 362
 363 =head2 button(event) * to move in SDL::Game::Mouse
 364
 365 Return the mouse button index (SDL_BUTTON_LEFT, SDL_BUTTON_MIDDLE, SDL_BUTTON_RIGHT, SDL_BUTTON_WHEELUP, SDL_BUTTON_WHEELDOWN)
 366
 367 =head1 AUTHOR
 368
 369 David J. Goehrig
 370 Documentation by Tels <http://bloodgate.com/>
 371
 372 =head1 SEE ALSO
 373
 374 L<perl> L<SDL::App>
 375
 376 =cut