Input

# EventQueue

This class is the interface to the eventsystem in SDL. Don't be put off by the amount of non-implemented methods, their absence doesn't bother me and I don't plan on implementing them before someone comes up with a good reason for their existence.

## Class and instance Methods

#### allowed=( eventtype ) → nil

Not implemented.

#### blocked=( eventtype ) → nil

#### flush → nil

Flushes all events from the queue.

#### get → [ Event, ... ]

Returns all events in the queue and removes them from the queue. method get( eventmask ) -> [ Event, ... ] Not implemented.

#### grab → self
grab=( grab ) → self

Controls grabbing of all mouse and keyboard input for the display. Grabbing the input is not neccessary to receive keyboard and mouse events, but it ensures all input will go to your application. It also keeps the mouse locked inside your window. It is best to not always grab the input, since it prevents the end user from doing anything else on their system. grab is true or false.

#### peek → Event or nil

Returns the next event without removing it from the queue, or nil when no events are available. method peek( eventmask ) Not implemented.

#### poll → Event or nil

Returns the next event, or nil if the queue is empty.

#### post( event ) → nil

Not implemented.

#### pump → self

This method is responsible for getting events from the operating system into the SDL eventqueue. If your application seems unresponsive, calling this method every now and then might help.

#### wait → Event

Wait for an event to arrive. Returns that event.

# Joystick

## Class methods

#### count

Returns the amount of joysticks attached to the computer.

#### new( id )

Creates a new joystick object. id is a number smaller than count. This will also start events for this joystick.

## Instance methods

#### axes

Returns the amount of axes the joystick has.

#### axis( nr )

Returns the state of axis nr, which is between -1 to 1.

#### ball( nr )

Returns the state of ball nr, which is an array of [dx, dy] where dx and dy are between -1 to 1.

#### balls

Returns the amount of trackballs the joystick has.

#### button( nr )

Returns the boolean state of button nr.

#### buttons

Returns the amount of buttons the joystick has.

#### hat( nr )

Returns the state of hat nr, which is an array of [dx, dy] where dx and dy can be -1, 0 or 1.

#### hats

Returns the amount of hats the joystick has.

#### id

Returns the id of the joystick as it was passed to new.

## Joystick input event classes

JoyAxisEvent
  Contains id which is the joysticknumber, value which is the movement, ranging from -1 to 1 and axis which is the axis index.

JoyBallEvent
  Contains id which is the joysticknumber, ball which is a trackball index and rel which is a movement array of [dx, dy].

JoyHatEvent
  Contains id which is the joysticknumber, hat which is the hatnumber and a movement array of [dx, dy] called value where dx and dy can be -1, 0 or 1.

JoyButtonUpEvent
  Contains id which is the joysticknumber and button which is the button index.

JoyButtonDownEvent
  Contains id which is the joysticknumber and button which is the button index.

# Key

The Key class gives access to the keyboard without events.

You can either call the class methods: "Key.something" directly, or instantiate the class and lug along a reference to it and call instance methods on that: "k=Key.new" "k.something" (they will call class methods under the hood, so it's exactly the same)

EventQueue.pump will update the state of Key, so if no keys seem to be pressed, call pump.

## Class and instance Methods

#### focused? → boolean

Returns true when the application has the keyboard input focus.

#### modifiers → Number
modifiers=( modifiers ) → self

Returns the current modifier keys state. Sets the keyboard modifier state.

#### name( key ) → String

Returns a string describing constant key.

#### pressed? → { K_b → true, ... }

Returns a hash containing all keys that are set, set to true. So, if K_b is pressed, the hash will contain a key,value pair of K_b => true.

#### set_repeat( delay, interval ) → self

Sets the keyboard to wait for delay milliseconds before starting repeat with interval delay between repeats. Set both to zero to disable repeat.

## Constants

Keycodes in one handy big mess: (found in the module RUDL::Constant)

K_UNKNOWN, K_FIRST, K_BACKSPACE, K_TAB, K_CLEAR, K_RETURN, K_PAUSE, K_ESCAPE, K_SPACE, K_EXCLAIM, K_QUOTEDBL, K_HASH, K_DOLLAR, K_AMPERSAND, K_QUOTE, K_LEFTPAREN, K_RIGHTPAREN, K_ASTERISK, K_PLUS, K_COMMA, K_MINUS, K_PERIOD, K_SLASH, K_0, K_1, K_2, K_3, K_4, K_5, K_6, K_7, K_8, K_9, K_COLON, K_SEMICOLON, K_LESS, K_EQUALS, K_GREATER, K_QUESTION, K_AT, K_LEFTBRACKET, K_BACKSLASH, K_RIGHTBRACKET, K_CARET, K_UNDERSCORE, K_BACKQUOTE, K_a, K_b, K_c, K_d, K_e, K_f, K_g, K_h, K_i, K_j, K_k, K_l, K_m, K_n, K_o, K_p, K_q, K_r, K_s, K_t, K_u, K_v, K_w, K_x, K_y, K_z, K_DELETE, K_KP0, K_KP1, K_KP2, K_KP3, K_KP4, K_KP5, K_KP6, K_KP7, K_KP8, K_KP9, K_KP_PERIOD, K_KP_DIVIDE, K_KP_MULTIPLY, K_KP_MINUS, K_KP_PLUS, K_KP_ENTER, K_KP_EQUALS, K_UP, K_DOWN, K_RIGHT, K_LEFT, K_INSERT, K_HOME, K_END, K_PAGEUP, K_PAGEDOWN, K_F1, K_F2, K_F3, K_F4, K_F5, K_F6, K_F7, K_F8, K_F9, K_F10, K_F11, K_F12, K_F13, K_F14, K_F15, , K_NUMLOCK, K_CAPSLOCK, K_SCROLLOCK, K_RSHIFT, K_LSHIFT, K_RCTRL, K_LCTRL, K_RALT, K_LALT, K_RMETA, K_LMETA, K_LSUPER, K_RSUPER, K_MODE, K_HELP, K_PRINT, K_SYSREQ, K_BREAK, K_MENU, K_POWER, K_EURO, K_LAST, KMOD_NONE, KMOD_LSHIFT, KMOD_RSHIFT, KMOD_LCTRL, KMOD_RCTRL, KMOD_LALT, KMOD_RALT, KMOD_LMETA, KMOD_RMETA, KMOD_NUM, KMOD_CAPS, KMOD_MODE, KMOD_CTRL, KMOD_SHIFT, KMOD_ALT, KMOD_META

## Keyboard input event classes

KeyUpEvent
  This event is posted when a key is released. It contains key (the keycode for the released key), mod (the modifier keys state) and unicode (the Unicode version of the key).
KeyDownEvent
  This event is posted when a key is pressed and when it gets repeated (see Key#set_repeat). It contains key (the keycode for the pressed key), mod (the modifier keys state) and unicode (the Unicode version of the key).

# Mouse

The mouse class methods can also be used as instance methods once you instantiate the class. However, there is no need to do that, it's just for convenience.

## Class and instance Methods

#### focused? → boolean

Returns true when the application is receiving the mouse input focus.

#### pos → [x, y]
pos=( pos ) → self

Returns the current position of the mouse cursor. This is the absolute mouse position inside your game window. Moves the mouse cursor to the specified position. This will generate a MouseMotionEvent on the input queue.

#### pressed? → [boolean, boolean, boolean]

This will return an array containing the pressed state of each mouse button.

#### rel → [dx, dy]

Returns the total distance the mouse has moved since your last call to rel. On the first call to rel the movement will always be 0,0. When the mouse is at the edges of the screen, the relative movement will be stopped. See visible for a way to resolve this.

#### set_cursor( hotspot, xormasks, andmasks ) → self

When the mouse cursor is visible, it will be displayed as a black and white bitmap using the given bitmask arrays. Hotspot is an array containing the cursor hotspot position. xormasks is an array of arrays of bytes containing the cursor xor data masks. Lastly is andmasks, an array of arrays of bytes containting the cursor bitmask data.

The example "mousecursor.rb" explains this much better.

#### visible=( onOrOff ) → boolean

Shows or hides the mouse cursor. This will return the previous visible state of the mouse cursor.

Note that when the cursor is hidden and the application has grabbed the input. SDL will force the mouse to stay in the center of the screen. Since the mouse is hidden it won't matter that it's not moving, but it will keep the mouse from the edges of the screen so the relative mouse position will always be true.

## Mouse input event classes

MouseMotionEvent
  Contains pos (an array [x, y] telling the position of the mouse), rel (an array [dx, dy] telling how much the mouse moved), and button (an array of booleans, representing the states of the mousebuttons). Currently, three buttons are supported.
MouseButtonUpEvent
  Contains pos (an array [x, y] telling the position of the mouse) and button (the number of the button that was released).
MouseButtonDownEvent
  Contains pos (an array [x, y] telling the position of the mouse) and button (the number of the button that was pressed).