ChangeDisplaySettingsA, fonction (winuser.h)

Article
11/20/2024

La fonction ChangeDisplaySettings modifie les paramètres de l’appareil d’affichage par défaut en mode graphique spécifié.

Pour modifier les paramètres d’un appareil d’affichage spécifié, utilisez la fonction ChangeDisplaySettingsEx.

Remarque Applications que vous concevez pour cibler Windows 8 et versions ultérieures ne peuvent plus interroger ou définir des modes d’affichage inférieurs à 32 bits par pixel (bpp) ; ces opérations échouent. Ces applications ont un manifeste de compatibilité qui cible Windows 8. Windows 8 prend toujours en charge les modes de couleur 8 bits et 16 bits pour les applications de bureau qui ont été créées sans manifeste Windows 8 ; Windows 8 émule ces modes, mais s’exécute toujours en mode couleur 32 bits.

Syntaxe

LONG ChangeDisplaySettingsA(
  [in] DEVMODEA *lpDevMode,
  [in] DWORD    dwFlags
);

Paramètres

[in] lpDevMode

Pointeur vers une structure DEVMODE qui décrit le nouveau mode graphique. Si lpDevMode est NULL, toutes les valeurs actuellement présentes dans le Registre seront utilisées pour le paramètre d’affichage. Passer NULL pour le paramètre lpDevMode et 0 pour le paramètre dwFlags est le moyen le plus simple de revenir au mode par défaut après un changement de mode dynamique.

Le dmSize membre de DEVMODE doit être initialisé à la taille, en octets, de la structure DEVMODE . Le membre dmDriverExtra de DEVMODE doit être initialisé pour indiquer le nombre d’octets de données de pilote privé suivant la structure DEVMODE . En outre, vous pouvez utiliser n’importe quel ou tous les membres suivants de la structure DEVMODE .

Membre	Signification
dmBitsPerPel	Bits par pixel
dmPelsWidth	Largeur des pixels
dmPelsHeight	Hauteur des pixels
dmDisplayFlags	Indicateurs de mode
dmDisplayFrequency	Fréquence du mode
dmPosition	Position de l’appareil dans une configuration à plusieurs moniteurs.

En plus d’utiliser un ou plusieurs membres DEVMODE précédents, vous devez également définir une ou plusieurs des valeurs suivantes dans le membre dmFields pour modifier le paramètre d’affichage.

Valeur	Signification
DM_BITSPERPEL	Utilisez la valeur dmBitsPerPel.
DM_PELSWIDTH	Utilisez la valeur dmPelsWidth.
DM_PELSHEIGHT	Utilisez la valeur dmPelsHeight.
DM_DISPLAYFLAGS	Utilisez la valeur dmDisplayFlags.
DM_DISPLAYFREQUENCY	Utilisez la valeur dmDisplayFrequency .
DM_POSITION	Utilisez la valeur dmPosition .

[in] dwFlags

Indique comment le mode graphique doit être modifié. Ce paramètre peut être l’une des valeurs suivantes.

Valeur	Signification
0	Le mode graphique de l’écran actuel sera modifié dynamiquement.
CDS_FULLSCREEN	Le mode est temporaire par nature. Si vous passez à un autre bureau, ce mode ne sera pas réinitialisé.
CDS_GLOBAL	Les paramètres sont enregistrés dans la zone des paramètres globaux afin qu’ils affectent tous les utilisateurs sur l’ordinateur. Sinon, seuls les paramètres de l’utilisateur sont modifiés. Cet indicateur est valide uniquement lorsqu’il est spécifié avec l’indicateur de CDS_UPDATEREGISTRY.
CDS_NORESET	Les paramètres seront enregistrés dans le Registre, mais ne prendront pas effet. Cet indicateur est valide uniquement lorsqu’il est spécifié avec l’indicateur de CDS_UPDATEREGISTRY.
CDS_RESET	Les paramètres doivent être modifiés, même si les paramètres demandés sont identiques aux paramètres actuels.
CDS_SET_PRIMARY	Cet appareil deviendra l’appareil principal.
CDS_TEST	Le système teste si le mode graphique demandé peut être défini.
CDS_UPDATEREGISTRY	Le mode graphique de l’écran actuel sera modifié dynamiquement et le mode graphique sera mis à jour dans le Registre. Les informations de mode sont stockées dans le profil UTILISATEUR.

La spécification de CDS_TEST permet à une application de déterminer quels modes graphiques sont réellement valides, sans que le système passe à ce mode graphique.

Si CDS_UPDATEREGISTRY est spécifié et qu’il est possible de modifier le mode graphique dynamiquement, les informations sont stockées dans le Registre et DISP_CHANGE_SUCCESSFUL est retournée. S’il n’est pas possible de modifier le mode graphique dynamiquement, les informations sont stockées dans le Registre et DISP_CHANGE_RESTART est retournée.

Si CDS_UPDATEREGISTRY est spécifié et que les informations n’ont pas pu être stockées dans le Registre, le mode graphique n’est pas modifié et DISP_CHANGE_NOTUPDATED est retourné.

Valeur de retour

La fonction ChangeDisplaySettings retourne l’une des valeurs suivantes.

Retourner le code	Description
DISP_CHANGE_SUCCESSFUL	La modification des paramètres a réussi.
DISP_CHANGE_BADDUALVIEW	La modification des paramètres a échoué, car le système est compatible avec DualView.
DISP_CHANGE_BADFLAGS	Un ensemble d’indicateurs non valide a été passé.
DISP_CHANGE_BADMODE	Le mode graphique n’est pas pris en charge.
DISP_CHANGE_BADPARAM	Un paramètre non valide a été passé. Cela peut inclure un indicateur non valide ou une combinaison d’indicateurs.
DISP_CHANGE_FAILED	Le pilote d’affichage a échoué en mode graphique spécifié.
DISP_CHANGE_NOTUPDATED	Impossible d’écrire des paramètres dans le Registre.
DISP_CHANGE_RESTART	L’ordinateur doit être redémarré pour que le mode graphique fonctionne.

Remarques

Pour vous assurer que la structure DEVMODE passée à ChangeDisplaySettings est valide et contient uniquement des valeurs prises en charge par le pilote d’affichage, utilisez la DEVMODE retournée par la fonction EnumDisplaySettings.

Lorsque le mode d’affichage est modifié dynamiquement, le message WM_DISPLAYCHANGE est envoyé à toutes les applications en cours d’exécution avec les paramètres de message suivants.

Paramètres	Signification
wParam	Nouveaux bits par pixel
LOWORD(lParam)	Nouvelle largeur de pixel
HIWORD(lParam)	Nouvelle hauteur de pixel

virtualisation d'ppp

Cette API ne participe pas à la virtualisation DPI. L’entrée donnée est toujours en termes de pixels physiques et n’est pas liée au contexte appelant.

Note

L’en-tête winuser.h définit ChangeDisplaySettings comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winuser.h (include Windows.h)
bibliothèque	User32.lib
DLL	User32.dll
ensemble d’API	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (introduit dans Windows 10, version 10.0.14393)