Qaf Framework: qaf::Joystick Class Reference

Most methods expect a JoystickObject code as a parameter. See the enumerated type definition in qafJoystickSystem.h for its possible values.

If any errors are encountered during the execution of this class's methods, they will be reported in the HGE log file.


Public Member Functions
	Joystick (LPDIRECTINPUTDEVICE8 pJoystick, HWND hWindow)
	For internal use only.
bool	isInitialized ()
	For internal use only.
bool	poll ()
	For internal use only. This method must be called every frame to update the joystick's state.
int	getObjectState (JoystickObject obj)
	Returns a number representing the specified object's state.
const char *	getObjectName (JoystickObject obj)
	Returns a pointer to an internal string, containing the object's description.
const char *	getDeviceName ()
	Returns: This joystick's name.
bool	setHWND (HWND hWindow)
	For internal use only. Changes this joystick's target window.
bool	setAxesParameters (bool absolute, int minValue, int maxValue, float deadZone, float saturation)
	Sets the axes' parameters.
int	createVibrationEffect (float magnitude, float duration, float period)
	Creates a periodic force-feedback effect if the device supports it.
bool	changeVibrationMagnitude (int effectID, float newMagnitude, float newPeriod)
	Changes the vibration's magnitude of the effect specified by `effectID`.
bool	deleteEffect (int effectID)
	Unloads and deletes the effect specified by `effectID`.
bool	playEffect (int effectID, int repetitions)
	Starts the effect specified by `effectID`.

Constructor & Destructor Documentation

qaf::Joystick::Joystick	(	LPDIRECTINPUTDEVICE8	pJoystick,
		HWND	hWindow
	)

For internal use only.

Parameters:

	pJoystick	A pointer to the joystick interface.
	hWindow	The window handle to which this device will be attached.

Member Function Documentation

bool qaf::Joystick::isInitialized ( )

For internal use only.

Returns:: true if the device was successfully initialized.

bool qaf::Joystick::poll ( )

For internal use only.

This method must be called every frame to update the joystick's state.

This is the Environment's task; users need not and should not invoke this method directly.

Returns:: false if the device could not be read. This could happen if the window has lost focus, or the joystick was disconnected.

int qaf::Joystick::getObjectState ( JoystickObject obj )

Returns a number representing the specified object's state.

The semantics of that value depend on the type of object read:

Axes and sliders: An integer number between the axis' minimum and maximum values. (See the setAxesParameters() method).
POV hats: The position is indicated in hundredths of a degree clockwise from north (away from the user). The center position is reported as -1. For indicators that have only five positions, the value for a controller is -1 (center), 0 (north), 9000 (east), 18000 (south), or 27000 (west). Warning: This differs slightly from DirectInput's default.
Buttons: A non-zero value is returned if the button is pressed (usually 128); otherwise, zero is returned.

const char* qaf::Joystick::getObjectName ( JoystickObject obj )

Returns a pointer to an internal string, containing the object's description.

Returns:: NULL if the object does not exist on the joystick.

const char* qaf::Joystick::getDeviceName ( )

Returns:: This joystick's name.

The string is statically allocated and should not be changed or freed.

bool qaf::Joystick::setHWND ( HWND hWindow )

For internal use only.

Changes this joystick's target window.

Returns:: false if the change was not successful.

bool qaf::Joystick::setAxesParameters	(	bool	absolute,
		int	minValue,
		int	maxValue,
		float	deadZone,
		float	saturation
	)

Sets the axes' parameters.

Parameters:

	absolute	If set to false, the axes' data will be returned in relation to the last frame. Default: true
	minValue	The axes' minimum value (e.g., the number returned when the X-axis is all the way to the left). Default: -1000
	maxValue	The axes' maximum value (e.g., the number returned when the X-axis is all the way to the right). Default: +1000
	deadZone	A percentage value (range [0, 1]), indicating the area at the axes' center where movement should be considered zero. Default: 0.1
	saturation	A percentage value (range [0, 1]), indicating the area at the axes' outer edge where movement should be considered at its maximum. Default: 1.0

Returns:: false if the change was not successful. Note that some of the axes might have been changed if that occurs.

int qaf::Joystick::createVibrationEffect	(	float	magnitude,
		float	duration,
		float	period
	)

Creates a periodic force-feedback effect if the device supports it.

Parameters:

	magnitude	A number contained in the interval [0, 1], where 0 represents no force and 1 represents the device's maximum force.
	duration	Duration of the vibration, in seconds.
	period	This parameter specifies the period of the effect's vibration.

Returns:: The effect ID, which can be used for playback later, or -1 if the effect could not be created.

See also:: playEffect(), changeVibrationMagnitude(), deleteEffect()

bool qaf::Joystick::changeVibrationMagnitude	(	int	effectID,
		float	newMagnitude,
		float	newPeriod
	)

Changes the vibration's magnitude of the effect specified by effectID.

It may be possible to change the effect's parameters as it is playing, depending on the device.

Returns:: false if the operation was not successful.

See also:: createVibrationEffect(), playEffect()

bool qaf::Joystick::deleteEffect ( int effectID )

Unloads and deletes the effect specified by effectID.

Returns:: false if the operation was not successful.

See also:: createVibrationEffect()

bool qaf::Joystick::playEffect	(	int	effectID,
		int	repetitions
	)

Starts the effect specified by effectID.

Returns:: false if the operation was not successful.

See also:: createVibrationEffect(), changeVibrationMagnitude()

qaf::Joystick Class Reference

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation