pages/SDL-Events.html-inc

   1 <div class="pod">
   2 <!-- INDEX START -->
   3 <h3 id="TOP">Index</h3>
   4
   5 <ul><li><a href="#NAME">NAME</a>
   6 <ul><li><a href="#CATEGORY">CATEGORY</a></li>
   7 </ul>
   8 </li>
   9 <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
  10 <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
  11 <li><a href="#METHODS">METHODS</a>
  12 <ul><li><a href="#pump_events">pump_events</a></li>
  13 <li><a href="#peep_events_event_num_events_action_">peep_events (event, num_events, action, mask) </a>
  14 <ul><li><a href="#RETURN">RETURN</a></li>
  15 </ul>
  16 </li>
  17 <li><a href="#poll_event_event">poll_event($event)</a>
  18 <ul><li><a href="#RETURN-2">RETURN</a></li>
  19 </ul>
  20 </li>
  21 <li><a href="#push_event_event">push_event($event)</a>
  22 <ul><li><a href="#RETURN-3">RETURN</a></li>
  23 </ul>
  24 </li>
  25 <li><a href="#wait_event_event">wait_event($event)</a>
  26 <ul><li><a href="#RETURN-4">RETURN</a></li>
  27 </ul>
  28 </li>
  29 <li><a href="#set_event_filter">set_event_filter</a>
  30 <ul><li><a href="#PARAMETER">PARAMETER</a></li>
  31 </ul>
  32 </li>
  33 <li><a href="#get_key_state">get_key_state</a></li>
  34 <li><a href="#get_mod_state">get_mod_state</a>
  35 <ul><li><a href="#MOD_VALUES">MOD VALUES</a></li>
  36 </ul>
  37 </li>
  38 <li><a href="#set_mod_state">set_mod_state</a></li>
  39 <li><a href="#event_state">event_state </a>
  40 <ul><li><a href="#STATES">STATES</a></li>
  41 </ul>
  42 </li>
  43 <li><a href="#get_key_name">get_key_name</a></li>
  44 <li><a href="#enable_unicode">enable_unicode </a></li>
  45 <li><a href="#enable_key_repeat">enable_key_repeat </a></li>
  46 <li><a href="#get_mouse_state">get_mouse_state </a></li>
  47 <li><a href="#get_relative_mouse_state">get_relative_mouse_state </a></li>
  48 <li><a href="#get_app_state">get_app_state </a></li>
  49 <li><a href="#joystick_event_state">joystick_event_state </a></li>
  50 </ul>
  51 </li>
  52 <li><a href="#SEE_ALSO">SEE ALSO</a>
  53 </li>
  54 </ul><hr />
  55 <!-- INDEX END -->
  56
  57 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
  58 <div id="NAME_CONTENT">
  59 <p>SDL::Events - Bindings to the Events Category in SDL API</p>
  60
  61 </div>
  62 <h2 id="CATEGORY">CATEGORY</h2>
  63 <div id="CATEGORY_CONTENT">
  64 <p>Core, Events</p>
  65
  66 </div>
  67 <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
  68 <div id="SYNOPSIS_CONTENT">
  69 <p>Most likely you just want to know how to get events for you app.</p>
  70 <pre>  use SDL;
  71   use SDL::Event;
  72   use SDL::Events;
  73
  74   SDL::init(SDL_INIT_VIDEO); # Event can only be grabbed in the same thread as this
  75
  76   ...
  77
  78   my $event = SDL::Event-&gt;new(); # notices 'Event' ne 'Events'
  79
  80   while( 1 )
  81         {
  82           SDL::Events::pump_events();
  83          while(  SDL::Events::poll_event($event) )
  84          {
  85                 #check by event type
  86                 on_active() if $event-&gt;type == SDL_ACTIVEEVENT;
  87                 ...
  88          }
  89         }
  90
  91 </pre>
  92
  93 </div>
  94 <h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
  95 <div id="DESCRIPTION_CONTENT">
  96
  97
  98
  99
 100
 101 </div>
 102 <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
 103 <div id="METHODS_CONTENT">
 104
 105 </div>
 106 <h2 id="pump_events">pump_events</h2>
 107 <div id="pump_events_CONTENT">
 108 <p>Pumps the event loop, gathering events from the input devices.</p>
 109 <pre>   pump_events();
 110
 111 </pre>
 112 <p>pump_events gathers all the pending input information from devices and places it on the event queue. Without calls to pump_events no events would ever be placed on the queue.
 113 Often the need for calls to pump_events is hidden from the user since <a href="http://search.cpan.org/perldoc?poll_event">poll_event</a> and <a href="http://search.cpan.org/perldoc?wait_event">wait_event</a> implicitly call pump_events.
 114 However, if you are not polling or waiting for events (e.g. you are filtering them), then you must call pump_events to force an event queue update.</p>
 115
 116
 117
 118
 119
 120 </div>
 121 <h2 id="peep_events_event_num_events_action_">peep_events (event, num_events, action, mask) </h2>
 122 <div id="peep_events_event_num_events_action_-2">
 123 <p>Checks the event queue for messages and optionally returns them.  </p>
 124 <pre>   my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS);
 125
 126 </pre>
 127 <p>If action is SDL_ADDEVENT, up to numevents events will be added to the back of the event queue.</p>
 128 <p>If action is SDL_PEEKEVENT, up to numevents events at the front of the event queue, matching mask, will be returned and will not be removed from the queue.</p>
 129 <p>If action is SDL_GETEVENT, up to numevents events at the front of the event queue, matching mask, will be returned and will be removed from the queue.</p>
 130 <p>The mask parameter is a bitwise OR of SDL::Events::SDL_EVENTMASK(event_type), for all event types you are interested in</p>
 131 <p>This function is thread-safe.</p>
 132 <p>You may have to call pump_events before calling this function. Otherwise, the events may not be ready to be filtered when you call peep_events.</p>
 133 <p>Examples of mask:</p>
 134 <dl>
 135         <dt>SDL_EVENTMASK (SDL_KEYUP)</dt>
 136         <dt>(SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK (SDL_MOUSEBUTTONUP))</dt>
 137         <dt>SDL_ALLEVENTS</dt>
 138         <dt>SDL_KEYUPMASK</dt>
 139         <dt>SDL_ALLEVENTS ^ SDL_QUITMASK</dt>
 140 </dl>
 141
 142 </div>
 143 <h3 id="RETURN">RETURN</h3>
 144 <div id="RETURN_CONTENT">
 145 <p>Number of Events actually stored or -1 if there was an error</p>
 146
 147 </div>
 148 <h2 id="poll_event_event">poll_event($event)</h2>
 149 <div id="poll_event_event_CONTENT">
 150 <p>Polls for currently pending events. </p>
 151 <p>If $event is not NULL, the next event is removed from the queue and stored in the <a href="SDL-Event.html">SDL::Event</a> structure pointed to by $event.</p>
 152 <p>As this function implicitly calls pump_events, you can only call this function in the thread that set the video mode with <a href="/SDL-Video.html#set_video_mode">SDL::Video::set_video_mode</a>. </p>
 153
 154 </div>
 155 <h3 id="RETURN-2">RETURN</h3>
 156 <div id="RETURN_CONTENT-2">
 157 <p>Returns 1 if there are any pending events, or 0 if there are none available. </p>
 158
 159 </div>
 160 <h2 id="push_event_event">push_event($event)</h2>
 161 <div id="push_event_event_CONTENT">
 162 <p>Pushes an event onto the event queue </p>
 163 <p>The event queue can actually be used as a two way communication channel. Not only can events be read from the queue, but the user can also push their own events onto it. event is a pointer to the event structure you wish to push onto the queue.
 164 The event is copied into the queue, and the caller may dispose of the memory pointed to after push_event returns.</p>
 165 <p>Note: Pushing device input events onto the queue doesn't modify the state of the device within SDL. </p>
 166 <p>This function is thread safe, and can be called from other threads safely.</p>
 167
 168 </div>
 169 <h3 id="RETURN-3">RETURN</h3>
 170 <div id="RETURN_CONTENT-3">
 171 <p>Returns 0 on success or -1 if the event couldn't be pushed.</p>
 172
 173 </div>
 174 <h2 id="wait_event_event">wait_event($event)</h2>
 175 <div id="wait_event_event_CONTENT">
 176 <p>Waits indefinitely for the next available $event, returning 0 if there was an error while waiting for events, 1 otherwise.</p>
 177 <p>If $event is not NULL, the next event is removed from the queue and stored in $event.</p>
 178 <p>As this function implicitly calls SDL_PumpEvents, you can only call this function in the thread that  <a href="/SDL-Video.html#set_video_mode">SDL::Video::set_video_mode</a>.  </p>
 179
 180 </div>
 181 <h3 id="RETURN-4">RETURN</h3>
 182 <div id="RETURN_CONTENT-4">
 183 <p>0 if there was an error while waiting for events, 1 otherwise</p>
 184
 185 </div>
 186 <h2 id="set_event_filter">set_event_filter</h2>
 187 <div id="set_event_filter_CONTENT">
 188 <p>Sets up a filter to process all events </p>
 189 <pre>   my $filter = sub { if($_[0]-&gt;type == SDL_ACTIVEEVENT){ return 0} else{ return 1; }};
 190
 191         SDL::Events::set_event_filter($filter);
 192
 193 </pre>
 194
 195 </div>
 196 <h3 id="PARAMETER">PARAMETER</h3>
 197 <div id="PARAMETER_CONTENT">
 198 <p>set_event_filter takes a coderef that it checks all events again. The callback gets a event in the stack</p>
 199 <pre>   sub { my $event_to_test = shift; ...}
 200
 201 </pre>
 202 <p>to filter the event return a 0, to pass the filter return a 1. </p>
 203 <p>One <strong>Caveat</strong> is if you are filterign SDL_QUITEVENT the event will be filtered if it is non-intterupt call ( Window closes normally ). If it is a interrupt SDL_QUITEVENT it will be process on the next event poll. </p>
 204 <p>Events pushed onto to the queue with <a href="/SDL-Events.html#push_events">SDL::Events::push_events</a> or <a href="/SDL-Events.html#peep_events">SDL::Events::peep_events</a> do not get filtered.</p>
 205 <p>This callback may run in a different thread. </p>
 206
 207 </div>
 208 <h2 id="get_key_state">get_key_state</h2>
 209 <div id="get_key_state_CONTENT">
 210 <p>Get a snapshot of the current keyboard state</p>
 211 <pre>   my $keys_ref = SDL::Events::get_key_state();
 212
 213         print $keys_ref-&gt;[SDLK_RETURN]; # 1 if pressed , 0 if not pressed
 214
 215 </pre>
 216 <p>Use <a href="/SDL-Events.html#pump_events">SDL::Events::pump_events</a> to update the state array.</p>
 217 <p>This function gives you the current state after all events have been processed, so if a key or button has been pressed and released before you process events, then the pressed state will never show up in the get_key_state call.</p>
 218 <p>This function doesn't take into account whether shift has been pressed or not.</p>
 219
 220 </div>
 221 <h2 id="get_mod_state">get_mod_state</h2>
 222 <div id="get_mod_state_CONTENT">
 223 <p>Get the state of the modifier keys</p>
 224 <p>Returns the current state of modifier keys</p>
 225 <p>Return value is an OR'd combination of  KMOD_*</p>
 226 <pre> SDL::Events::pump_events; #get latest mod_state in buffers
 227
 228  my $mod_state = SDL::Events::get_mod_state();
 229
 230  # Check which ones are pressed with
 231
 232  # no mod pressed?
 233
 234  print 'no_mod' if  ( $mod_state &amp; KMOD_NONE );
 235
 236  # CTRL or ALT
 237
 238  print 'ctrl alt' if ($mod_state &amp; KMOD_CTRL || $mod_state &amp; KMOD_ALT );
 239
 240 </pre>
 241
 242 </div>
 243 <h3 id="MOD_VALUES">MOD VALUES</h3>
 244 <div id="MOD_VALUES_CONTENT">
 245 <dl>
 246         <dt>KMOD_NONE</dt>
 247         <dt>KMOD_LSHIFT</dt>
 248         <dt>KMOD_RSHIFT</dt>
 249         <dt>KMOD_LCTRL</dt>
 250         <dt>KMOD_RCTRL</dt>
 251         <dt>KMOD_LALT</dt>
 252         <dt>KMOD_RALT</dt>
 253         <dt>KMOD_LMETA</dt>
 254         <dt>KMOD_RMETA</dt>
 255         <dt>KMOD_NUM</dt>
 256         <dt>KMOD_CAPS</dt>
 257         <dt>KMOD_MODE</dt>
 258         <dt>KMOD_CTRL </dt>
 259         <dd>
 260                 <p>same as KMOD_LCTRL|KMOD_RCTRL</p>
 261         </dd>
 262         <dt>KMOD_SHIFT</dt>
 263         <dd>
 264                 <p>same as KMOD_LSHIFT|KMOD_RSHIFT</p>
 265         </dd>
 266         <dt>KMOD_ALT</dt>
 267         <dd>
 268                 <p>same as KMOD_LALT|KMOD_RALT</p>
 269         </dd>
 270         <dt>KMOD_META</dt>
 271         <dd>
 272                 <p>same as KMOD_LMETA|KMOD_RMETA</p>
 273         </dd>
 274 </dl>
 275
 276 </div>
 277 <h2 id="set_mod_state">set_mod_state</h2>
 278 <div id="set_mod_state_CONTENT">
 279 <p>Get the state of the modifier keys</p>
 280 <p>The inverse of <a href="/SDL-Events.html#get_mod_state">SDL::Events::get_mod_state</a> allows you to impose modifier key states on your application.</p>
 281 <p>Simply pass your desired modifier states into $modstate. This value can be a OR'd combination of any KMOD* constant.</p>
 282 <pre> my $modstate = KMOD_LMETA | KMOD_LSHIFT;
 283
 284 </pre>
 285 <p>Any KMOD_* constant see <a href="/SDL-Events.html#get_mod_state">SDL::Events::get_mod_state</a> for constants.
 286  SDL::Events::set_mod_state( $modstate );</p>
 287
 288 </div>
 289 <h2 id="event_state">event_state </h2>
 290 <div id="event_state_CONTENT">
 291 <p>Allows you to set the state of processing certain events</p>
 292 <pre> SDL::Events::event_state( $type, $state );
 293
 294 </pre>
 295 <p>A list of $type(s) can be found in <a href="SDL-Event.html">SDL::Event</a></p>
 296
 297 </div>
 298 <h3 id="STATES">STATES</h3>
 299 <div id="STATES_CONTENT">
 300 <dl>
 301         <dt>SDL_IGNORE</dt>
 302         <dd>
 303                 <p>The event of $type will be automatically dropper from the event queue and will not be filtered.</p>
 304         </dd>
 305         <dt>SDL_ENABLE</dt>
 306         <dd>
 307                 <p>The event of $type will be processed normally. This is default.</p>
 308         </dd>
 309         <dt>SDL_QUERY</dt>
 310         <dd>
 311                 <p>The current processing state of the $type will be returned</p>
 312         </dd>
 313 </dl>
 314
 315 </div>
 316 <h2 id="get_key_name">get_key_name</h2>
 317 <div id="get_key_name_CONTENT">
 318 <p>Gets the name of the a SDL virtual keysym</p>
 319 <pre> my $event = SDL::Event-&gt;new();
 320
 321  while( SDL::Events::poll_event($event) )
 322  {
 323    my $key = $event-&gt;key_sym;
 324    $key_str = SDL::Events::get_key_name($key);
 325  }
 326
 327 </pre>
 328 <p>Returns a string with the name of the key sym.</p>
 329
 330 </div>
 331 <h2 id="enable_unicode">enable_unicode </h2>
 332 <div id="enable_unicode_CONTENT">
 333 <p>Enable/Disable UNICODE translation</p>
 334 <pre>  my $previous_translation_mode = SDL::Events::enable_unicode( 1 ); #enable
 335      $previous_translation_mode = SDL::Events::enable_unicode( 0 ); #disables
 336
 337 </pre>
 338 <p>To obtain the character codes corresponding to received keyboard events, Unicode translation must first be turned on using this function. The translation incurs a slight overhead for each keyboard event and is therefore disabled by default. For each subsequently recieved key down event, the unicode member of the <a href="/SDL-Event.html#key_sym">SDL::Event::key_sym</a> provided structure will be then contain the corresponding character code, or otherwise zero.</p>
 339 <p>A value of 1 for enabling, 0 for disabling and -1 for unchanged. -1 is usefull for querying the current translation mode.</p>
 340 <p>Only key press events will be translated not release events.</p>
 341 <p>Returns the previous translation mode as (1,0).</p>
 342
 343 </div>
 344 <h2 id="enable_key_repeat">enable_key_repeat </h2>
 345 <div id="enable_key_repeat_CONTENT">
 346 <p>Sets keyboard repeat rate</p>
 347 <pre> my $success = SDL::Events::enable_key_repeat( $delay, $interval );
 348
 349 </pre>
 350 <p>Enables or disables the keyboard repeat rate. $delay specifies how long the key must be pressed before it begins repeating, it then repleats at the speed specified by $interval. Both $delay and $interval are expressed in milliseconds.</p>
 351 <p>Setting $delay to 0 disables key repeating completely. Good default values are SDL_DEFAULT_REPEAT_DELAY and SDL_DEFAULT_REPEAT_INTERVAL.</p>
 352 <p>Return 0 on success and -1 on fail.</p>
 353
 354 </div>
 355 <h2 id="get_mouse_state">get_mouse_state </h2>
 356 <div id="get_mouse_state_CONTENT">
 357 <p>Retrives the current state of the mouse</p>
 358 <pre>   my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };
 359
 360         print 'Button Left pressed' if ($mask &amp; SDL_BUTTON_LMASK);
 361
 362         print 'Button Right pressed' if ($mask &amp; SDL_BUTTON_RMASK);
 363
 364         print 'Button Middle pressed' if ($mask &amp; SDL_BUTTON_MMASK);
 365
 366         print $x.','.$y;
 367
 368 </pre>
 369 <p>The current button state is returned as a button $bitmask, which can be tested using the the above constants </p>
 370
 371 </div>
 372 <h2 id="get_relative_mouse_state">get_relative_mouse_state </h2>
 373 <div id="get_relative_mouse_state_CONTENT">
 374 <p>Retrives the current relative state of the mouse</p>
 375 <pre>   my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };
 376
 377         print 'Button Left pressed' if ($mask &amp; SDL_BUTTON_LMASK);
 378
 379         print 'Button Right pressed' if ($mask &amp; SDL_BUTTON_RMASK);
 380
 381         print 'Button Middle pressed' if ($mask &amp; SDL_BUTTON_MMASK);
 382
 383         print $x.','.$y; # this is relative to the last postion of the mouse
 384
 385 </pre>
 386 <p>The current button state is returned as a button $bitmask, which can be tested using the the above constants </p>
 387
 388
 389
 390
 391
 392 </div>
 393 <h2 id="get_app_state">get_app_state </h2>
 394 <div id="get_app_state_CONTENT">
 395 <p>Gets the state of the application</p>
 396 <pre>   my $app_state = SDL::Events::get_app_state();
 397
 398 </pre>
 399 <p>The $app_state is a bitwise combination of:</p>
 400 <dl>
 401         <dt>SDL_APPMOUSEFOCUS</dt>
 402         <dd>
 403                 <p>Application has mouse focus</p>
 404 <pre>   warn 'mouse focus' if $app_state &amp; SDL_APPMOUSEFOCUS
 405
 406 </pre>
 407         </dd>
 408         <dt>SDL_APPINPUTFOCUS</dt>
 409         <dd>
 410                 <p>Application has keyboard focus</p>
 411 <pre>   warn 'keyboard focus' if $app_state &amp; SDL_APPINPUTFOCUS
 412
 413
 414
 415
 416 </pre>
 417         </dd>
 418         <dt>SDL_APPACTIVE</dt>
 419         <dd>
 420                 <p>Application is visible</p>
 421 <pre>   warn 'Application Visible' if $app_state &amp; SDL_APPACTIVE
 422
 423 </pre>
 424         </dd>
 425 </dl>
 426
 427 </div>
 428 <h2 id="joystick_event_state">joystick_event_state </h2>
 429 <div id="joystick_event_state_CONTENT">
 430 <p>Enable/disable joystick event polling</p>
 431 <pre>   my $status = SDL::Events::joystick_event_state( $state );
 432
 433 </pre>
 434 <p>This function is used to enable or disable joystick event processing. With joystick event processing disabled you will have to update joystick states with SDL_JoystickUpdate and read the joystick information manually. $state can be:</p>
 435 <dl>
 436         <dt>SDL_QUERY</dt>
 437         <dt>SDL_ENABLE </dt>
 438         <dt>SDL_IGNORE</dt>
 439         <dd>
 440                 <p>Joystick event handling is default. Even if joystick event processing is enabled, individual joysticks must be opened before they generate events</p>
 441         </dd>
 442 </dl>
 443 <p><strong>Warning:</strong> Calling this function may delete all events currently in SDL's event queue.</p>
 444 <p>If $state is SDL_QUERY then the current state is returned, otherwise the new processing state is returned.</p>
 445
 446 </div>
 447 <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
 448 <div id="SEE_ALSO_CONTENT">
 449 <p><a href="SDL-Event.html">SDL::Event</a>, <a href="SDL-Video.html">SDL::Video</a>
 450 </p>
 451
 452 </div>
 453 </div>