Función ChangeDisplaySettingsExA (winuser.h)

Artículo
11/20/2024

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

Nota Aplicaciones que diseñes para tener Como destino Windows 8 y versiones posteriores ya no pueden consultar ni establecer modos de visualización inferiores a 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 creadas 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 se muestran los nombres de dispositivo devueltos por enumDisplayDevices son válidos. Consulte EnumDisplayDevices para obtener más información sobre los nombres asociados a estos dispositivos para mostrar.

El parámetro lpszDeviceName puede ser NULL. Un valor null especifica el dispositivo de visualización predeterminado. El dispositivo predeterminado se puede determinar llamando a EnumDisplayDevices y comprobando la marca de DISPLAY_DEVICE_PRIMARY_DEVICE.

[in] lpDevMode

Puntero a una estructura de 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 de . El miembro dmDriverExtra debe inicializarse para indicar el número de bytes de datos del controlador privado después de la estructura de DEVMODE . Además, puede usar cualquiera de los siguientes miembros de la estructura de DEVMODE.

Miembro	Significado
dmBitsPerPel de	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 siguientes valores en el miembro dmFields para cambiar la configuración de presentación.

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

hwnd

Reservado; debe ser null.

[in] dwflags

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

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 USER.
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 hacer 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.

Observaciones

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

Al agregar un monitor de visualización 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 siguientes parámetros de mensaje.

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 de

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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winuser.h (incluya Windows.h)
biblioteca de	User32.lib
DLL de	User32.dll
conjunto de API de	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (introducido en Windows 10, versión 10.0.14393)