Platform SDK: DirectX |
The cooperative level of a device determines how the input is shared with other applications and with the Windows system. You set it by using the IDirectInputDevice7::SetCooperativeLevel method, as in the following code example:
/* hwnd is the top-level window handle. */ lpdiDevice->SetCooperativeLevel(hwnd, DISCL_NONEXCLUSIVE | DISCL_FOREGROUND)
The parameters are the handle to the top-level window associated with the device (generally the application window) and one or more flags.
The cooperative level of a device determines how the input is shared with other applications and with the Windows system. You set it by using the DirectInputDevice.SetCooperativeLevel method, as in the following code example:
diDevice.SetCooperativeLevel(hWnd, DISCL_NONEXCLUSIVE Or DISCL_FOREGROUND)
The parameters are the handle to the top-level window associated with the device (generally the application window) and one or more flags. The hWnd property of a form does not become valid until the form is shown. If you are initializing the DirectInput device in the Load method of the application's main form, you must call Show before attempting to set the cooperative level.
Note Although DirectInput provides a default setting, you should still explicitly set the cooperative level because this is the only way to give DirectInput the window handle. Without this handle, DirectInput cannot react to situations that involve window messages, such as joystick recalibration.
The valid flag combinations are shown in the following table:
Flags | Notes |
---|---|
DISCL_NONEXCLUSIVE DISCL_BACKGROUND |
The default setting |
DISCL_NONEXCLUSIVE DISCL_FOREGROUND |
|
DISCL_EXCLUSIVE DISCL_FOREGROUND |
|
DISCL_EXCLUSIVE DISCL_BACKGROUND |
Not valid for keyboard or mouse |
For the keyboard, you can also include DISCL_NOWINKEY in combination with DISCL_NONEXCLUSIVE. This flag disables the Windows key so that users cannot inadvertently break out of the application. In exclusive mode, the Windows key is always disabled.
The cooperative level has two main components: whether the device is being used in the foreground or the background, and whether it is being used exclusively or nonexclusively.
A foreground cooperative level means that the input device is available only when the application is in the foreground or, in other words, has the input focus. If the application moves to the background, the device is automatically unacquired, or made unavailable.
A background cooperative level really means foreground and background. A device with a background cooperative level can be acquired and used by an application at any time.
You will usually want to have foreground access only, since most applications are not interested in input that takes place when another program is in the foreground.
While developing an application, it is useful to employ conditional compilation so that the background cooperative level is always set for debugging. This prevents your application from losing access to the device every time that it moves to the background as you switch to the debugging environment.
The fact that your application is using a device at the exclusive level does not mean that other applications cannot get data from the device. However, it does mean that no other application can also acquire the device exclusively.
Take the example of a music player that accepts input from a hand-held remote-control device, even when the application is running in the background. If you run a similar application that plays movies in response to signals from the same remote control, what happens when the user presses Play? Both programs start playing, which is probably not what the user wants. To prevent this from happening, each application should have the DISCL_EXCLUSIVE flag set so that only one of them can be running at a time.
To use force-feedback effects, an application must have exclusive access to the device.
Windows itself requires exclusive access to the mouse because mouse events such as a click on an inactive window could force an application to unacquire the device, with potentially harmful results, such as a loss of data from the input buffer. Therefore, when an application has exclusive access to the mouse, Windows is not allowed any access at all. No mouse messages are generated. A further side effect is that the cursor disappears.
When an application has exclusive access to the keyboard, DirectInput suppresses all keyboard messages except CTRL+ALT+DEL and, on Windows 95 and Windows 98, ALT+TAB.