Tao.Platform.Windows SDK Documentation

User.ChangeDisplaySettings Method (IntPtr, Int32)

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.

[Visual Basic]
Overloads Public Shared Function ChangeDisplaySettings( _
   ByVal devMode As IntPtr, _
   ByVal flags As Integer _
) As Integer
[C#]
public static int ChangeDisplaySettings(
   IntPtr devMode,
   int flags
);

Parameters

devMode

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.

flags

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.

Return Value

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.

Remarks

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.

See Also

User Class | Tao.Platform.Windows Namespace | User.ChangeDisplaySettings Overload List | Gdi.DEVMODE | EnumDisplaySettings