Función ChangeDisplaySettingsExA (winuser.h)

Artículo
03/15/2023

La función ChangeDisplaySettingsEx cambia la configuración del dispositivo de visualización especificado al modo gráfico especificado.

Nota Las aplicaciones que diseñe para dirigirse a Windows 8 y versiones posteriores ya no pueden consultar o establecer modos de presentación que tengan menos de 32 bits por píxel (bpp); estas operaciones producirán un error. Estas aplicaciones tienen un manifiesto de compatibilidad que tiene como destino Windows 8. Windows 8 todavía admite modos de color de 8 y 16 bits para aplicaciones de escritorio compiladas sin un manifiesto de Windows 8; Windows 8 emula estos modos, pero sigue funcionando en modo de color de 32 bits.

Sintaxis

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

Parámetros

[in] lpszDeviceName

Puntero a una cadena terminada en null que especifica el dispositivo de visualización cuyo modo gráfico cambiará. Solo los nombres de dispositivo que devuelve EnumDisplayDevices son válidos . Consulte EnumDisplayDevices para obtener más información sobre los nombres asociados a estos dispositivos de visualización.

El parámetro lpszDeviceName puede ser NULL. Un valor NULL especifica el dispositivo para mostrar predeterminado. El dispositivo predeterminado se puede determinar llamando a EnumDisplayDevices y comprobando la marca DISPLAY_DEVICE_PRIMARY_DEVICE.

[in] lpDevMode

Puntero a una estructura DEVMODE que describe el nuevo modo gráfico. Si lpDevMode es NULL, se usarán todos los valores que se encuentran actualmente en el Registro para la configuración de visualización. Pasar NULL para el parámetro lpDevMode y 0 para el parámetro dwFlags es la manera más fácil de volver al modo predeterminado después de un cambio de modo dinámico.

El miembro dmSize debe inicializarse en el tamaño, en bytes, de la estructura DEVMODE . El miembro dmDriverExtra debe inicializarse para indicar el número de bytes de datos del controlador privado después de la estructura DEVMODE . Además, puede usar cualquiera de los siguientes miembros de la estructura DEVMODE .

Miembro	Significado
dmBitsPerPel	Bits por píxel
dmPelsWidth	Ancho de píxel
dmPelsHeight	Alto de píxeles
dmDisplayFlags	Marcas de modo
dmDisplayFrequency	Frecuencia del modo
dmPosition	Posición del dispositivo en una configuración de varios monitores.

Además de usar uno o varios de los miembros DEVMODE anteriores, también debe establecer uno o varios de los valores siguientes en el miembro dmFields para cambiar la configuración de presentación.

Valor	Significado
DM_BITSPERPEL	Use el valor dmBitsPerPel .
DM_PELSWIDTH	Use el valor dmPelsWidth .
DM_PELSHEIGHT	Use el valor dmPelsHeight .
DM_DISPLAYFLAGS	Use el valor dmDisplayFlags .
DM_DISPLAYFREQUENCY	Use el valor dmDisplayFrequency .
DM_POSITION	Use el valor dmPosition .

hwnd

Reservados; debe ser NULL.

[in] dwflags

Indica cómo se debe cambiar el modo gráfico. Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
0	El modo gráfico de la pantalla actual se cambiará dinámicamente.
CDS_FULLSCREEN	El modo es temporal por naturaleza. Si cambia a y desde otro escritorio, este modo no se restablecerá.
CDS_GLOBAL	La configuración se guardará en el área de configuración global para que afecten a todos los usuarios del equipo. De lo contrario, solo se modifica la configuración del usuario. Esta marca solo es válida cuando se especifica con la marca CDS_UPDATEREGISTRY.
CDS_NORESET	La configuración se guardará en el Registro, pero no surtirá efecto. Esta marca solo es válida cuando se especifica con la marca CDS_UPDATEREGISTRY.
CDS_RESET	La configuración debe cambiarse, incluso si la configuración solicitada es la misma que la configuración actual.
CDS_SET_PRIMARY	Este dispositivo se convertirá en el dispositivo principal.
CDS_TEST	El sistema comprueba si se puede establecer el modo gráfico solicitado.
CDS_UPDATEREGISTRY	El modo gráfico de la pantalla actual se cambiará dinámicamente y el modo gráfico se actualizará en el Registro. La información del modo se almacena en el perfil DE USUARIO.
CDS_VIDEOPARAMETERS	Cuando se establece, el parámetro lParam es un puntero a una estructura VIDEOPARAMETERS .
CDS_ENABLE_UNSAFE_MODES	Habilita los cambios de configuración en los modos de gráficos no seguros.
CDS_DISABLE_UNSAFE_MODES	Deshabilita los cambios de configuración en los modos de gráficos no seguros.

Especificar CDS_TEST permite a una aplicación determinar qué modos gráficos son realmente válidos, sin provocar que el sistema cambie a ellos.

Si se especifica CDS_UPDATEREGISTRY y es posible cambiar el modo gráfico dinámicamente, la información se almacena en el registro y se devuelve DISP_CHANGE_SUCCESSFUL. Si no es posible cambiar el modo gráfico dinámicamente, la información se almacena en el Registro y se devuelve DISP_CHANGE_RESTART.

Si se especifica CDS_UPDATEREGISTRY y no se pudo almacenar la información en el Registro, no se cambia el modo gráfico y se devuelve DISP_CHANGE_NOTUPDATED.

[in] lParam

Si dwFlags es CDS_VIDEOPARAMETERS, lParam es un puntero a una estructura VIDEOPARAMETERS . De lo contrario , lParam debe ser NULL.

Valor devuelto

La función ChangeDisplaySettingsEx devuelve uno de los valores siguientes.

Código devuelto	Descripción
DISP_CHANGE_SUCCESSFUL	El cambio de configuración se realizó correctamente.
DISP_CHANGE_BADDUALVIEW	El cambio de configuración no se realizó correctamente porque el sistema es compatible con DualView.
DISP_CHANGE_BADFLAGS	Se pasó un conjunto no válido de marcas.
DISP_CHANGE_BADMODE	No se admite el modo gráfico.
DISP_CHANGE_BADPARAM	Se pasó un parámetro no válido. Esto puede incluir una marca o combinación de marcas no válidas.
DISP_CHANGE_FAILED	El controlador de pantalla produjo un error en el modo gráfico especificado.
DISP_CHANGE_NOTUPDATED	No se puede escribir la configuración en el Registro.
DISP_CHANGE_RESTART	El equipo debe reiniciarse para que el modo gráfico funcione.

Comentarios

Para asegurarse de que la estructura DEVMODE pasada a ChangeDisplaySettingsEx es válida y contiene solo los valores admitidos por el controlador de pantalla, use el DEVMODE devuelto por la función EnumDisplaySettings .

Al agregar un monitor de pantalla a un sistema de varios monitores mediante programación, establezca DEVMODE.dmFields en DM_POSITION y especifique una posición (en DEVMODE.dmPosition) para el monitor que va a agregar que está adyacente a al menos un píxel del área de visualización de un monitor existente. Para desasociar el monitor, establezca DEVMODE.dmFields en DM_POSITION pero establezca DEVMODE.dmPelsWidth y DEVMODE.dmPelsHeight en cero. Para obtener más información, vea Varios monitores de visualización.

Cuando el modo de presentación se cambia dinámicamente, el mensaje de WM_DISPLAYCHANGE se envía a todas las aplicaciones en ejecución con los parámetros de mensaje siguientes.

Parámetros	Significado
wParam	Nuevos bits por píxel
LOWORD(lParam)	Nuevo ancho de píxel
HIWORD(lParam)	Nuevo alto de píxeles

Para cambiar la configuración de más de una pantalla al mismo tiempo, primero llame a ChangeDisplaySettingsEx para cada dispositivo individualmente para actualizar el registro sin aplicar los cambios. A continuación, llame a ChangeDisplaySettingsEx una vez más, con un dispositivo NULL , para aplicar los cambios. Por ejemplo, para cambiar la configuración de dos pantallas, haga lo siguiente:


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

Virtualización de PPP

Esta API no participa en la virtualización de PPP. La entrada especificada siempre está en términos de píxeles físicos y no está relacionada con el contexto de llamada.

Nota

El encabezado winuser.h define ChangeDisplaySettingsEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winuser.h (incluya Windows.h)
Library	User32.lib
Archivo DLL	User32.dll
Conjunto de API	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (introducido en Windows 10, versión 10.0.14393)