DirectInputDevice8.SetProperty

Sets properties that define the device behavior.

object.SetProperty( _ 
  guid As String, _ 
  propertyInfo As Any)

Parts

object

Resolves to a DirectInputDevice8 object.

guid

Identifier of the property to be set. The following property values are predefined for an input device and can be passed as strings:

DIPROP_APPDATA

Sets the application-defined value associated with an in-game action, as a DIPROPPOINTER.

DIPROP_AUTOCENTER

Specifies whether device objects are self-centering. This setting applies to the entire device, rather than to any particular object, so the lHow member of the associated DIPROPLONG type must be DIPH_DEVICE.

The lData member can be one of the following values from the CONST_DINPUT enumeration.

DIPROPAUTOCENTER_OFF: The device should not automatically center when the user releases the device. An application that uses force feedback should disable autocentering before playing effects.

DIPROPAUTOCENTER_ON: The device should automatically center when the user releases the device.

Not all devices support the autocenter property.

DIPROP_AXISMODE

Sets the axis mode. The value being set (either DIPROPAXISMODE_ABS or DIPROPAXISMODE_REL from the CONST_DINPUT enumeration) must be specified in the lData member of the associated DIPROPLONG type.

This setting applies to the entire device, so the lHow member of the DIPROPLONG type must be set to DIPH_DEVICE.

DIPROP_BUFFERSIZE

Sets the input-buffer size. See Remarks.

This setting applies to the entire device, so the lHow member of the associated DIPROPLONG type must be set to DIPH_DEVICE.

DIPROP_CALIBRATIONMODE

Enables the application to specify whether Microsoft® DirectInput® should retrieve calibrated or uncalibrated data from an axis. By default, DirectInput retrieves calibrated data.

Setting the calibration mode for the entire device is equivalent to setting it for each axis individually.

The lData member of the DIPROPLONG type may be one of the following values:

DIPROPCALIBRATIONMODE_COOKED: DirectInput should return data after applying calibration information. This is the default mode.

DIPROPCALIBRATIONMODE_RAW: DirectInput should return raw, uncalibrated data. This mode is typically used only by Control Panel–type applications.

Note that setting a device into raw mode causes the dead zone, saturation, and range settings to be ignored.

DIPROP_CPOINTS

Retrieves calibration points used for the adjustment of incoming raw data as a DIPROPCPOINTS structure.

DIPROP_DEADZONE

Sets the value for the dead zone of a joystick, in the range 0 to 10,000, where 0 indicates there is no dead zone, 5,000 indicates that the dead zone extends over 50 percent of the physical range of the axis on both sides of center, and 10,000 indicates that the entire physical range of the axis is dead. When the axis is within the dead zone, it is reported as being at the center of its range.

This setting can be applied to either the entire device or to a specific axis.

DIPROP_FFGAIN

Sets the gain for the device. This setting applies to the entire device, rather than to any particular object, so the lHow member of the associated DIPROPLONG type must be DIPH_DEVICE.

The lData member contains a gain value that is applied to all effects created on the device. The value is an integer in the range from 0 through 10,000, and specifies the amount by which effect magnitudes are scaled for the device. For example, a value of 10,000 indicates that you should take all effect magnitudes at face value. A value of 9,000 indicates that you should reduce all effect magnitudes to 90% of their nominal magnitudes.

Setting a gain value is useful when an application wants to scale down the strength of all force-feedback effects uniformly, based on user preferences.

Unlike other properties, the gain can be set when the device is in an acquired state.

DIPROP_INSTANCENAME

This property exists for advanced applications that want to change the friendly instance name of a device (as returned by GetInstanceName) to distinguish it from similar devices that are plugged in simultaneously. Most applications should not need to change the friendly name.

This setting applies to the entire device, so the lHow member of the associated DIPROPSTRING type must be set to DIPH_DEVICE.

The PropString member is a string that specifies the new friendly instance name for the device.

DIPROP_PRODUCTNAME

This property exists for advanced applications that want to change the friendly product name of a device (as returned by GetProductName) to distinguish it from similar devices which are plugged in simultaneously. Most applications should have no need to change the friendly name.

This setting applies to the entire device, so the lHow member of the associated DIPROPSTRING type must be set to DIPH_DEVICE.

The PropString member is a string that specifies the new friendly product name for the device.

DIPROP_RANGE

Sets the range of values an object can possibly report. The minimum and maximum values are taken from the lMin and lMax members of the associated DIPROPRANGE type.

For some devices, this is a read-only property.

You cannot set a reverse range; lMax must be greater than lMin.

DIPROP_SATURATION

Sets the value for the saturation zones of a joystick, in the range 0 to 10,000. The saturation level is the point at which the axis is considered to be at its most extreme position. For example, if the saturation level is set to 9,500, then the axis reaches the extreme of its range when it has moved 95 percent of the physical distance from its center position (or from the dead zone).

This setting can be applied to either the entire device or to a specific axis.

propertyInfo

A DIPROPLONG type containing data for properties that take a single value, a DIPROPRANGE type containing data for properties that take a pair of values, or a DIPROPSTRING type containing data for properties that take a string.

Error Codes

If the method fails, an error is raised and Err.Number may be one of the following error codes.

Remarks

The buffer size determines the amount of data that the buffer can hold between calls to the DirectInputDevice8.GetDeviceData method before data is lost. This value may be set to 0 to indicate that the application will not be reading buffered data from the device. If the buffer size in the lData member of the DIPROPLONG type is too large to be supported by the device, the largest possible buffer size is set. To determine whether the requested buffer size was set, retrieve the buffer-size property and compare the result with the value you previously attempted to set.

See Also

DirectInputDevice8.GetProperty