ChangeDisplaySettingsExA-Funktion (winuser.h)

Artikel
11/20/2024

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

Beachten Sie Apps, die Sie für Windows 8 und höher entwerfen, keine Anzeigemodi mehr abfragen oder festlegen können, die weniger als 32 Bit pro Pixel (bpp) sind; Diese Vorgänge schlagen fehl. Diese Apps verfügen über ein Kompatibilitätsmanifest für Windows 8. Windows 8 unterstützt weiterhin 8-Bit- und 16-Bit-Farbmodi für Desktop-Apps, die ohne ein Windows 8-Manifest erstellt wurden; Windows 8 emuliert diese Modi, wird jedoch 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 mit Null beendete Zeichenfolge, die das Anzeigegerät angibt, dessen Grafikmodus sich ändert. Es sind nur Gerätenamen wie von EnumDisplayDevices gültig. Weitere Informationen zu den Namen, die diesen Anzeigegeräten zugeordnet sind, finden Sie unter EnumDisplayDevices.

Der parameter lpszDeviceName kann NULL-sein. Ein NULL- Wert gibt das Standardanzeigegerät an. Das Standardgerät kann durch Aufrufen EnumDisplayDevices bestimmt und nach dem DISPLAY_DEVICE_PRIMARY_DEVICE Flag gesucht werden.

[in] lpDevMode

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

Das dmSize Member muss in Byte der DEVMODE--Struktur initialisiert werden. Das dmDriverExtra Member muss initialisiert werden, um die Anzahl der Byte privater Treiberdaten nach der DEVMODE- Struktur anzugeben. Darüber hinaus können Sie eines der folgenden Elemente der DEVMODE- Struktur verwenden.

Mitglied	Bedeutung
dmBitsPerPel-	Bits pro Pixel
dmPelsWidth-	Pixelbreite
dmPelsHeight-	Pixelhöhe
dmDisplayFlags-	Moduskennzeichnungen
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 wert dmPosition.

hwnd

Reserviert; muss NULL-sein.

[in] dwflags

Gibt an, wie der Grafikmodus geändert werden soll. Dieser Parameter kann einer der folgenden Werte sein:

Wert	Bedeutung
0	Der Grafikmodus für den aktuellen Bildschirm wird dynamisch geändert.
CDS_FULLSCREEN	Der Modus ist vorübergehend in der Natur. Wenn Sie zu und von einem anderen Desktop wechseln, wird dieser Modus nicht zurückgesetzt.
CDS_GLOBAL	Die Einstellungen werden im globalen Einstellungsbereich gespeichert, sodass sie sich auf alle Benutzer auf dem Computer auswirken. Andernfalls werden nur die Einstellungen für den Benutzer geändert. Dieses Kennzeichen ist nur gültig, wenn es mit dem CDS_UPDATEREGISTRY Flag angegeben wird.
CDS_NORESET	Die Einstellungen werden in der Registrierung gespeichert, werden jedoch nicht wirksam. Dieses Kennzeichen 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	Bei Festlegung ist der lParam Parameter ein Zeiger auf eine VIDEOPARAMETERS--Struktur.
CDS_ENABLE_UNSAFE_MODES	Aktiviert Einstellungenänderungen an unsicheren Grafikmodi.
CDS_DISABLE_UNSAFE_MODES	Deaktiviert Einstellungsänderungen an unsicheren Grafikmodi.

Wenn Sie CDS_TEST angeben, kann eine Anwendung bestimmen, welche Grafikmodi tatsächlich gültig sind, ohne dass das System zu ihnen 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.

[in] lParam

Wenn dwFlags-CDS_VIDEOPARAMETERSist, ist lParam- ein Zeiger auf eine VIDEOPARAMETERS- Struktur. Andernfalls muss lParam-NULL-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	Es wurde ein ungültiger Satz von Flags übergeben.
DISP_CHANGE_BADMODE	Der Grafikmodus wird nicht unterstützt.
DISP_CHANGE_BADPARAM	Ein ungültiger Parameter wurde übergeben. Dies kann eine ungültige Kennzeichnung oder Eine Kombination von Kennzeichen enthalten.
DISP_CHANGE_FAILED	Der Anzeigetreiber hat den angegebenen Grafikmodus nicht bestanden.
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.

Bemerkungen

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

Legen Sie beim programmgesteuerten Hinzufügen eines Anzeigemonitors zu einem System mit mehreren Monitoren DEVMODE.dmFields auf DM_POSITION fest, und geben Sie eine Position (in DEVMODE.dmPosition) für den Monitor an, den Sie hinzufügen, die an mindestens ein Pixel des Anzeigebereichs eines vorhandenen Monitors angrenzen. Um den Monitor zu trennen, legen Sie DEVMODE.dmFields- auf DM_POSITION fest, legen 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 WM_DISPLAYCHANGE Nachricht an alle ausgeführten Anwendungen mit den folgenden Meldungsparametern 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 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 nimmt nicht an der DPI-Virtualisierung teil. Die angegebene Eingabe entspricht immer physischen Pixeln und ist nicht mit dem aufrufenden Kontext verknüpft.

Anmerkung

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
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winuser.h (enthalten Windows.h)
Library	User32.lib
DLL-	User32.dll
API-Satz	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (eingeführt in Windows 10, Version 10.0.14393)