Fonction ChangeDisplaySettingsExW (winuser.h)

Article
08/27/2023

La fonction ChangeDisplaySettingsEx modifie les paramètres du périphérique d’affichage spécifié en mode graphique spécifié.

Note Les 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 ChangeDisplaySettingsExW(
  [in] LPCWSTR  lpszDeviceName,
  [in] DEVMODEW *lpDevMode,
       HWND     hwnd,
  [in] DWORD    dwflags,
  [in] LPVOID   lParam
);

Paramètres

[in] lpszDeviceName

Pointeur vers une chaîne terminée par null qui spécifie le périphérique d’affichage dont le mode graphique sera modifié. Seuls les noms d’appareils d’affichage retournés par EnumDisplayDevices sont valides . Pour plus d’informations sur les noms associés à ces appareils d’affichage, consultez EnumDisplayDevices .

Le paramètre lpszDeviceName peut être NULL. Une valeur NULL spécifie le périphérique d’affichage par défaut. L’appareil par défaut peut être déterminé en appelant EnumDisplayDevices et en vérifiant l’indicateur DISPLAY_DEVICE_PRIMARY_DEVICE.

[in] lpDevMode

Pointeur vers une structure DEVMODE qui décrit le nouveau mode graphique. Si lpDevMode a la valeur NULL, toutes les valeurs actuellement dans le Registre seront utilisées pour le paramètre d’affichage. Le passage de null pour le paramètre lpDevMode et de 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 membre dmSize doit être initialisé à la taille, en octets, de la structure DEVMODE . Le membre dmDriverExtra doit être initialisé pour indiquer le nombre d’octets de données de pilote privé suivant la structure DEVMODE . En outre, vous pouvez utiliser l’un des 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 multi-moniteurs.

En plus d’utiliser un ou plusieurs des membres DEVMODE précédents, vous devez également définir une ou plusieurs des valeurs suivantes dans le membre dmFields pour modifier les paramètres 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 .

hwnd

Réservés au; doit avoir la valeur NULL.

[in] dwflags

Indique comment le mode graphique doit être modifié. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
0	Le mode graphique de l’écran actif sera modifié dynamiquement.
CDS_FULLSCREEN	Le mode est temporaire par nature. Si vous changez vers et à partir d’un autre bureau, ce mode ne sera pas réinitialisé.
CDS_GLOBAL	Les paramètres seront enregistrés dans la zone des paramètres globaux afin qu’ils affectent tous les utilisateurs de 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 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 CDS_UPDATEREGISTRY.
CDS_RESET	Les paramètres doivent être modifiés, même si les paramètres demandés sont les mêmes que les 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 actif sera modifié dynamiquement et le mode graphique sera mis à jour dans le Registre. Les informations de mode sont stockées dans le profil UTILISATEUR.
CDS_VIDEOPARAMETERS	Lorsqu’il est défini, le paramètre lParam est un pointeur vers une structure VIDEOPARAMETERS .
CDS_ENABLE_UNSAFE_MODES	Active les modifications des paramètres vers les modes graphiques non sécurisés.
CDS_DISABLE_UNSAFE_MODES	Désactive les modifications de paramètres apportées aux modes graphiques non sécurisés.

La spécification de CDS_TEST permet à une application de déterminer quels modes graphiques sont réellement valides, sans que le système y soit modifié.

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

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

[in] lParam

Si dwFlags est CDS_VIDEOPARAMETERS, lParam est un pointeur vers une structure VIDEOPARAMETERS . Sinon, lParam doit avoir la valeur NULL.

Valeur retournée

La fonction ChangeDisplaySettingsEx retourne l’une des valeurs suivantes.

Code de retour	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é transmis.
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 ou une combinaison d’indicateurs non valides.
DISP_CHANGE_FAILED	Le pilote d’affichage a échoué au mode graphique spécifié.
DISP_CHANGE_NOTUPDATED	Impossible d’écrire les 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 à ChangeDisplaySettingsEx est valide et contient uniquement les valeurs prises en charge par le pilote d’affichage, utilisez le DEVMODE retourné par la fonction EnumDisplaySettings .

Lorsque vous ajoutez un moniteur d’affichage à un système à plusieurs moniteurs par programmation, définissez DEVMODE.dmFields sur DM_POSITION et spécifiez une position (dans DEVMODE.dmPosition) pour le moniteur que vous ajoutez qui est adjacente à au moins un pixel de la zone d’affichage d’un moniteur existant. Pour détacher le moniteur, définissez DEVMODE.dmFields sur DM_POSITION mais définissez DEVMODE.dmPelsWidth et DEVMODE.dmPelsHeight sur zéro. Pour plus d’informations, consultez Moniteurs d’affichage multiples.

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

Pour modifier les paramètres de plusieurs affichages en même temps, appelez d’abord ChangeDisplaySettingsEx pour chaque appareil individuellement afin de mettre à jour le Registre sans appliquer les modifications. Appelez ensuite ChangeDisplaySettingsEx une fois de plus, avec un appareil NULL , pour appliquer les modifications. Par exemple, pour modifier les paramètres de deux affichages, procédez comme suit :


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

Virtualisation PPP

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

Notes

L’en-tête winuser.h définit ChangeDisplaySettingsEx 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. La combinaison 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.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winuser.h (inclure 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)