Freigeben über


ChangeDisplaySettingsExA-Funktion (winuser.h)

Die ChangeDisplaySettingsEx-Funktion ändert die Einstellungen des angegebenen Anzeigegeräts in den angegebenen Grafikmodus.

Hinweis Apps, die Sie für Windows 8 und höher entwerfen, können keine Anzeigemodi mehr abfragen oder festlegen, die kleiner als 32 Bits pro Pixel (bpp) sind. Bei diesen Vorgängen tritt ein Fehler auf. Diese Apps verfügen über ein Kompatibilitätsmanifest, das auf Windows 8 abzielt. 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 ChangeDisplaySettingsExA(
  [in] LPCSTR   lpszDeviceName,
  [in] DEVMODEA *lpDevMode,
       HWND     hwnd,
  [in] DWORD    dwflags,
  [in] LPVOID   lParam
);

Parameter

[in] lpszDeviceName

Ein Zeiger auf eine null-beendete Zeichenfolge, die das Anzeigegerät angibt, dessen Grafikmodus sich ändert. Nur anzeigegerätenamen, die von EnumDisplayDevices zurückgegeben werden, sind gültig. Weitere Informationen zu den Namen, die diesen Anzeigegeräten zugeordnet sind, finden Sie unter EnumDisplayDevices .

Der lpszDeviceName-Parameter kann NULL sein. Ein NULL-Wert gibt das Standardanzeigegerät an. Das Standardgerät kann bestimmt werden, indem Sie EnumDisplayDevices aufrufen und auf das flag DISPLAY_DEVICE_PRIMARY_DEVICE überprüfen.

[in] lpDevMode

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

Das dmSize-Element muss in die Größe der DEVMODE-Struktur in Bytes initialisiert werden. Das dmDriverExtra-Element muss initialisiert werden, um die Anzahl der Bytes privater Treiberdaten nach der DEVMODE-Struktur anzugeben. Darüber hinaus können Sie eines 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-Member festlegen, um die Anzeigeeinstellungen zu ändern.

Wert Bedeutung
DM_BITSPERPEL Verwenden Sie den Wert dmBitsPerPel .
DM_PELSWIDTH Verwenden Sie den Wert dmPelsWidth .
DM_PELSHEIGHT Verwenden Sie den Wert dmPelsHeight .
DM_DISPLAYFLAGS Verwenden Sie den Wert dmDisplayFlags .
DM_DISPLAYFREQUENCY Verwenden Sie den Wert dmDisplayFrequency .
DM_POSITION Verwenden Sie den DmPosition-Wert .

hwnd

Reserviert; muss NULL sein.

[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 temporärer Natur.

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.
CDS_VIDEOPARAMETERS
Wenn festgelegt, ist der lParam-Parameter ein Zeiger auf eine VIDEOPARAMETERS-Struktur .
CDS_ENABLE_UNSAFE_MODES
Aktiviert Einstellungen für unsichere Grafikmodi.
CDS_DISABLE_UNSAFE_MODES
Deaktiviert Einstellungen für unsichere Grafikmodi.
 

Wenn Sie CDS_TEST angeben, kann eine Anwendung bestimmen, welche Grafikmodi tatsächlich gültig sind, ohne dass sich das System in sie ändert.

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.

[in] lParam

Wenn dwFlagsCDS_VIDEOPARAMETERS ist, ist lParam ein Zeiger auf eine VIDEOPARAMETERS-Struktur . Andernfalls muss lParamNULL sein.

Rückgabewert

Die ChangeDisplaySettingsEx-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 ChangeDisplaySettingsEx übergebene DEVMODE-Struktur gültig ist und nur werte enthält, die vom Anzeigetreiber unterstützt werden, verwenden Sie den devmode, der von der EnumDisplaySettings-Funktion zurückgegeben wird.

Wenn Sie einem System mit mehreren Monitoren programmgesteuert einen Anzeigemonitor hinzufügen, legen Sie DEVMODE.dmFields auf DM_POSITION fest, und geben Sie (in DEVMODE.dmPosition) für den hinzuzufügenden Monitor eine Position an, die an mindestens ein Pixel des Anzeigebereichs eines vorhandenen Monitors angrenzt. Um den Monitor zu trennen, legen Sie DEVMODE.dmFields auf DM_POSITION aber DEVMODE.dmPelsWidth und DEVMODE.dmPelsHeight auf Null fest. Weitere Informationen finden Sie unter Mehrere Anzeigemonitore.

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
 

Um die Einstellungen für mehrere Anzeige gleichzeitig zu ändern, rufen Sie zuerst ChangeDisplaySettingsEx für jedes Einzelne Gerät auf, um die Registrierung zu aktualisieren, ohne die Änderungen anzuwenden. Rufen Sie dann ChangeDisplaySettingsEx erneut mit einem NULL-Gerät auf, um die Änderungen anzuwenden. Gehen Sie beispielsweise wie folgt vor, um die Einstellungen für zwei Anzeigen zu ändern:


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

DPI-Virtualisierung

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

Hinweis

Der winuser.h-Header definiert ChangeDisplaySettingsEx 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 Code, der nicht Codierungsneutral ist, 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 (windows.h einschließen)
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)

Weitere Informationen

CreateDC

DEVMODE

Gerätekontextfunktionen

Übersicht über Gerätekontexte

EnumDisplayDevices

EnumDisplaySettings

VIDEOPARAMETERS

WM_DISPLAYCHANGE