Функция ChangeDisplaySettingsA (winuser.h)

Статья
11/20/2024

Функция ChangeDisplaySettings изменяет параметры устройства отображения по умолчанию на указанный графический режим.

Чтобы изменить параметры указанного устройства отображения, используйте функцию ChangeDisplaySettingsEx.

Примечание Приложения, которые вы разрабатываете для Windows 8 и более поздних версий, больше не могут запрашивать или устанавливать режимы отображения, которые меньше 32 бит на пиксель (bpp); Эти операции завершаются ошибкой. Эти приложения имеют манифест совместимости , предназначенный для Windows 8. Windows 8 по-прежнему поддерживает 8-разрядные и 16-разрядные режимы цветов для классических приложений, созданных без манифеста Windows 8; Windows 8 эмулирует эти режимы, но по-прежнему работает в 32-разрядном цветовом режиме.

Синтаксис

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

Параметры

[in] lpDevMode

Указатель на структуру DEVMODE, описывающую новый графический режим. Если lpDevModeNULL, все значения в реестре будут использоваться для параметра отображения. Передача NULL для параметра lpDevMod e и 0 для параметра dwFlags dwFlags — самый простой способ вернуться в режим по умолчанию после динамического изменения режима.

dmSize член DEVMODE должен быть инициализирован в размер в байтах структуры DEVMODE. Элемент dmDriverExtraDEVMODE должен быть инициализирован, чтобы указать количество байт данных частного драйвера после структуры 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	Для работы графического режима необходимо перезапустить компьютер.

Замечания

Чтобы структура DEVMODE, переданная ChangeDisplaySettings, действительна и содержит только значения, поддерживаемые драйвером отображения, используйте DEVMODE, возвращенные функцией EnumDisplaySettings.

При динамическом изменении режима отображения сообщение WM_DISPLAYCHANGE отправляется всем запущенным приложениям со следующими параметрами сообщения.

Параметры	Значение
wParam	Новые биты на пиксель
LOWORD(lParam)	Новая ширина пикселя
HIWORD(lParam)	Новая высота пикселя

виртуализация DPI

Этот API не участвует в виртуализации DPI. Входные данные всегда относятся к физическим пикселям и не связаны с вызывающим контекстом.

Заметка

Заголовок winuser.h определяет ChangeDisplaySettings как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winuser.h (включая Windows.h)
библиотеки	User32.lib
DLL	User32.dll
набор API	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (представлено в Windows 10 версии 10.0.14393)