Initializes the BJoystick object so that all values are set to 0. Before using the object, you must call Open() to open a particular joystick port. For the object to register any meaningful values, you must call Update() to query the open port.

Closes the port, if it was not closed already.

CountAxes() returns the number of axes on the opened game port.

GetAxisValues() fills the array pointed to by outValues with the values of all the axes connected to the specified joystick. The forStick parameter lets you choose which joystick on the game port to read the values from (the default is to read from the first stick on the port).

The returned values range from -32,768 to 32,767.

The array outValues must be large enough to contain the values for all the axes. You can ensure that this is the case by using the following code:

int16* axes;

axes = (int16*) malloc(sizeof(int16) * stick->CountAxes());
stick->GetAxisValues(axes);

CountButtons() returns the number of buttons on the opened game port.

ButtonValues() returns a 32-bit number in which each bit represents the state of one button. The forStick parameter lets you choose which joystick on the game port to read the values from (the default is to read from the first stick on the port). You can deterimine if a particular button is down by using the following code:

uint32 buttonValues = stick->ButtonValues();

if (buttonValues & (1 << whichButton)) {
   /* button number whichButton is pressed */
}

CountDevices() returns the number of game ports on the computer.

GetDeviceName() returns the name of the device specified by the given index. The buffer pointed to by outName is filled with the device name; bufSize indicates the size of the buffer.

The names returned by GetDeviceName() can be passed into the Open() function to open a device.

Note

The BJoystick doesn't need to have an open device before you use these functions; in fact, your application will typically use these to provide user interface allowing the user to choose the joystick device they'd like to use.

CountHats() returns the number of hats on the opened game port.

GetHatValues() fills the array pointed to by outHats with the values of all the hats connected to the specified joystick. The forStick parameter lets you choose which joystick on the game port to read the values from (the default is to read from the first stick on the port).

The return value means the following:

The array outHats must be large enough to contain the values for all the hats. You can ensure that this is the case by using the following code:

int8* hats;

hats = (int8*) malloc(sizeof(int8) * stick->CountAxes());
stick->GetHatValues(hats);

Returns the number of joysticks connected to the opened game port.

Returns the name of the control specified by the given index. The BString object pointed to by outName is set to the control's name.

GetAxisNameAt() returns the specified axis' name, GetHatNameAt() returns the specified hat's name, and GetButtonNameAt() returns the specified button's name.

GetControllerModule() returns the name of the joystick module that represents the opened joystick device. If the device isn't in enhanced mode, this always returns "Legacy".

GetControllerName() returns the name of the joystick that's been configured for the opened device. This is the same string that appears in the Joysticks preference application. The returned string is always "2-axis" if the device isn't in enhanced mode.

Switches the device into enhanced mode. If ref isn't NULL, it's treated as a reference to a joystick description file (such as those in /boot/beos/etc/joysticks). If ref is NULL, the currently-configured joystick settings (as per the Joysticks preference application) are used.

If enhanced mode is entered successfully (or the device is already in enhanced mode), true is returned. Otherwise, EnterEnhancedMode() returns false.

IsCalibrationEnabled() returns true if axis values returned by the joystick will be calibrated automatically into the range -32,768 to 32,767, or false if the raw values will be returned.

EnableCalibration() enables or disables automatic calibration for the joystick's axes. Specify a value of true for calibrates to enable calibration; otherwise, specify false.

Note

The Joysticks preference application lets the user calibrate the joystick. Calibration is enabled by default.

These functions open the joystick port specified by devName and close it again. The devName should be the name of a game port device. The easiest way to determine valid device names is by using the CountDevices() and GetDeviceName() functions.

If it's able to open the port, Open() returns a positive integer. If unable or if the devName isn't valid, it returns B_ERROR. If the devName port is already open, Open() tries to close it first, then open it again.

By default, Open() opens the device in enhanced mode. If you want to use the old, unenhanced mode, you can use the second form of Open() to specify whether or not you want to use enhanced mode; set enterEnhanced to true to use enhanced mode; specify false if you don't want enhanced mode.

Note

Even in enhanced mode, the classic BJoystick data members are valid (for compatibility with older applications). However, they only give you access to the first two axes and buttons of the joystick.

To be able to obtain joystick data, a BJoystick object must have a port open.

Specifies the maximum latency to allow when accessing the joystick. Returns B_OK if the change is applied successfully, otherwise returns an error code.

Updates the data members of the object so that they reflect the current state of the joystick. An application would typically call Update() periodically to poll the condition of the device, then read the values of the data members, or—if in enhanced mode—call the various functions for obtaining joystick state information.

This function returns B_ERROR if the BJoystick object doesn't have a port open, and B_OK if it does.