The ChangeDisplaySettings function changes the settings of the default display device to the specified graphics mode.
To change the settings of a specified display device, use the ChangeDisplaySettingsEx function.
Pointer to a Gdi.DEVMODE structure that describes the new graphics mode. If devMode is NULL, all the values currently in the registry will be used for the display setting. Passing NULL for the devMode parameter and 0 for the flags parameter is the easiest way to return to the default mode after a dynamic mode change.
The dmSize member of Gdi.DEVMODE must be initialized to the size, in bytes, of the Gdi.DEVMODE structure. The dmDriverExtra member of Gdi.DEVMODE must be initialized to indicate the number of bytes of private driver data following the Gdi.DEVMODE structure. In addition, you can use any or all of the following members of the Gdi.DEVMODE structure:
Value | Description |
---|---|
dmBitsPerPel | Bits per pixel. |
dmPelsWidth | Pixel width. |
dmPelsHeight | Pixel height. |
dmDisplayFlags | Mode flags. |
dmDisplayFrequency | Mode frequency. |
dmPosition | Windows 98/Me, Windows 2000/XP: Position of the device in a multimonitor configuration. |
In addition to using one or more of the preceding Gdi.DEVMODE members, you must also set one or more of the following values in the dmFields member to change the display setting:
Value | Description |
---|---|
DM_BITSPERPEL | Use the dmBitsPerPel value. |
DM_PELSWIDTH | Use the dmPelsWidth value. |
DM_PELSHEIGHT | Use the dmPelsHeight value. |
DM_DISPLAYFLAGS | Use the dmDisplayFlags value. |
DM_DISPLAYFREQUENCY | Use the dmDisplayFrequency value. |
see cref="Gdi.DM_POSITION" | Windows 98/Me, Windows 2000/XP: Use the dmPosition value. |
Indicates how the graphics mode should be changed. This parameter can be one of the following values:
Value | Description |
---|---|
0 | The graphics mode for the current screen will be changed dynamically. |
see cref="Gdi.CDS_FULLSCREEN" |
The mode is temporary in nature. Windows NT/2000/XP: If you change to and from another desktop, this mode will not be reset. |
see cref="Gdi.CDS_GLOBAL" | The settings will be saved in the global settings area so that they will affect all users on the machine. Otherwise, only the settings for the user are modified. This flag is only valid when specified with the see cref="Gdi.CDS_UPDATEREGISTRY" flag. |
see cref="Gdi.CDS_NORESET" | The settings will be saved in the registry, but will not take affect. This flag is only valid when specified with the see cref="Gdi.CDS_UPDATEREGISTRY" flag. |
see cref="Gdi.CDS_RESET" | The settings should be changed, even if the requested settings are the same as the current settings. |
see cref="Gdi.CDS_SET_PRIMARY" | This device will become the primary device. |
see cref="Gdi.CDS_TEST" | The system tests if the requested graphics mode could be set. |
see cref="Gdi.CDS_UPDATEREGISTRY" | The graphics mode for the current screen will be changed dynamically and the graphics mode will be updated in the registry. The mode information is stored in the USER profile. |
Specifying see cref="Gdi.CDS_TEST" allows an application to determine which graphics modes are actually valid, without causing the system to change to that graphics mode.
If see cref="Gdi.CDS_UPDATEREGISTRY" is specified and it is possible to change the graphics mode dynamically, the information is stored in the registry and see cref="Gdi.DISP_CHANGE_SUCCESSFUL" is returned. If it is not possible to change the graphics mode dynamically, the information is stored in the registry and see cref="Gdi.DISP_CHANGE_RESTART" is returned.
Windows NT/2000/XP: If see cref="Gdi.CDS_UPDATEREGISTRY" is specified and the information could not be stored in the registry, the graphics mode is not changed and see cref="Gdi.DISP_CHANGE_NOTUPDATED" is returned.
The ChangeDisplaySettings function returns one of the following values:
Value | Description |
---|---|
see cref="Gdi.DISP_CHANGE_SUCCESSFUL" | The settings change was successful. |
see cref="Gdi.DISP_CHANGE_BADDUALVIEW" | Windows XP: The settings change was unsuccessful because system is DualView capable. |
see cref="Gdi.DISP_CHANGE_BADFLAGS" | An invalid set of flags was passed in. |
see cref="Gdi.DISP_CHANGE_BADMODE" | The graphics mode is not supported. |
see cref="Gdi.DISP_CHANGE_BADPARAM" | An invalid parameter was passed in. This can include an invalid flag or combination of flags. |
see cref="Gdi.DISP_CHANGE_FAILED" | The display driver failed the specified graphics mode. |
see cref="Gdi.DISP_CHANGE_NOTUPDATED" | Windows NT/2000/XP: Unable to write settings to the registry. |
see cref="Gdi.DISP_CHANGE_RESTART" | The computer must be restarted in order for the graphics mode to work. |
To ensure that the Gdi.DEVMODE structure passed to ChangeDisplaySettings is valid and contains only values supported by the display driver, use the Gdi.DEVMODE returned by the EnumDisplaySettings function.
When the display mode is changed dynamically, the WM_DISPLAYCHANGE message is sent to all running applications with the following message parameters:
Value | Description |
---|---|
wParam | New bits per pixel. |
LOWORD(lParam) | New pixel width. |
HIWORD(lParam) | New pixel height. |
Windows 95/98/Me: If the calling thread has any windows, ChangeDisplaySettings sends them the WM_DISPLAYCHANGE message immediately (for windows in all other threads, the message is sent when the thread can receive nonqueued messages). This may cause the shell to get its message too soon and could squash icons. To avoid this problem, have ChangeDisplaySettings do resolution switching by calling on a thread with no windows, for example, a new thread.
User Class | Tao.Platform.Windows Namespace | User.ChangeDisplaySettings Overload List | Gdi.DEVMODE | EnumDisplaySettings