Class: Rubygame::Joystick

Inherits:
Object
  • Object
show all
Defined in:
lib/rubygame/joystick.rb

Overview

The Joystick class interfaces with joysticks, gamepads, and other similar hardware devices used to play games. Each joystick may have zero or more #axes, #balls, #hats, and/or #buttons.

After a Joystick object is successfully created, events for that Joystick will begin appearing on the EventQueue when a button is pressed or released, a control stick is moved, etc.

You can use Joystick.activate_all to start receiving events for all joysticks (equivalent to creating them all individually with Joystick.new). You can use Joystick.deactivate_all to stop receiving events for all joysticks.

As of Rubygame 2.4, these are the current, “new-style” Joystick event classes:

  • Events::JoystickAxisMoved

  • Events::JoystickButtonPressed

  • Events::JoystickButtonReleased

  • Events::JoystickBallMoved

  • Events::JoystickHatMoved

These old Joystick-related events are deprecated and will be removed in Rubygame 3.0:

  • JoyAxisEvent

  • JoyBallEvent

  • JoyHatEvent

  • JoyDownEvent

  • JoyUpEvent

For more information about “new-style” events, see EventQueue.enable_new_style_events.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(index) ⇒ Joystick

Create and initialize an interface to the Nth joystick on the system. Raises SDLError if the joystick could not be opened.



122
123
124
125
126
127
128
 
# File 'lib/rubygame/joystick.rb', line 122

def initialize( index )
  @struct = SDL.JoystickOpen( index )
  if( @struct.pointer.null? )
    raise( Rubygame::SDLError, "Could not open joystick %d: %s"%
           [index, SDL.GetError()] )
  end
end

Class Method Details

.activate_all ⇒ Object

Activate all joysticks on the system, equivalent to calling Joystick.new for every joystick available. This will allow joystick-related events to be sent to the EventQueue for all joysticks.

Returns

Array of zero or more Joysticks.

May raise

SDLError, if the joystick system could not be initialized.



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/rubygame/joystick.rb', line 82

def self.activate_all
  # Initialize if it isn't already.
  if( SDL.WasInit(SDL::INIT_JOYSTICK) == 0 )
    if( SDL.Init(SDL::INIT_JOYSTICK) != 0 )
      raise Rubygame::SDLError, "Could not initialize SDL joysticks."
    end
  end

  # Collect Joystick instances in an Array
  joysticks = []

  num_joysticks.times do |i|
    joysticks << new( i )
  end

  return joysticks
end

.deactivate_all ⇒ Object

Deactivate all joysticks on the system. This will stop all joystick-related events from being sent to the EventQueue.



104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/rubygame/joystick.rb', line 104

def self.deactivate_all
  # Return right away if it isn't active
  return if( SDL.WasInit(SDL::INIT_JOYSTICK) == 0 )

  num_joysticks.times do |i|
    joy = SDL.JoystickOpen(i)
    unless( joy.pointer.nil? )
      SDL.JoystickClose( joy )
    end
  end

  return nil
end

.get_name(index) ⇒ Object

Returns the name of Nth joystick on the system. The name is implementation-dependent. See also #name.



68
69
70
 
# File 'lib/rubygame/joystick.rb', line 68

def self.get_name( index )
  SDL.JoystickName( index )
end

.num_joysticks ⇒ Object

Returns the total number of joysticks detected on the system.



60
61
62
 
# File 'lib/rubygame/joystick.rb', line 60

def self.num_joysticks
  SDL.NumJoysticks()
end

Instance Method Details

#axes ⇒ Object

Returns the number of axes (singular: axis) featured on the Joystick. Each control stick generally has two axes (X and Y), although there are other types of controls which are represented as one or more axes.



153
154
155
 
# File 'lib/rubygame/joystick.rb', line 153

def axes
  SDL.JoystickNumAxes( @struct )
end

#balls ⇒ Object

Returns the number of trackballs featured on the Joystick. A trackball is usually a small sphere which can be rotated in-place in any direction, registering relative movement along two axes.



162
163
164
 
# File 'lib/rubygame/joystick.rb', line 162

def balls
  SDL.JoystickNumBalls( @struct )
end

#buttons ⇒ Object

Returns the number of buttons featured on the Joystick. A button can be in one of two states: neutral, or pushed.



179
180
181
 
# File 'lib/rubygame/joystick.rb', line 179

def buttons
  SDL.JoystickNumButtons( @struct )
end

#hats ⇒ Object

Returns the number of hats featured on the Joystick. A hat is a switch which can be pushed in one of several directions, or centered.



171
172
173
 
# File 'lib/rubygame/joystick.rb', line 171

def hats
  SDL.JoystickNumHats( @struct )
end

#index ⇒ Object

Returns the index number of the Joystick, i.e. the identifier number of the joystick that this interface controls. This is the same number that was given to Joystick.new.



135
136
137
 
# File 'lib/rubygame/joystick.rb', line 135

def index
  SDL.JoystickIndex( @struct )
end

#name ⇒ Object

Returns a String containing the name of the Joystick. The name is implementation-dependent. See also Joystick.get_name.



143
144
145
 
# File 'lib/rubygame/joystick.rb', line 143

def name
  SDL.JoystickName( self.index )
end