Class Rubygame::Joystick
In: lib/rubygame/joystick.rb
Parent: Object

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:

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

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

Methods

activate_all   axes   balls   buttons   deactivate_all   get_name   hats   index   name   new   num_joysticks  

Public Class methods

activate_all()

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.

[Source]

# 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()

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

[Source]

# 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 )

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

[Source]

# File lib/rubygame/joystick.rb, line 68
  def self.get_name( index )
    SDL.JoystickName( index )
  end
new( index )

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

[Source]

# 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
num_joysticks()

Returns the total number of joysticks detected on the system.

[Source]

# File lib/rubygame/joystick.rb, line 60
  def self.num_joysticks
    SDL.NumJoysticks()
  end

Public Instance methods

axes()

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.

[Source]

# File lib/rubygame/joystick.rb, line 153
  def axes
    SDL.JoystickNumAxes( @struct )
  end
balls()

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.

[Source]

# File lib/rubygame/joystick.rb, line 162
  def balls
    SDL.JoystickNumBalls( @struct )
  end
buttons()

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

[Source]

# File lib/rubygame/joystick.rb, line 179
  def buttons
    SDL.JoystickNumButtons( @struct )
  end
hats()

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.

[Source]

# File lib/rubygame/joystick.rb, line 171
  def hats
    SDL.JoystickNumHats( @struct )
  end
index()

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.

[Source]

# File lib/rubygame/joystick.rb, line 135
  def index
    SDL.JoystickIndex( @struct )
  end
name()

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

[Source]

# File lib/rubygame/joystick.rb, line 143
  def name
    SDL.JoystickName( self.index )
  end

[Validate]