= Event
* ((<Event system Overview>))
* ((<SDL::Event>))
* ((<SDL::Event::Active>))
* ((<SDL::Event::KeyDown>))
* ((<SDL::Event::KeyUp>))
* ((<SDL::Event::MouseMotion>))
* ((<SDL::Event::MouseButtonDown>))
* ((<SDL::Event::MouseButtonUp>))
* ((<SDL::Event::JoyAxis>))
* ((<SDL::Event::JoyBall>))
* ((<SDL::Event::JoyHat>))
* ((<SDL::Event::JoyButtonDown>))
* ((<SDL::Event::JoyButtonUp>))
* ((<SDL::Event::Quit>))
* ((<SDL::Event::SysWM>))
* ((<SDL::Event::VideoResize>))
* ((<SDL::Event::VideoExpose>))
* ((<SDL::Key>))
* ((<SDL::Mouse>))
* Methdos for Event
TOC

== Event system Overview
Event handling allows your application to receive input from the user.
Event handling is initalised (along with video) with a call to:
  SDL_Init(SDL_INIT_VIDEO);
Internally, SDL stores all the events waiting to be handled in an event queue.
Using functions like @[Event.poll] and @[Event.wait]
you can observe and handle waiting input events.

The key to event handling in SDL is the subclasses of @[Event].
The event queue itself is composed of a series of 
instance of (subclasses of) @[Event], one for each waiting event.
Those objects are read from queue with the @[Event.poll] and it is
then up to the application to process the information stored with them.

Subclasses of @[Event] is following:
* @[Event::Active]
* @[Event::KeyDown]
* @[Event::KeyUp]
* @[Event::MouseMotion]
* @[Event::MouseButtonDown]
* @[Event::MouseButtonUp]
* @[Event::JoyAxis]
* @[Event::JoyBall]
* @[Event::JoyHat]
* @[Event::JoyButtonDown]
* @[Event::JoyButtonUp]
* @[Event::Quit]
* @[Event::SysWM]
* @[Event::VideoResize]
* @[Event::VideoExpose]

Those classes have two uses.
* Reading events on the event queue.
* Placing events on the event queue.

Reading events from the event queue is done with @[Event.poll].
We'll use @[Event.poll] and step through an example.
@[Event.poll] removes the next event from the event queue, 
if there are no events on the queue it returns nil
otherwise it returns event object. 
We use a while loop to process each event in turn.

  while event = SDL::Event.poll

We know that if @[Event.poll] removes an event from the queue then the event information will
be placed in returned object, but we also know that the class of that object will represent
the type of event. So we handle each event type seperately we use a switch statement.

  case event

We need to know what kind of events we're looking for ((*and*)) the event type's of those events.
So lets assume we want to detect where the user is moving the mouse pointer within our application.
We look through our event types and notice that @[Event::MouseMotion] is, more than likely,
the event we're looking for. A little more research tells use that
mouse motion events are handled within the @[Event::MouseMotion].
We can check for the mouse motion event type within our switch statement like so:

  when SDL::Event::MouseMotion

All we need do now is read the information out of this object as instance 
of @[Event::MouseMotion].
  
    puts "We got a motion event"
    puts "Current mouse position is: (#{event.x}, #{event.y})"
  else
    puts "Unhandled Event!"
  end
  end
  puts "Event queue is empty."

It is also possible to push events onto the event queue.
[Event.push]  allows you to place events onto the event queue.
You can use it to post fake input events if you wished.

== SDL::Event
This class handle events. All objects returned by @[Event.poll] are
instances of subclasses of SDL::Event.

== Compatiblity
The class that used to be known as SDL::Event is remove.
The class now called SDL::Event was called SDL::Event2 before.
A constant SDL::Event2 remains as alias of SDL::Event because of compatiblity with older version.

== SDL::Event::Active
Class for Application visibility event.

This event raises when the mouse leaves or enters the window area,
the application loses or gains keyboard focus,
or the application is either minimised/iconified or restored.

@[Event::Active#state] returns which event occurs.

* NOTES

  This event does not occur when an application window is first created.

METHODS(Event::Active)

== SDL::Event::KeyDown

Class for keyboard down event.

METHODS(Event::KeyDown)

== SDL::Event::KeyUp

Class for key up event.

METHODS(Event::KeyUp)

== SDL::Event::MouseMotion

Class for mouse motion event.

Simply put, a event of this type occurs 
when a user moves the mouse within the application window or when [Mouse.warp] is called.
Both the absolute coordinate (@[Event::MouseMotion#x] and @[Event::MouseMotion#y]) and
relative coordinate (@[Event::MouseMotion#xrel] and @[Event::MouseMotion#yrel]) 
are reported along with the current button states (@[Event::MouseMotion#state]).

METHODS(Event::MouseMotion)

== SDL::Event::MouseButtonDown
Class for mouse button press event.

This type of event occurs when a mouse button press is detected.

METHODS(Event::MouseButtonDown)

== SDL::Event::MouseButtonUp
Class for mouse button release event.

This type of event occurs when a mouse button release is detected.

METHODS(Event::MouseButtonUp)

== SDL::Event::JoyAxis
Class for joystick axis motion event. 

This event occurs when ever a user moves an axis on the joystick. 

METHODS(Event::JoyAxis)

* SEEALSO
  @[Joystick#num_axes], @[Joystick#axis]

== SDL::Event::JoyBall
Class for joystick ball motion event.

This type of event occurs when a user moves a trackball on the joystick.

METHODS(Event::JoyBall)

* SEEALSO

  @[Joystick#num_balls], @[Joystick#ball]

== SDL::Event::JoyHat
Class for joystick hat position change event.

METHODS(Event::JoyHat)

* SEEALSO
  
  @[Joystick#num_hats], @[Joystick#hat]

== SDL::Event::JoyButtonDown
Class for joystick button press event.

This event occurs when a user presses a button on a joystick.

METHODS(Event::JoyButtonDown)

* SEEALSO

  @[Joystick#num_buttons], @[Joystick#button]

== SDL::Event::JoyButtonUp
Class for joystick button release event.

This event occurs when a user releases a button on a joystick.

METHODS(Event::JoyButtonUp)

* SEEALSO

  @[Joystick#num_buttons], @[Joystick#button]

== SDL::Event::Quit
Class for quit reqested event.

This event is very important.
If you filter out or ignore a quit event then it is impossible for the user to
close the window. On the other hand, if you do accept a quit event then the application window will be
closed, and screen updates will still report success event though the application will no longer be
visible.

== SDL::Event::SysWM
Class for platform-dependent window manager event.

Event of this type occurs when unknown window manager event happens.
You can never know the detail of this event.
Only you can to do is to ignore this event.

== SDL::Event::VideoResize
Class for window resize event.

When SDL::RESIZABLE is passed as a $[flag] to 
@[Screen.open] the user is allowed to resize the applications
window. When the window is resized an event of this type is report,
with the new window width and height values stored in @[Event::VideoResize#w] and
 @[Event::VideoResize#h] respectively.

When this event is recieved the window should be resized
to the new dimensions using @[Screen.open].

== SDL::Event::VideoExpose
Class for video expose event.

This event is triggered when the screen has been modified outside of the application, usually by
the window manager and needs to be redrawn.

== SDL::Key
Module for keyboard input.

This module defines some keyboard-related constants and 
module functions.

METHODS(Key)

=== Key symbol
Key symbol constants definitions.
* SDL::Key::BACKSPACE  '\b'  backspace  
* SDL::Key::TAB  '\t' tab  
* SDL::Key::CLEAR     clear
* SDL::Key::RETURN  '\r'  return
* SDL::Key::PAUSE    pause
* SDL::Key::ESCAPE  '^['  escape
* SDL::Key::SPACE  ' '   space
* SDL::Key::EXCLAIM  '!'   exclaim
* SDL::Key::QUOTEDBL  '"'   quotedbl
* SDL::Key::HASH  '#'   hash
* SDL::Key::DOLLAR  '$'   dollar
* SDL::Key::AMPERSAND  '&'  ampersand
* SDL::Key::QUOTE  '''  quote
* SDL::Key::LEFTPAREN  '('   left parenthesis
* SDL::Key::RIGHTPAREN  ')'  right parenthesis
* SDL::Key::ASTERISK  '*'  asterisk
* SDL::Key::PLUS  '+'  plus sign
* SDL::Key::COMMA  ','  comma
* SDL::Key::MINUS  '-'  minus sign
* SDL::Key::PERIOD  '.'  period
* SDL::Key::SLASH  '/'  forward slash
* SDL::Key::K0  '0'  0
* SDL::Key::K1  '1'  1
* SDL::Key::K2  '2'  2
* SDL::Key::K3  '3'  3
* SDL::Key::K4  '4'  4
* SDL::Key::K5  '5'  5
* SDL::Key::K6  '6'  6
* SDL::Key::K7  '7'  7
* SDL::Key::K8  '8'  8
* SDL::Key::K9  '9'  9
* SDL::Key::COLON  ':'  colon
* SDL::Key::SEMICOLON  ';'  semicolon
* SDL::Key::LESS  '&lt;'  less-than sign
* SDL::Key::EQUALS  '='   equals sign
* SDL::Key::GREATER  '&gt;'   greater-than sign
* SDL::Key::QUESTION  '?'   question mark
* SDL::Key::AT  '@'   at
* SDL::Key::LEFTBRACKET  '['   left bracket
* SDL::Key::BACKSLASH  '\'   backslash
* SDL::Key::RIGHTBRACKET  ']'   right bracket
* SDL::Key::CARET  '^'   caret
* SDL::Key::UNDERSCORE  '_'   underscore
* SDL::Key::BACKQUOTE  '`'   grave
* SDL::Key::A  'a'  a  
* SDL::Key::B  'b'  b  
* SDL::Key::C  'c'  c  
* SDL::Key::D  'd'  d  
* SDL::Key::E  'e'  e  
* SDL::Key::F  'f'  f  
* SDL::Key::G  'g'  g  
* SDL::Key::H  'h'  h  
* SDL::Key::I  'i'  i  
* SDL::Key::J  'j'  j  
* SDL::Key::K  'k'  k  
* SDL::Key::L  'l'  l  
* SDL::Key::M  'm'  m  
* SDL::Key::N  'n'  n  
* SDL::Key::O  'o'  o  
* SDL::Key::P  'p'  p  
* SDL::Key::Q  'q'  q  
* SDL::Key::R  'r'  r  
* SDL::Key::S  's'  s  
* SDL::Key::T  't'  t  
* SDL::Key::U  'u'  u  
* SDL::Key::V  'v'  v  
* SDL::Key::W  'w'  w  
* SDL::Key::X  'x'  x  
* SDL::Key::Y  'y'  y  
* SDL::Key::Z  'z'  z  
* SDL::Key::DELETE  '^?'  delete  
* SDL::Key::KP0     keypad 0
* SDL::Key::KP1     keypad 1
* SDL::Key::KP2     keypad 2
* SDL::Key::KP3     keypad 3
* SDL::Key::KP4     keypad 4
* SDL::Key::KP5     keypad 5
* SDL::Key::KP6     keypad 6
* SDL::Key::KP7     keypad 7
* SDL::Key::KP8     keypad 8
* SDL::Key::KP9     keypad 9
* SDL::Key::KP_PERIOD  '.'   keypad period
* SDL::Key::KP_DIVIDE  '/'   keypad divide
* SDL::Key::KP_MULTIPLY  '*'   keypad multiply
* SDL::Key::KP_MINUS  '-'   keypad minus
* SDL::Key::KP_PLUS  '+'   keypad plus
* SDL::Key::KP_ENTER  '\r'   keypad enter
* SDL::Key::KP_EQUALS  '='   keypad equals
* SDL::Key::UP     up arrow
* SDL::Key::DOWN     down arrow
* SDL::Key::RIGHT     right arrow
* SDL::Key::LEFT     left arrow
* SDL::Key::INSERT    insert  
* SDL::Key::HOME    home  
* SDL::Key::END    end  
* SDL::Key::PAGEUP    page up  
* SDL::Key::PAGEDOWN    page down  
* SDL::Key::F1    F1  
* SDL::Key::F2    F2  
* SDL::Key::F3    F3  
* SDL::Key::F4    F4  
* SDL::Key::F5    F5  
* SDL::Key::F6    F6  
* SDL::Key::F7    F7  
* SDL::Key::F8    F8  
* SDL::Key::F9    F9  
* SDL::Key::F10    F10  
* SDL::Key::F11    F11  
* SDL::Key::F12    F12  
* SDL::Key::F13    F13  
* SDL::Key::F14    F14  
* SDL::Key::F15    F15  
* SDL::Key::NUMLOCK    numlock  
* SDL::Key::CAPSLOCK    capslock  
* SDL::Key::SCROLLOCK    scrollock  
* SDL::Key::RSHIFT     right shift
* SDL::Key::LSHIFT     left shift
* SDL::Key::RCTRL     right ctrl
* SDL::Key::LCTRL     left ctrl
* SDL::Key::RALT     right alt
* SDL::Key::LALT     left alt
* SDL::Key::RMETA     right meta
* SDL::Key::LMETA     left meta
* SDL::Key::LSUPER     left windows key
* SDL::Key::RSUPER     right windows key
* SDL::Key::MODE     mode shift
* SDL::Key::HELP    help  
* SDL::Key::PRINT    print-screen  
* SDL::Key::SYSREQ    SysRq  
* SDL::Key::BREAK    break  
* SDL::Key::MENU    menu  
* SDL::Key::POWER    power  
* SDL::Key::EURO     euro

== SDL::Mouse
Module for mouse input.

This module defines some mouse constants and module functions.

METHODS(Mouse)
== Methods
%%%
NAME poll
MOD Event
TYPE .
PURPOSE Polls for currently pending events.
RVAL Event/nil

PROTO
poll

DESC
Polls for currently pending events, and returns event object if there
are any pending events, or nil if there are none
available.

If event object is returned, the next event is removed from 
the queue and stored in that area.

EXAMPLE
while event = SDL::Event.poll # Loop until there are no events left on the queue
  case event # Process the appropiate event type
  when SDL::Event::KeyDown # Handle a KEYDOWN event
    puts "Oh! Key press"
  when SDL::Event::MouseMotion
    .
    .
    .
  else # Report an unhandled event
    puts "I don't know what this event is!"
  end
end

SEEALSO
Event
Event.wait

%%
NAME wait
MOD Event
TYPE .
PURPOSE Waits indefinitely for the next available event.
RVAL Event/nil

PROTO
wait

DESC
Waits indefinitely for the next available event and return that event.

If event object is returned, the next event is removed
from the queue and stored in that area.

EXCEPTION
Raise @[Error] if there was an error while waiting
for events.

NOTES
In Ruby 1.9 and above, this method releases the global VM lock (GVL) prior to
calling the underlying SDL_WaitEvent function.  This allows other Ruby threads to
continue executing while waiting for an event.

In Ruby 1.8 and below, there is no way to release the GVL, so all Ruby threads
suspend execution until this method finishes.

This method may return nil when Ruby/SDL encounters an unknown type of event.
You should treat this case.

SEEALSO
Event.poll

%%
NAME push
MOD Event
TYPE .
PURPOSE Pushes an event onto the event queue.

PROTO
push(event)

DESC
Push $[event] onto event queue.

NOTES
Pushing device input events onto the queue doesn't modify the 
state of the device within SDL.

EXCEPTION *

SEEALSO
Event.poll

%%
NAME app_state
MOD Event
TYPE .
PURPOSE Get the state of the application.
RVAL UINT

PROTO
app_state
appState

DESC
This method returns the current state of the application. 
The value returned is a bitwise combination of:
:SDL::Event::APPMOUSEFOCUS
  The application has mouse focus. 
:SDL::Event::APPINPUTFOCUS
  The application has keyboard focus.
:SDL::Event::APPACTIVE
  The application is visible.

SEEALSO
Event::Active

%%
NAME enable_unicode
MOD Event
TYPE .
PURPOSE Enable UNICODE translation

PROTO
enable_unicode
enableUNICODE

DESC
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 received key down event, 
@[Event::KeyDown#unicode] will then contain the corresponding character code, 
or zero for keysyms that do not correspond to any character code.

NOTES
Note that only key press events will be translated, not release events.

SEEALSO
Event.disable_unicode
Event.enable_unicode?

%%
NAME disable_unicode
MOD Event
TYPE .
PURPOSE Disable UNICODE translation

PROTO
disable_unicode
disableUNICODE

DESC
Disables Unicode keyboard translation. Please see @[Event.enable_unicode]
in detail.

%%
NAME enable_unicode?
MOD Event
TYPE .
PURPOSE Get whether UNICODE translation is enabled.
RVAL true/false

PROTO
enable_unicode?
enableUNICODE?

DESC
Returns true if Unicode keyboard translation is enabled, otherwise
returns false. Please see @[Event.enable_unicode] in detail.

%%
NAME gain
TYPE #
MOD Event::Active
PURPOSE Returns whether gaining visibility or not
RVAL true/false

PROTO
gain

DESC
Returns true if the mouse enters the window, the application gains keyboard focus, or
minimized/iconcified window is restored.
Otherwise returns false.

SEEALSO
Event::Active
Event::Active#state

%%
NAME state
MOD Event::Active
TYPE #
PURPOSE Gets the type of visibility event.
RVAL SDL::Event::APPMOUSEFOCUS/SDL::Event::APPINPUTFOCUS/SDL::Event::APPACTIVE

PROTO
state

DESC
Returns one of following three constants:
* SDL::Event::APPMOUSEFOCUS

  This event occurs when the mouse leaves or enters the window area.

* SDL::Event::APPINPUTFOCUS

  THis event occurs when the application loses or gains input focus.

* SDL::Event::APPACTIVE

  This event occurs when the application is either minimized/iconcified or restored.

SEEALSO
Event::Active
Event::Active#gain

%%
NAME press
MOD Event::KeyDown
TYPE #
PURPOSE Returns true.
RVAL true

PROTO
press

DESC
Always returns true.

SEEALSO
Event::KeyUp#press

%%
NAME sym
MOD Event::KeyDown
TYPE #
PURPOSE Get the key symbol of pressed key
RVAL Integer

PROTO
sym

DESC
Returns pressed ((<Key symbol>)).

SEEALSO
Event::KeyDown#unicode

%%
NAME mod
MOD Event::KeyDown
TYPE #
PURPOSE Current key modifier
RVAL UINT

PROTO
mod

DESC
Returns the current state of keyboard modifiers as explained in @[Key.mod_state].

SEEALSO
Key.mod_state

%%
NAME unicode
MOD Event::KeyDown
TYPE #
PURPOSE Translated character
RVAL UINT

PROTO
unicode

DESC
Returns the UNICODE character corresponding to the keypress if Unicode translation
is enabled with @[Event.enable_unicode]. 
If the high 9 bits of the character are 0, then this
maps to the equivalent ASCII character:

Returns zero if unicode translation is disabled.

%%
NAME press
MOD Event::KeyUp
TYPE #
PURPOSE Whether key is pressed
RVAL false

PROTO
press

DESC
Always returns false.

SEEALSO
Event::KeyDown#press

%%
NAME sym
MOD Event::KeyUp
TYPE #
PURPOSE Get the key symbol of released key
RVAL Integer

PROTO
sym

DESC
Returns the released ((<Key symbol>))

%%
NAME mod
MOD Event::KeyUp
TYPE #
PURPOSE Current key modifier
RVAL UINT

PROTO
mod

DESC
Returns the current state of keyboard modifiers as explained in @[Key.mod_state].

SEEALSO
Key.mod_state

%%
NAME state
MOD Event::MouseMotion
TYPE #
PURPOSE The current button state
RVAL UINT

PROTO
state

DESC
Returns the current button state.
The value returned is a bitwise combination of:

:SDL::Mouse::BUTTON_LMASK
  Left button
:SDL::Mouse::BUTTON_MMASK
  Middle button
:SDL::Mouse::BUTTON_RMASK
  Right button

SEEALSO
Mouse.state

%%
NAME x
MOD Event::MouseMotion
TYPE #
PURPOSE The X coordinate of the mouse
RVAL UINT

PROTO
x

DESC
Returns the X coordinate of the mouse.

SEEALSO
Mouse.state

%%
NAME y
MOD Event::MouseMotion
TYPE #
PURPOSE the X coordinate of the mouse.
RVAL UINT

PROTO
y

DESC
Returns the Y coordinate of the mouse.

SEEALSO
Mouse.state

%%
NAME xrel
MOD Event::MouseMotion
TYPE #
PURPOSE Relative motion in the X direction
RVAL Integer

PROTO
xrel

DESC
Returns relative motion in the X direction.

%%
NAME yrel
MOD Event::MouseMotion
TYPE #
PURPOSE Relative motion in the Y direction
RVAL Integer

PROTO
yrel

DESC
Returns relative motion in the Y direction.

%%
NAME button
MOD Event::MouseButtonDown
TYPE #
PURPOSE The mouse button index

PROTO
button

DESC
Returns number of the button pressed:
* SDL::Mouse::BUTTON_LEFT
* SDL::Mouse::BUTTON_MIDDLE
* SDL::Mouse::BUTTON_RIGHT

%%
NAME press
MOD Event::MouseButtonDown
TYPE #
PURPOSE Whether mouse button is pressed or not
RVAL true

PROTO
press

DESC
Always returns true.

SEEALSO
Event::MouseButtonUp#press

%%
NAME x
MOD Event::MouseButtonDown
TYPE #
PURPOSE The X coordinate of the mouse at press time.
RVAL UINT

PROTO
x

DESC
Returns the X coordinate of the mouse.

SEEALSO
Mouse.state

%%
NAME y
MOD Event::MouseButtonDown
TYPE #
PURPOSE The Y coordinate of the mouse at press time
RVAL UINT

PROTO
y

DESC
Returns the Y coordinate of the mouse at press time.

SEEALSO
Mouse.state

%%
NAME button
MOD Event::MouseButtonUp
TYPE #
PURPOSE The mouse button index

PROTO
button

DESC
Returns number of the button released:
* SDL::Mouse::BUTTON_LEFT
* SDL::Mouse::BUTTON_MIDDLE
* SDL::Mouse::BUTTON_RIGHT

%%
NAME press
MOD Event::MouseButtonUp
TYPE #
PURPOSE Whether mouse button is pressed or not
RVAL false

PROTO
press

DESC
Always returns false.

SEEALSO
Event::MouseButtonDown#press

%%
NAME x
MOD Event::MouseButtonUp
TYPE #
PURPOSE The X coordinate of the mouse at release time
RVAL UINT

PROTO
x

DESC
Returns the X coordinate of the mouse at release time.

SEEALSO
Mouse.state

%%
NAME y
MOD Event::MouseButtonUp
TYPE #
PURPOSE The Y coordinate of the mouse at release time.
RVAL UINT

PROTO
y

DESC
Returns the Y coordinate of the mouse at release time.

SEEALSO
Mouse.state

%%
NAME which
MOD Event::JoyAxis
TYPE #
PURPOSE Joystick device index
RVAL Integer

PROTO
which

DESC
Returns the index of the joystick that reported the event.

SEEALSO
Joystick
Joystick#num_axes

%%
NAME axis
MOD Event::JoyAxis
TYPE #
PURPOSE JoyAxis axis index
RVAL Integer

PROTO
axis

DESC
Returns the index of the axis that reported the event.

SEEALSO
Joystick

%%
NAME value
MOD Event::JoyAxis
TYPE #
PURPOSE Axis value
RVAL -32767 - 32767

PROTO
value

DESC
Returns the position of the axis in -32767 .. 32767.

SEEALSO
Joystick
Joystick#axis

%%
NAME which
MOD Event::JoyBall
TYPE #
PURPOSE Joystick device index
RVAL Integer

PROTO
which

DESC
Returns the index of the joystick that reported the event.

SEEALSO
Joystick

%%
NAME ball
MOD Event::JoyBall
TYPE #
PURPOSE Joystick trackball index
RVAL Integer

PROTO
ball

DESC
Returns the index of the trackball that reported the event.

SEEALSO
Joystick
Joystick#num_balls

%%
NAME xrel
MOD Event::JoyBall
TYPE #
PURPOSE The relative motion in the X direction
RVAL Integer

PROTO
xrel

DESC
Returns the relative motion in the X direction as Integer.
This value is the change in position on the ball since it was last polled.

SEEALSO
Joystick
Joystick#ball

%%
NAME yrel
MOD Event::JoyBall
TYPE #
PURPOSE The relative motion in the Y direction.

RVAL Integer

PROTO
yrel

DESC
Returns the relative motion in the Y direction as Integer.
This value is the change in position on the ball since it was last polled.

SEEALSO
Joystick
Joystick#ball

%%
NAME which
MOD Event::JoyHat
TYPE #
PURPOSE Joystick device index
RVAL Integer

PROTO
which

DESC
Returns the index of the joystick that reported the event.

SEEALSO
Joystick

%%
NAME hat
MOD Event::JoyHat
TYPE #
PURPOSE Joystick hat index
RVAL Integer

PROTO
hat

DESC
Returns the index of the hat that reported the event.

SEEALSO
Joystick
Joystick#num_hats

%%
NAME value
MOD Event::JoyHat
TYPE #
PURPOSE Hat position
RVAL UINT

PROTO
value

DESC
Returns the current position of the hat. It is a logically OR'd
combination of the following values (whose meanings should be pretty obvious:) :

* SDL::Joystick::HAT_CENTERED
* SDL::Joystick::HAT_UP
* SDL::Joystick::HAT_RIGHT
* SDL::Joystick::HAT_DOWN
* SDL::Joystick::HAT_LEFT

The following defines are also provided:
* SDL::Joystick::HAT_RIGHTUP
* SDL::Joystick::HAT_RIGHTDOWN
* SDL::Joystick::HAT_LEFTUP
* SDL::Joystick::HAT_LEFTDOWN

%%
NAME which
MOD Event::JoyButtonDown
TYPE #
PURPOSE Joystick device index
RVAL Integer

PROTO
which

DESC
Returns the index of the joystick that reported the event.

SEEALSO
Joystick

%%
NAME button
MOD Event::JoyButtonDown
TYPE #
PURPOSE Joystick button index
RVAL Integer

PROTO
button

DESC
Returns the index of the button that reported the event.

SEEALSO
Joystick
Joystick#num_buttons

%%
NAME press
MOD Event::JoyButtonDown
TYPE #
PURPOSE Joystick button is pressed or released
RVAL true

PROTO
press

DESC
Returns whether this event is button press event.
Always returns true.

SEEALSO
Event::JoyButtonUp#press
Joystick#button

%%
NAME which
MOD Event::JoyButtonUp
TYPE #
PURPOSE Joystick device index
RVAL Integer

PROTO
which

DESC
Returns the index of the joystick that reported the event.

SEEALSO
Joystick

%%
NAME button
MOD Event::JoyButtonUp
TYPE #
PURPOSE Joystick button index
RVAL Integer

PROTO
button

DESC
Returns the index of the button that reported the event.

SEEALSO
Joystick
Joystick#num_buttons

%%
NAME press
MOD Event::JoyButtonUp
TYPE #
PURPOSE Joystick button is pressed or released
RVAL false

PROTO
press

DESC
Returns whether this event is button press event.
Always returns false.

SEEALSO
Event::JoyButtonDown#press
Joystick#button

%%
NAME w
MOD Event::VideoResize
TYPE #
PURPOSE New width of the window.
RVAL Integer

PROTO
w

DESC
Returns the new width of the window when window is resized.

%%
NAME h
MOD Event::VideoResize
TYPE #
PURPOSE New height of the window 
RVAL Integer

PROTO
h

DESC
Returns the new width of the window when window is resized.

%%
NAME scan
MOD Key
TYPE .
PURPOSE Get a snapshot of the current keyboard state

PROTO
scan

DESC
Gets a snapshot of the current keyboard state.
You can check this state with @[Key.press?].

NOTE
Call @[Event.poll] or @[Event.wait] to update the state.

SEEALSO
Key.press?
Event::KeyDown
Event::KeyUp
Event.poll

%%
NAME press?
MOD Key
TYPE .
PURPOSE Get the current keyboard state.
RVAL true/false

PROTO
press?(key)

DESC
Returns true if $[key] is pressed, otherwise returns false.
Please use ((<Key symbol>)) as parameter.

SEEALSO
Key.scan
Event::KeyDown
Event::KeyUp

%%
NAME mod_state
MOD Key
TYPE .
PURPOSE Get the state of modifier keys.
RVAL UINT

PROTO
mod_state
modState

DESC
Returns the current state of the modifier keys (CTRL, ALT, etc.).
The return value can be an OR'd combination of:
:SDL::Key::MOD_NONE
:SDL::Key::MOD_LSHIFT
:SDL::Key::MOD_RSHIFT
:SDL::Key::MOD_LCTRL
:SDL::Key::MOD_RCTRL
:SDL::Key::MOD_LALT
:SDL::Key::MOD_RALT
:SDL::Key::MOD_LMETA
:SDL::Key::MOD_RMETA
:SDL::Key::MOD_NUM
:SDL::Key::MOD_CAPS
:SDL::Key::MOD_MODE
 
SDL also defines the following symbols for convenience:
* SDL::Key::MOD_CTRL = SDL::Key::MOD_LCTRL|SDL::Key::MOD_RCTRL
* SDL::Key::MOD_SHIFT = SDL::Key::MOD_LSHIFT|SDL::Key::MOD_RSHIFT
* SDL::Key::MOD_ALT = SDL::Key::MOD_LALT|SDL::Key::MOD_RALT
* SDL::Key::MOD_META = SDL::Key::MOD_LMETA|SDL::Key::MOD_RMETA

SEEALSO
Key.scan

%%
NAME get_key_name
MOD Key
TYPE .
PURPOSE Get the name of an SDL virtual keysym
RVAL String

PROTO
get_key_name(key)
getKeyName(key)

DESC
Returns the SDL-defined name of the $[key] ((<key symbol|Key symbol>)).

%%
NAME enable_key_repeat
MOD Key
TYPE .
PURPOSE Set keyboard repeat rate.

PROTO
enable_key_repeat(delay,interval)
enableKeyRepeat(delay,interval)

DESC
Enables the keyboard repeat rate. $[delay] specifies how long the key must be pressed before it
begins repeating, it then repeats at the speed specified by $[interval]. Both delay and interval are
expressed in milliseconds.

Good default values are SDL::Key::DEFAULT_REPEAT_DELAY and 
SDL::Key::DEFAULT_REPEAT_INTERVAL.

EXCEPTION *

SEEALSO
Key.disable_key_repeat

%%
NAME disable_key_repeat
MOD Key
TYPE .
PURPOSE Disable key repeat.

PROTO
disable_key_repeat
disableKeyRepeat

DESC
Disables key repeat.

EXCEPTION *

SEEALSO
Key.enable_key_repeat

%%
NAME state
MOD Mouse
TYPE .
PURPOSE Retrieve the current state of the mouse
RVAL [Integer, Integer, true/false, true/false, true/false]
PROTO
state

DESC
Returns an array of five element:
  [ X coordinate, Y coordinate, left button is pressed?, middle button is pressed?, right button is pressed?]

EXAMPLE
x, y, lbutton, * = SDL::Mouse.state
if lbutton
  print "Left Mouse Button is pressed \n"
end

SEEALSO
Event::MouseMotion
Event::MouseButtonDown
Event::MouseButtonUp

%%
NAME warp
MOD Mouse
TYPE .
PURPOSE Set the position of the mouse cursor.

PROTO
warp(x,y)

DESC
Set the position of the mouse cursor (generates a mouse motion event).

SEEALSO
Event::MouseMotion

%%
NAME show
MOD Mouse
TYPE .
PURPOSE Toggle the cursor is shown on the screen.

PROTO
show

DESC
Shows cursor.

The cursor starts off displayed, but can be turned off.

SEEALSO
Mouse.hide
Mouse.show?

%%
NAME hide
MOD Mouse
TYPE .
PURPOSE Hide cursor.

PROTO
hide

DESC
Hide cursor.

SEEALSO
Mouse.show
Mouse.show?

%%
NAME show?
MOD Mouse
TYPE .
PURPOSE Get the state of mouse cursor.
RVAL true/false

PROTO
show?

DESC
Returns true if mouse cursor is shown, otherwise returns false.

SEEALSO
Mouse.show
Mouse.hide

%%
NAME set_cursor
MOD Mouse
TYPE .
PURPOSE Set the currently active mouse cursor.

PROTO
set_cursor(bitmap,white,black,transparent,inverted,hot_x=0,hot_y=0)
setCursor(bitmap,white,black,transparent,inverted,hot_x=0,hot_y=0)

DESC
Sets the currently active cursor to the specified one. If the cursor is currently visible, the change
will be immediately represented on the display.

$[bitmap] is shape of cursor, given by the instance of @[Surface].
$[white] is white color pixel value in $[bitmap], 
$[black] is black color pixel value in $[bitmap], 
$[transparent] is transparent pixel value in $[bitmap], 
$[inverted] is inverted pixel value in $[bitmap].
The cursor width must be a multiple of 8 bits.

SEEALSO
Surface