Función ChangeDisplaySettingsA (winuser.h)

Artículo
03/04/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 Las aplicaciones que diseñe para dirigirse a Windows 8 y versiones posteriores ya no pueden consultar o establecer modos de visualización menores 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 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 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 de DEVMODE debe inicializarse en el tamaño, en bytes, de la estructura DEVMODE . El miembro dmDriverExtra de DEVMODE 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 o todos los miembros siguientes 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 visualizació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 .

[in] dwFlags

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

Valor	Significado
0	El modo de gráficos 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 de gráficos 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.

Especificar CDS_TEST permite a una aplicación determinar qué modos de 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 dinámicamente el modo gráfico, la información se almacena en el registro y se devuelve DISP_CHANGE_SUCCESSFUL. Si no es posible cambiar dinámicamente el modo gráfico, 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.

Comentarios

Para asegurarse de que la estructura DEVMODE pasada a ChangeDisplaySettings es válida y contiene solo los valores admitidos por el controlador de pantalla, 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 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

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 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 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 (incluir 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)