Funzione ChangeDisplaySettingsA (winuser.h)

Articolo
08/27/2023

La funzione ChangeDisplaySettings modifica le impostazioni del dispositivo di visualizzazione predefinito alla modalità grafica specificata.

Per modificare le impostazioni di un dispositivo di visualizzazione specificato, usare la funzione ChangeDisplaySettingsEx.

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 ChangeDisplaySettingsA(
  [in] DEVMODEA *lpDevMode,
  [in] DWORD    dwFlags
);

Parametri

[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 di DEVMODE deve essere inizializzato in byte della struttura DEVMODE. È necessario inizializzare il membro dmDriverExtra di DEVMODE per indicare il numero di byte di dati del driver privato dopo la struttura DEVMODE. Inoltre, è possibile usare uno o tutti i 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 membro dmFields per modificare l'impostazione 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 .

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

Specificare CDS_TEST consente a un'applicazione di determinare quali modalità grafiche sono effettivamente valide, senza che il sistema cambi in tale modalità grafica.

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.

Valore restituito

La funzione ChangeDisplaySettings 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 ChangeDisplaySettings sia valida e contenga solo i valori supportati dal driver di visualizzazione, usare il DEVMODE restituito dalla funzione EnumDisplaySettings .

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

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 ChangeDisplaySettings 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)