ChangeDisplaySettingsExA 函数 (winuser.h)

项目
03/13/2024

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

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

语法

LONG ChangeDisplaySettingsExA(
  [in] LPCSTR   lpszDeviceName,
  [in] DEVMODEA *lpDevMode,
       HWND     hwnd,
  [in] DWORD    dwflags,
  [in] LPVOID   lParam
);

参数

[in] lpszDeviceName

指向以 null 结尾的字符串的指针，该字符串指定其图形模式将更改的显示设备。仅显示 EnumDisplayDevices 返回的设备名称有效。有关与这些显示设备关联的名称的详细信息，请参阅 EnumDisplayDevices 。

lpszDeviceName 参数可以为 NULL。 NULL 值指定默认显示设备。可以通过调用 EnumDisplayDevices 并检查DISPLAY_DEVICE_PRIMARY_DEVICE标志来确定默认设备。

[in] lpDevMode

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

dmSize 成员必须初始化为 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 值。

hwnd

保留;必须为 NULL。

[in] dwflags

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

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

通过指定CDS_TEST，应用程序可以确定哪些图形模式实际有效，而不会导致系统更改这些模式。

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

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

[in] lParam

如果 dwFlags为CDS_VIDEOPARAMETERS， 则 lParam 是指向 VIDEOPARAMETERS 结构的指针。否则 ，lParam 必须为 NULL。

返回值

ChangeDisplaySettingsEx 函数返回以下值之一。

返回代码	说明
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	必须重启计算机才能使图形模式正常工作。

注解

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

以编程方式将显示监视器添加到多监视器系统时，请将 DEVMODE.dmFields 设置为DM_POSITION，并在 DEVMODE.dmPosition) 为要添加的监视器指定一个 (位置，该位置与现有监视器的显示区域至少一个像素相邻。若要分离监视器，请将 DEVMODE.dmFields 设置为 DM_POSITION但将 DEVMODE.dmPelsWidth 和 DEVMODE.dmPelsHeight 设置为零。有关详细信息，请参阅多个显示监视器。

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

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

若要同时更改多个显示器的设置，请首先为每个设备单独调用 ChangeDisplaySettingsEx 以更新注册表，而无需应用更改。然后使用 NULL 设备再次调用 ChangeDisplaySettingsEx 以应用更改。例如，若要更改两个显示器的设置，请执行以下操作：


ChangeDisplaySettingsEx (lpszDeviceName1, lpDevMode1, NULL, (CDS_UPDATEREGISTRY | CDS_NORESET), NULL);
ChangeDisplaySettingsEx (lpszDeviceName2, lpDevMode2, NULL, (CDS_UPDATEREGISTRY | CDS_NORESET), NULL);
ChangeDisplaySettingsEx (NULL, NULL, NULL, 0, NULL);

DPI 虚拟化

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

注意

winuser.h 标头将 ChangeDisplaySettingsEx 定义为别名，该别名根据 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 中引入)