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

Статья
08/27/2023

Функция 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 , описывающую новый режим графики. Если lpDevMode имеет значение NULL, для параметра отображения будут использоваться все текущие значения в реестре. Передача null для параметра lpDevMode и 0 для параметра dwFlags — это самый простой способ вернуться в режим по умолчанию после изменения динамического режима.

Член dmSizedevMODE должен быть инициализирован размером в байтах структуры 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 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll
Набор API	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (представлено в Windows 10 версии 10.0.14393)