Поделиться через


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

Функция 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)

См. также раздел

Создание центра обработки данных

DEVMODE

Функции контекста устройства

Общие сведения о контекстах устройств

EnumDisplayDevices

EnumDisplaySettings

VIDEOPARAMETERS

WM_DISPLAYCHANGE