Funzione ChangeDisplaySettingsExW (winuser.h)

Articolo
11/20/2024

La funzione ChangeDisplaySettingsEx modifica le impostazioni del dispositivo di visualizzazione specificato nella modalità grafica specificata.

Si noti App che si progettano per Windows 8 e versioni successive non possono più eseguire query o impostare modalità di visualizzazione inferiori a 32 bit per pixel (bpp); queste operazioni avranno esito negativo. Queste app hanno un manifesto di compatibilità destinato a Windows 8. Windows 8 supporta ancora le modalità colore a 8 bit e a 16 bit per le app desktop compilate senza un manifesto di Windows 8; Windows 8 emula queste modalità ma viene comunque eseguita in modalità colore a 32 bit.

Sintassi

LONG ChangeDisplaySettingsExW(
  [in] LPCWSTR  lpszDeviceName,
  [in] DEVMODEW *lpDevMode,
       HWND     hwnd,
  [in] DWORD    dwflags,
  [in] LPVOID   lParam
);

Parametri

[in] lpszDeviceName

Puntatore a una stringa con terminazione Null che specifica il dispositivo di visualizzazione la cui modalità grafica cambierà. Vengono visualizzati solo i nomi dei dispositivi restituiti da EnumDisplayDevices sono validi. Per altre informazioni sui nomi associati a questi dispositivi di visualizzazione, vedere EnumDisplayDevices.

Il parametro lpszDeviceName può essere NULL. Un valore NULL specifica il dispositivo di visualizzazione predefinito. Il dispositivo predefinito può essere determinato chiamando EnumDisplayDevices e verificando il flag di DISPLAY_DEVICE_PRIMARY_DEVICE.

[in] lpDevMode

Puntatore a una struttura DEVMODE che descrive la nuova modalità grafica. Se lpDevMode è NULL, verranno usati tutti i valori attualmente presenti nel Registro di sistema per l'impostazione di visualizzazione. Il passaggio di NULL per il parametro lpDevMode e 0 per il parametro dwFlags è il modo più semplice per tornare alla modalità predefinita dopo una modifica della modalità dinamica.

Il membro dmSize deve essere inizializzato in byte della struttura DEVMODE. Il membro dmDriverExtra deve essere inizializzato per indicare il numero di byte di dati del driver privato dopo la struttura DEVMODE. Inoltre, è possibile usare uno dei membri seguenti della struttura DEVMODE.

Membro	Significato
dmBitsPerPel	Bit per pixel
dmPelsWidth	Larghezza pixel
dmPelsHeight	Altezza pixel
dmDisplayFlags	Flag di modalità
dmDisplayFrequency	Frequenza modalità
dmPosition	Posizione del dispositivo in una configurazione multi-monitor.

Oltre a usare uno o più dei membri DEVMODE precedenti, è necessario impostare uno o più dei valori seguenti nel dmFields membro per modificare le impostazioni di visualizzazione.

Valore	Significato
DM_BITSPERPEL	Usare il valore dmBitsPerPel .
DM_PELSWIDTH	Usare il valore dmPelsWidth .
DM_PELSHEIGHT	Usare il valore dmPelsHeight .
DM_DISPLAYFLAGS	Usare il valore dmDisplayFlags .
DM_DISPLAYFREQUENCY	Usare il valore dmDisplayFrequency .
DM_POSITION	Usare il valore dmPosition .

hwnd

Riservato; deve essere null.

[in] dwflags

Indica la modalità grafica da modificare. Questo parametro può essere uno dei valori seguenti.

Valore	Significato
0	La modalità grafica per la schermata corrente verrà modificata in modo dinamico.
CDS_FULLSCREEN	La modalità è temporanea in natura. Se si passa a e da un altro desktop, questa modalità non verrà reimpostata.
CDS_GLOBAL	Le impostazioni verranno salvate nell'area delle impostazioni globali in modo che influiscano su tutti gli utenti del computer. In caso contrario, vengono modificate solo le impostazioni per l'utente. Questo flag è valido solo se specificato con il flag CDS_UPDATEREGISTRY.
CDS_NORESET	Le impostazioni verranno salvate nel Registro di sistema, ma non saranno effettive. Questo flag è valido solo se specificato con il flag CDS_UPDATEREGISTRY.
CDS_RESET	Le impostazioni devono essere modificate, anche se le impostazioni richieste corrispondono alle impostazioni correnti.
CDS_SET_PRIMARY	Questo dispositivo diventerà il dispositivo primario.
CDS_TEST	Il sistema verifica se è possibile impostare la modalità grafica richiesta.
CDS_UPDATEREGISTRY	La modalità grafica per la schermata corrente verrà modificata dinamicamente e la modalità grafica verrà aggiornata nel Registro di sistema. Le informazioni sulla modalità vengono archiviate nel profilo UTENTE.
CDS_VIDEOPARAMETERS	Se impostato, il parametro lParam è un puntatore a una struttura VIDEOPARAMETERS .
CDS_ENABLE_UNSAFE_MODES	Abilita le modifiche delle impostazioni alle modalità grafiche non sicure.
CDS_DISABLE_UNSAFE_MODES	Disabilita le modifiche delle impostazioni alle modalità grafiche non sicure.

Specificando CDS_TEST consente a un'applicazione di determinare quali modalità grafiche sono effettivamente valide, senza che il sistema venga modificato.

Se viene specificato CDS_UPDATEREGISTRY ed è possibile modificare la modalità grafica in modo dinamico, le informazioni vengono archiviate nel Registro di sistema e DISP_CHANGE_SUCCESSFUL viene restituito. Se non è possibile modificare la modalità grafica in modo dinamico, le informazioni vengono archiviate nel Registro di sistema e vengono restituite DISP_CHANGE_RESTART.

Se viene specificato CDS_UPDATEREGISTRY e le informazioni non possono essere archiviate nel Registro di sistema, la modalità grafica non viene modificata e DISP_CHANGE_NOTUPDATED viene restituita.

[in] lParam

Se dwFlags è CDS_VIDEOPARAMETERS, lParam è un puntatore a una struttura VIDEOPARAMETERS. In caso contrario, lParam deve essere NULL.

Valore restituito

La funzione ChangeDisplaySettingsEx restituisce uno dei valori seguenti.

Codice restituito	Descrizione
DISP_CHANGE_SUCCESSFUL	La modifica delle impostazioni ha avuto esito positivo.
DISP_CHANGE_BADDUALVIEW	La modifica delle impostazioni non è riuscita perché il sistema è in grado di supportare DualView.
DISP_CHANGE_BADFLAGS	È stato passato un set di flag non valido.
DISP_CHANGE_BADMODE	La modalità grafica non è supportata.
DISP_CHANGE_BADPARAM	È stato passato un parametro non valido. Può includere un flag o una combinazione di flag non validi.
DISP_CHANGE_FAILED	Il driver di visualizzazione non è riuscito nella modalità grafica specificata.
DISP_CHANGE_NOTUPDATED	Impossibile scrivere le impostazioni nel Registro di sistema.
DISP_CHANGE_RESTART	Per il funzionamento della modalità grafica, è necessario riavviare il computer.

Osservazioni

Per assicurarsi che la struttura DEVMODE passata a ChangeDisplaySettingsEx sia valida e contenga solo i valori supportati dal driver di visualizzazione, usare il DEVMODE restituito dalla funzione EnumDisplaySettings .

Quando si aggiunge un monitor di visualizzazione a un sistema a più monitor a livello di codice, impostare DEVMODE.dmFields su DM_POSITION e specificare una posizione (in DEVMODE.dmPosition) per il monitor che si sta aggiungendo adiacente ad almeno un pixel dell'area di visualizzazione di un monitor esistente. Per scollegare il monitoraggio, impostare DEVMODE.dmFields su DM_POSITION ma impostare DEVMODE.dmPelsWidth e DEVMODE.dmPelsHeight su zero. Per altre informazioni, vedere più monitor.

Quando la modalità di visualizzazione viene modificata in modo dinamico, il messaggio di WM_DISPLAYCHANGE viene inviato a tutte le applicazioni in esecuzione con i parametri del messaggio seguenti.

Parametri	Significato
wParam	Nuovi bit per pixel
LOWORD(lParam)	Nuova larghezza pixel
HIWORD(lParam)	Nuova altezza pixel

Per modificare le impostazioni per più di una visualizzazione contemporaneamente, chiamare prima ChangeDisplaySettingsEx per ogni dispositivo singolarmente per aggiornare il Registro di sistema senza applicare le modifiche. Chiamare quindi ChangeDisplaySettingsEx ancora, con un dispositivo NULL per applicare le modifiche. Ad esempio, per modificare le impostazioni per due visualizzazioni, eseguire le operazioni seguenti:


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

Virtualizzazione DPI

Questa API non partecipa alla virtualizzazione DPI. L'input specificato è sempre in termini di pixel fisici e non è correlato al contesto chiamante.

Nota

L'intestazione winuser.h definisce ChangeDisplaySettingsEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winuser.h (include Windows.h)
libreria	User32.lib
dll	User32.dll
set di API	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (introdotto in Windows 10, versione 10.0.14393)