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

Статья
03/15/2023

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

Примечание Приложения, которые вы разрабатываете для Windows 8 и более поздних версий, больше не могут запрашивать или задавать режимы отображения менее 32 бит на пиксель (bpp); эти операции завершатся ошибкой. Эти приложения имеют манифест совместимости, предназначенный для Windows 8. Windows 8 по-прежнему поддерживает 8- и 16-разрядные цветовые режимы для классических приложений, созданных без манифеста Windows 8; 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, для параметра отображения будут использоваться все текущие значения в реестре. Передать значение NULL для параметра lpDevMode и 0 для параметра dwFlags — самый простой способ вернуться в режим по умолчанию после изменения динамического режима.

Член 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

Если dwFlagsCDS_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	Чтобы графический режим работал, компьютер необходимо перезагрузить.

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

При добавлении монитора дисплея в систему с несколькими мониторами программными средствами задайте для DEVMODE.dmFields значение DM_POSITION и укажите позицию (в DEVMODE.dmPosition) добавляемого монитора, которая находится рядом по крайней мере с одним пикселем области отображения существующего монитора. Чтобы отключить монитор, задайте для параметра DEVMODE.dmFields значение DM_POSITION но установите для devmode.dmPelsWidth и DEVMODE.dmPelsHeight значение 0. Дополнительные сведения см. в разделе Несколько мониторов отображения.

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

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

Чтобы изменить параметры для нескольких дисплеев одновременно, сначала вызовите ChangeDisplaySettingsEx для каждого устройства по отдельности, чтобы обновить реестр без применения изменений. Затем снова вызовите ChangeDisplaySettingsEx с устройством NULL , чтобы применить изменения. Например, чтобы изменить параметры для двух дисплеев, сделайте следующее:


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 в качестве псевдонима, который автоматически выбирает версию 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)