ChangeDisplaySettingsW-Funktion (winuser.h)

Artikel
03/04/2024

Die ChangeDisplaySettings-Funktion ändert die Einstellungen des Standardanzeigegeräts in den angegebenen Grafikmodus.

Verwenden Sie die ChangeDisplaySettingsEx-Funktion , um die Einstellungen eines angegebenen Anzeigegeräts zu ändern.

Hinweis Apps, die Sie für Windows 8 und höher entwerfen, können anzeigemodi, die kleiner als 32 Bit pro Pixel (bpp) sind, nicht mehr abfragen oder festlegen. Bei diesen Vorgängen tritt ein Fehler auf. Diese Apps verfügen über ein Kompatibilitätsmanifest, das auf Windows 8 ausgerichtet ist. Windows 8 unterstützt weiterhin 8-Bit- und 16-Bit-Farbmodi für Desktop-Apps, die ohne Windows 8 Manifest erstellt wurden. Windows 8 emuliert diese Modi, wird aber weiterhin im 32-Bit-Farbmodus ausgeführt.

Syntax

LONG ChangeDisplaySettingsW(
  [in] DEVMODEW *lpDevMode,
  [in] DWORD    dwFlags
);

Parameter

[in] lpDevMode

Ein Zeiger auf eine DEVMODE-Struktur , die den neuen Grafikmodus beschreibt. Wenn lpDevModeNULL ist, werden alle Werte, die derzeit in der Registrierung enthalten sind, für die Anzeigeeinstellung verwendet. Das Übergeben von NULL für den lpDevMode-Parameter und 0 für den dwFlags-Parameter ist die einfachste Möglichkeit, nach einer Änderung des dynamischen Modus zum Standardmodus zurückzukehren.

Das dmSize-Element von DEVMODE muss mit der Größe der DEVMODE-Struktur in Bytes initialisiert werden. Das dmDriverExtra-Element von DEVMODE muss initialisiert werden, um die Anzahl der Byte privater Treiberdaten nach der DEVMODE-Struktur anzugeben. Darüber hinaus können Sie beliebige oder alle der folgenden Member der DEVMODE-Struktur verwenden.

Mitglied	Bedeutung
dmBitsPerPel	Bit pro Pixel
dmPelsWidth	Pixelbreite
dmPelsHeight	Pixelhöhe
dmDisplayFlags	Modusflags
dmDisplayFrequency	Modushäufigkeit
dmPosition	Position des Geräts in einer Konfiguration mit mehreren Monitoren.

Zusätzlich zur Verwendung eines oder mehrerer der vorherigen DEVMODE-Member müssen Sie auch einen oder mehrere der folgenden Werte im dmFields-Element festlegen, um die Anzeigeeinstellung zu ändern.

Wert	Bedeutung
DM_BITSPERPEL	Verwenden Sie den DmBitsPerPel-Wert .
DM_PELSWIDTH	Verwenden Sie den DmPelsWidth-Wert .
DM_PELSHEIGHT	Verwenden Sie den DmPelsHeight-Wert .
DM_DISPLAYFLAGS	Verwenden Sie den DmDisplayFlags-Wert .
DM_DISPLAYFREQUENCY	Verwenden Sie den DmDisplayFrequency-Wert .
DM_POSITION	Verwenden Sie den DmPosition-Wert .

[in] dwFlags

Gibt an, wie der Grafikmodus geändert werden soll. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
0	Der Grafikmodus für den aktuellen Bildschirm wird dynamisch geändert.
CDS_FULLSCREEN	Der Modus ist vorübergehend. Wenn Sie zu und von einem anderen Desktop wechseln, wird dieser Modus nicht zurückgesetzt.
CDS_GLOBAL	Die Einstellungen werden im Bereich globale Einstellungen gespeichert, sodass sie sich auf alle Benutzer auf dem Computer auswirken. Andernfalls werden nur die Einstellungen für den Benutzer geändert. Dieses Flag ist nur gültig, wenn es mit dem CDS_UPDATEREGISTRY-Flag angegeben wird.
CDS_NORESET	Die Einstellungen werden in der Registrierung gespeichert, werden aber nicht wirksam. Dieses Flag ist nur gültig, wenn es mit dem CDS_UPDATEREGISTRY-Flag angegeben wird.
CDS_RESET	Die Einstellungen sollten geändert werden, auch wenn die angeforderten Einstellungen mit den aktuellen Einstellungen identisch sind.
CDS_SET_PRIMARY	Dieses Gerät wird zum primären Gerät.
CDS_TEST	Das System testet, ob der angeforderte Grafikmodus festgelegt werden kann.
CDS_UPDATEREGISTRY	Der Grafikmodus für den aktuellen Bildschirm wird dynamisch geändert, und der Grafikmodus wird in der Registrierung aktualisiert. Die Modusinformationen werden im BENUTZERprofil gespeichert.

Durch die Angabe CDS_TEST kann eine Anwendung bestimmen, welche Grafikmodi tatsächlich gültig sind, ohne dass das System in diesen Grafikmodus wechselt.

Wenn CDS_UPDATEREGISTRY angegeben ist und es möglich ist, den Grafikmodus dynamisch zu ändern, werden die Informationen in der Registrierung gespeichert und DISP_CHANGE_SUCCESSFUL zurückgegeben. Wenn es nicht möglich ist, den Grafikmodus dynamisch zu ändern, werden die Informationen in der Registrierung gespeichert und DISP_CHANGE_RESTART zurückgegeben.

Wenn CDS_UPDATEREGISTRY angegeben ist und die Informationen nicht in der Registrierung gespeichert werden konnten, wird der Grafikmodus nicht geändert und DISP_CHANGE_NOTUPDATED zurückgegeben.

Rückgabewert

Die ChangeDisplaySettings-Funktion gibt einen der folgenden Werte zurück.

Rückgabecode	Beschreibung
DISP_CHANGE_SUCCESSFUL	Die Einstellungsänderung war erfolgreich.
DISP_CHANGE_BADDUALVIEW	Die Einstellungsänderung war nicht erfolgreich, da das System DualView-fähig ist.
DISP_CHANGE_BADFLAGS	Ein ungültiger Satz von Flags wurde übergeben.
DISP_CHANGE_BADMODE	Der Grafikmodus wird nicht unterstützt.
DISP_CHANGE_BADPARAM	Ein ungültiger Parameter wurde übergeben. Dies kann ein ungültiges Flag oder eine Kombination aus Flags umfassen.
DISP_CHANGE_FAILED	Fehler beim Anzeigetreiber für den angegebenen Grafikmodus.
DISP_CHANGE_NOTUPDATED	Einstellungen können nicht in die Registrierung geschrieben werden.
DISP_CHANGE_RESTART	Der Computer muss neu gestartet werden, damit der Grafikmodus funktioniert.

Hinweise

Um sicherzustellen, dass die an ChangeDisplaySettings übergebene DEVMODE-Struktur gültig ist und nur werte enthält, die vom Anzeigetreiber unterstützt werden, verwenden Sie die DEVMODE-Eigenschaft, die von der EnumDisplaySettings-Funktion zurückgegeben wird.

Wenn der Anzeigemodus dynamisch geändert wird, wird die meldung WM_DISPLAYCHANGE mit den folgenden Nachrichtenparametern an alle ausgeführten Anwendungen gesendet.

Parameter	Bedeutung
wParam	Neue Bits pro Pixel
LOWORD(lParam)	Neue Pixelbreite
HIWORD(lParam)	Neue Pixelhöhe

DPI-Virtualisierung

Diese API ist nicht an der DPI-Virtualisierung beteiligt. Die angegebene Eingabe bezieht sich immer auf physische Pixel und ist nicht mit dem aufrufenden Kontext verknüpft.

Hinweis

Der winuser.h-Header definiert ChangeDisplaySettings als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h (einschließlich Windows.h)
Bibliothek	User32.lib
DLL	User32.dll
APIs	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (eingeführt in Windows 10, Version 10.0.14393)