| Microsoft DirectX 8.1 (C++) |
IDirectInputDevice8::SetActionMap
Sets the data format for a device and maps application-defined actions to device objects. It also sets the buffer size for buffered data.
Note The device must be unacquired prior to calling this method.
HRESULT SetActionMap( LPCDIACTIONFORMAT lpdiActionFormat, LPCTSTR lptszUserName, DWORD dwFlags );
Parameters
- lpdiActionFormat
- Address of a DIACTIONFORMAT structure containing information about the action map to be applied.
- lptszUserName
- Unicode string that specifies the name of the user for which the action map is being set. A value of NULL specifies the user currently logged into the system.
- dwFlags
- DWORD value that specifies how the action map is applied. This can be one of the following values.
- DIDSAM_DEFAULT
- Set the action map for this user. If the map differs from the current map, the new settings are saved to disk.
- DIDSAM_FORCESAVE
- Always save the configuration to disk.
- DIDSAM_NOUSER
- Reset user ownership for this device in the default configuration property sheet. Resetting user ownership does not remove the current action map.
Return Values
If the method succeeds, the return value can be one of the following error values:
| DI_OK |
| DI_SETTINGSNOTSAVED |
| DI_WRITEPROTECT |
If the method fails, the return value can be one of the following error values.
| DIERR_ACQUIRED |
| DIERR_INVALIDPARAM |
Remarks
This method provides the mechanism to change action-to-control mapping from the device defaults. An application must use this method to map its in-game actions to virtual controls.
The user name passed to this method binds a set of action mappings for a device to a specific user. Settings are automatically saved to disk when they differ from the currently applied map. Applications that accept input from multiple users should be very careful when applying action maps to the system mouse or keyboard, as the action maps for each user may conflict.
The method can be called only when the device is not acquired.
Requirements
Windows NT/2000/XP: Requires Windows® 2000.
Windows 98/Me: Requires Windows 98 or later. Available as a redistributable for Windows 98.
Header: Declared in Dinput.h.