Función ChangeDisplaySettingsA (winuser.h)

Artículo
11/20/2024

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

Para cambiar la configuración de un dispositivo para mostrar especificado, use la función ChangeDisplaySettingsEx.

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 ChangeDisplaySettingsA(
  [in] DEVMODEA *lpDevMode,
  [in] DWORD    dwFlags
);

Parámetros

[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 dmSize miembro de deVMODE debe inicializarse en el tamaño, en bytes, de la estructura DEVMODE de . El miembro dmDriverExtra de DEVMODE 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 o todos los siguientes miembros de la estructura 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 de 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 .

[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.

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

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.

Valor devuelto

La función ChangeDisplaySettings 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 pasada a ChangeDisplaySettings es válida y contiene solo los valores admitidos por el controlador de visualización, use el DEVMODE devuelto por la función EnumDisplaySettings.

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

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 ChangeDisplaySettings 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)