lib/pods/SDL/Event.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SDL::Event - a SDL perl extension
   6
   7 =head1 SYNOPSIS
   8
   9  use SDL::Event;
  10  my $event = new SDL::Event;             # create a new event
  11  $event->pump();                         # pump all events from SDL Event Queue
  12  $event->poll();                         # Get the top one from the queue
  13  while ($event->wait()) {
  14         my $type = $event->type();      # get event type
  15         # ... handle event
  16         exit if $type == SDL_QUIT;
  17  }
  18
  19 =head1 DESCRIPTION
  20
  21 C<SDL::Event> offers an object-oriented approach to SDL events. By creating
  22 an instance of SDL::Event via new() you can wait for events, and then determine
  23 the type of the event and take an appropriate action.
  24
  25 =head1 EXAMPLE
  26
  27 Here is an example of a simple event handler loop routine.
  28 See also L<SDL::App::loop>.
  29
  30        sub loop {
  31                my ($self,$href) = @_;
  32                my $event = new SDL::Event;
  33                while ( $event->wait() ) {
  34                        # ... insert here your event handling like:
  35                        if ( ref($$href{$event->type()}) eq "CODE" ) {
  36                                &{$$href{$event->type()}}($event);
  37                                $self->sync();
  38                        }
  39                }
  40        }
  41
  42 =head1 METHODS
  43
  44 =head2 new()
  45
  46 Create a new event object.It returns a SDL::Event.
  47
  48 =head2 type(event)
  49
  50 Returns the type of the SDL::Event given as first parameter, see list of exported symbols for which are
  51 available.
  52
  53 =head2 pump()
  54
  55 SDL::Events::pump gathers all the pending input information from devices and places
  56 it on the event queue.
  57 Without calls to pump no events would ever be placed on the queue.
  58 Often the need for calls to pump is hidden from the user
  59 since C</SDL::Events::poll> and C<SDL::Events::wait_event implicitly call pump.
  60 However, if you are not polling or waiting for events (e.g. you are filtering them),
  61 then you must call pump force an event queue update.
  62 pump doesn't return any value and doesn't take any parameters.
  63
  64 Note: You can only call this function in the thread that set the video mode.
  65
  66
  67 =head2 poll(event)
  68
  69 Polls for currently pending events.
  70 If event is not undef, the next event is removed from the queue and returned as a C< SDL::Event>.
  71 As this function implicitly calls C<SDL::Events::pump>, you can only call this function in the thread that set the video mode.
  72 it take a SDL::Event as first parameter.
  73
  74 =head2 wait(event)
  75
  76 Waits indefinitely for the next available event, returning undef if there was an error while waiting for events,
  77 a L< SDL::Event> otherwise.
  78 If event is not NULL, the next event is removed.
  79 As this function implicitly calls L<SDL::Events::pump>, you can only call this function in the thread that set the video mode.
  80 WaitEvent take a SDL::Event as first parameter.
  81
  82 =head2 set( type, state )
  83
  84 Set the state for all events of the given event's type
  85
  86 =head2 set_unicode( toggle )
  87
  88 Toggle unicode on the event.
  89
  90 =head2 set_key_repeat( delay, interval)
  91
  92 Sets the delay and intervall of the key repeat rate (e.g. when a user
  93 holds down a key on the keyboard).
  94
  95 =head2 active_gain(event)
  96
  97 active_gain return the active gain from the SDL::Event given as first parameter.
  98
  99 =head2 active_state(event)
 100
 101 active_state return the active state from the SDL::Event given as first parameter.
 102
 103 =head2 key_state(event)
 104
 105 key_state return the active key state from the SDL::Event given as first parameter.
 106
 107
 108 =head2 key_sym(key)
 109
 110 key_sym return the key pressed/released  information from the SDL::Event given as first parameter.
 111
 112 =head2 get_key_name(key)
 113
 114 get_key_name get the name of an SDL virtual keysym.
 115 it returns the key name.
 116
 117 =head2 key_mod(event)
 118
 119 key_mod return the mod keys pressed information from the SDL::Event given as first parameter.
 120
 121 =head2 key_unicode(event)
 122
 123 key_unicode return the unicode translated keys pressed/released information from the SDL::Event given as first parameter.
 124
 125 =head2 key_scancode(event) * to move in SDL::Game::Keyboard
 126
 127 key_scancode return the hardware specific keyboard scan code from the SDL::Event given as first parameter.
 128
 129 =head2 motion_state(event) * to move in SDL::Game::Mouse
 130
 131 motion_state return the state of the mouse button from the SDL::Event given as first parameter.
 132
 133 =head2 motion_x(event) * to move in SDL::Game::Mouse
 134
 135 Returns the motion of the mouse in X direction as an absolute value.
 136 It take a SDL::Event as first parameter.
 137
 138 =head2 motion_y(event) * to move in SDL::Game::Mouse
 139
 140 Returns the motion of the mouse in Y direction as an absolute value.
 141 It take a SDL::Event as first parameter.
 142
 143 =head2 motion_xrel(event) * to move in SDL::Game::Mouse
 144
 145 Returns the motion of the mouse in X direction as a relative value.
 146 It take a SDL::Event as first parameter.
 147
 148 =head2 motion_yrel(event) * to move in SDL::Game::Mouse
 149
 150 Returns the motion of the mouse in Y direction as a relative value.
 151 It take a SDL::Event as first parameter.
 152
 153 =head2 button_state(event) * to move in SDL::Game::Mouse
 154
 155 Returns the state of the mouse buttons.
 156 It take a SDL::Event as first parameter.
 157
 158 =head2 button_x(event) * to move in SDL::Game::Mouse
 159
 160 Return the X position of the mouse at keypress.it take a SDL::Event as first parameter.
 161
 162 =head2 button_y(event) * to move in SDL::Game::Mouse
 163
 164 Return the Y position of the mouse at keypress.it take a SDL::Event as first parameter.
 165
 166 =head2 button(event) * to move in SDL::Game::Mouse
 167
 168 Return the mouse button index (SDL_BUTTON_LEFT, SDL_BUTTON_MIDDLE, SDL_BUTTON_RIGHT, SDL_BUTTON_WHEELUP, SDL_BUTTON_WHEELDOWN)
 169
 170 =head1 AUTHOR
 171
 172 David J. Goehrig
 173 Documentation by Tels <http://bloodgate.com/>
 174
 175 =head1 SEE ALSO
 176
 177 L<perl> L<SDL::App>
 178
 179 =cut