ChangeDisplaySettingsA 函数 (winuser.h)

项目
03/13/2024

ChangeDisplaySettings 函数将默认显示设备的设置更改为指定的图形模式。

若要更改指定显示设备的设置，请使用 ChangeDisplaySettingsEx 函数。

注意设计为面向Windows 8及更高版本的应用无法再查询或设置每像素小于 32 位 (bpp) 的显示模式;这些操作将失败。这些应用具有面向Windows 8的兼容性清单。 Windows 8仍支持在没有Windows 8清单的情况下生成的桌面应用的 8 位和 16 位颜色模式;Windows 8模拟这些模式，但仍在 32 位颜色模式下运行。

语法

LONG ChangeDisplaySettingsA(
  [in] DEVMODEA *lpDevMode,
  [in] DWORD    dwFlags
);

参数

[in] lpDevMode

指向描述新图形模式的 DEVMODE 结构的指针。如果 lpDevMode 为 NULL，注册表中当前的所有值都将用于显示设置。在动态模式更改后，为 lpDevMode 参数传递 NULL，为 dwFlags 参数传递 0 是返回到默认模式的最简单方法。

DEVMODE 的 dmSize 成员必须初始化为 DEVMODE 结构的大小（以字节为单位）。必须初始化 DEVMODE 的 dmDriverExtra 成员，以指示 DEVMODE 结构后面的专用驱动程序数据的字节数。此外，还可以使用 DEVMODE 结构的以下任意或全部成员。

成员	含义
dmBitsPerPel	每像素位数
dmPelsWidth	像素宽度
dmPelsHeight	像素高度
dmDisplayFlags	模式标志
dmDisplayFrequency	模式频率
dmPosition	设备在多监视器配置中的位置。

除了使用上述一个或多个 DEVMODE 成员外，还必须在 dmFields 成员中设置以下一个或多个值以更改显示设置。

值	含义
DM_BITSPERPEL	使用 dmBitsPerPel 值。
DM_PELSWIDTH	使用 dmPelsWidth 值。
DM_PELSHEIGHT	使用 dmPelsHeight 值。
DM_DISPLAYFLAGS	使用 dmDisplayFlags 值。
DM_DISPLAYFREQUENCY	使用 dmDisplayFrequency 值。
DM_POSITION	使用 dmPosition 值。

[in] dwFlags

指示应如何更改图形模式。此参数的取值可为下列值之一：

值	含义
0	当前屏幕的图形模式将动态更改。
CDS_FULLSCREEN	该模式本质上是临时的。如果你从另一个桌面切换到和从另一个桌面更改，则不会重置此模式。
CDS_GLOBAL	设置将保存在全局设置区域中，以便它们会影响计算机上的所有用户。否则，仅修改用户的设置。仅当使用 CDS_UPDATEREGISTRY 标志指定时，此标志才有效。
CDS_NORESET	设置将保存在注册表中，但不会生效。仅当使用 CDS_UPDATEREGISTRY 标志指定时，此标志才有效。
CDS_RESET	应更改设置，即使请求的设置与当前设置相同。
CDS_SET_PRIMARY	此设备将成为主设备。
CDS_TEST	系统测试是否可以设置请求的图形模式。
CDS_UPDATEREGISTRY	当前屏幕的图形模式将动态更改，图形模式将在注册表中更新。模式信息存储在用户配置文件中。

指定CDS_TEST允许应用程序确定哪些图形模式实际有效，而不会导致系统更改为该图形模式。

如果指定了CDS_UPDATEREGISTRY并且可以动态更改图形模式，则会将信息存储在注册表中，并返回DISP_CHANGE_SUCCESSFUL。如果无法动态更改图形模式，则会将信息存储在注册表中，并返回DISP_CHANGE_RESTART。

如果指定了CDS_UPDATEREGISTRY，并且无法将信息存储在注册表中，则不会更改图形模式并返回DISP_CHANGE_NOTUPDATED。

返回值

ChangeDisplaySettings 函数返回以下值之一。

返回代码	说明
DISP_CHANGE_SUCCESSFUL	设置更改成功。
DISP_CHANGE_BADDUALVIEW	设置更改失败，因为系统支持 DualView。
DISP_CHANGE_BADFLAGS	传入了一组无效的标志。
DISP_CHANGE_BADMODE	不支持图形模式。
DISP_CHANGE_BADPARAM	传入了无效参数。这可以包括无效标志或标志组合。
DISP_CHANGE_FAILED	显示驱动程序未通过指定的图形模式。
DISP_CHANGE_NOTUPDATED	无法将设置写入注册表。
DISP_CHANGE_RESTART	必须重启计算机才能使图形模式正常工作。

注解

若要确保传递给 ChangeDisplaySettings 的DEVMODE 结构有效且仅包含显示驱动程序支持的值，请使用 EnumDisplaySettings 函数返回的 DEVMODE。

动态更改显示模式时， WM_DISPLAYCHANGE 消息将发送到具有以下消息参数的所有正在运行的应用程序。

参数	含义
wParam	每个像素的新位数
LOWORD(lParam)	新的像素宽度
HIWORD(lParam)	新的像素高度

DPI 虚拟化

此 API 不参与 DPI 虚拟化。给定的输入始终以物理像素为单位，与调用上下文无关。

注意

winuser.h 标头将 ChangeDisplaySettings 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winuser.h (包括 Windows.h)
Library	User32.lib
DLL	User32.dll
API 集	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (在 Windows 10 版本 10.0.14393 中引入)