ChangeDisplaySettingsExA, fonction (winuser.h)

Article
11/20/2024

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

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 ChangeDisplaySettingsExA(
  [in] LPCSTR   lpszDeviceName,
  [in] DEVMODEA *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 l’appareil d’affichage dont le mode graphique change. Seuls les noms d’appareils affichés comme retournés par EnumDisplayDevices sont valides. Consultez EnumDisplayDevices pour plus d’informations sur les noms associés à ces appareils d’affichage.

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

[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 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 à plusieurs moniteurs.

Outre l’utilisation d’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 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é; doit être NULL .

[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.
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 en modes graphiques non sécurisés.
CDS_DISABLE_UNSAFE_MODES	Désactive les modifications des paramètres en 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 ne les modifie.

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

[in] lParam

Si dwFlags est CDS_VIDEOPARAMETERS, lParam est un pointeur vers une structure VIDEOPARAMETERS. Sinon, lParam doit être NULL .

Valeur de retour

La fonction ChangeDisplaySettingsEx 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 à ChangeDisplaySettingsEx est valide et contient uniquement des valeurs prises en charge par le pilote d’affichage, utilisez la DEVMODE retournée par la fonction EnumDisplaySettings.

Lors de l’ajout d’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 adjacent à 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 plusieurs moniteurs d’affichage.

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 pour 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 pour 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 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 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. 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)