ChangeDisplaySettingsA 函式（winuser.h）

發行項
11/20/2024

ChangeDisplaySettings 函式會將預設顯示裝置的設定變更為指定的圖形模式。

若要變更指定顯示裝置的設定，請使用 ChangeDisplaySettingsEx 函式。

請注意，您設計以 Windows 8 和更新版本為目標的 app 無法再查詢或設定每圖元小於 32 位的顯示模式（bpp）：這些作業將會失敗。這些應用程式具有以 Windows 8 為目標的相容性指令清單。 Windows 8 仍然支援 8 位和 16 位色彩模式，適用於在沒有 Windows 8 指令清單的情況下建置之傳統型應用程式;Windows 8 會模擬這些模式，但仍以 32 位色彩模式執行。

語法

LONG ChangeDisplaySettingsA(
  [in] DEVMODEA *lpDevMode,
  [in] DWORD    dwFlags
);

參數

[in] lpDevMode

描述新圖形模式之 DEVMODE 結構的指標。如果 lpDevModeNULL，則登錄中目前的所有值都會用於顯示設定。針對 lpDevMode 參數傳遞 NULL，以及 dwFlags 參數的 0，是動態模式變更后最容易回到預設模式的方法。

dmSizeDEVMODE 的成員必須初始化為 DEVMODE 結構的大小。 dmDriverExtraDEVMODE 的成員必須初始化，以指出 DEVMODE 結構之後的私人驅動程式數據位元組數目。此外，您可以使用下列 DEVMODE 結構的任何或所有成員。

成員	意義
dmBitsPerPel	每個像素的位數
dmPelsWidth	圖元寬度
dmPelsHeight	圖元高度
dmDisplayFlags	模式旗標
dmDisplayFrequency	模式頻率
dmPosition	裝置在多監視器設定中的位置。

除了使用上述一或多個 DEVMODE 成員之外，您也必須在 dmFields 成員中設定下列一或多個值，以變更顯示設定。

價值	意義
DM_BITSPERPEL	使用 dmBitsPerPel 值。
DM_PELSWIDTH	使用 dmPelsWidth 值。
DM_PELSHEIGHT	使用 dmPelsHeight 值。
DM_DISPLAYFLAGS	使用 dmDisplayFlags 值。
DM_DISPLAYFREQUENCY	使用 dmDisplayFrequency 值。
DM_POSITION	使用 dmPosition 值。

[in] dwFlags

指出圖形模式應該如何變更。此參數可以是下列其中一個值。

價值	意義
0	目前畫面的圖形模式將會動態變更。
CDS_FULLSCREEN	模式本質上是暫時的。如果您從另一個桌面變更為和，將不會重設此模式。
CDS_GLOBAL	這些設定將會儲存在全域設定區域中，以便影響計算機上的所有使用者。否則，只會修改用戶的設定。只有在使用 CDS_UPDATEREGISTRY 旗標指定時，這個旗標才有效。
CDS_NORESET	這些設定將會儲存在登錄中，但不會生效。只有在使用 CDS_UPDATEREGISTRY 旗標指定時，這個旗標才有效。
CDS_RESET	即使要求的設定與目前的設定相同，也應該變更設定。
CDS_SET_PRIMARY	此裝置將成為主要裝置。
CDS_TEST	系統會測試是否可設定要求的圖形模式。
CDS_UPDATEREGISTRY	目前畫面的圖形模式將會動態變更，而圖形模式將會在登錄中更新。模式資訊會儲存在使用者配置檔中。

指定CDS_TEST可讓應用程式判斷哪些圖形模式實際上有效，而不會讓系統變更為該圖形模式。

如果指定了CDS_UPDATEREGISTRY，而且可以動態變更圖形模式，則會將資訊儲存在登錄中，並傳回DISP_CHANGE_SUCCESSFUL。如果無法動態變更圖形模式，則會將資訊儲存在登錄中，並傳回DISP_CHANGE_RESTART。

如果指定了CDS_UPDATEREGISTRY，而且無法將資訊儲存在登錄中，圖形模式就不會變更，而且會傳回DISP_CHANGE_NOTUPDATED。

傳回值

ChangeDisplaySettings 函式會傳回下列其中一個值。

傳回碼	描述
DISP_CHANGE_SUCCESSFUL	設定變更成功。
DISP_CHANGE_BADDUALVIEW	設定變更失敗，因為系統具備 DualView 功能。
DISP_CHANGE_BADFLAGS	傳入無效的旗標集。
DISP_CHANGE_BADMODE	不支援圖形模式。
DISP_CHANGE_BADPARAM	傳入無效的參數。這可以包含無效的旗標或旗標組合。
DISP_CHANGE_FAILED	顯示驅動程式失敗指定的圖形模式。
DISP_CHANGE_NOTUPDATED	無法將設定寫入登錄。
DISP_CHANGE_RESTART	計算機必須重新啟動，圖形模式才能運作。

言論

若要確保傳遞至 ChangeDisplaySettings 結構 DEVMODE 有效，且只包含顯示驅動程式所支援的值，請使用 EnumDisplaySettings 函式所傳回的 DEVMODE。

動態變更顯示模式時，WM_DISPLAYCHANGE 訊息會傳送至所有執行中的應用程式，並具有下列訊息參數。

參數	意義
wParam	每個圖元的新位
LOWORD（lParam）	新的像素寬度
HIWORD（lParam）	新的圖元高度

DPI 虛擬化

此 API 不會參與 DPI 虛擬化。指定的輸入一律以實體圖元為單位，且與呼叫內容無關。

注意

winuser.h 標頭會將 ChangeDisplaySettings 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平臺	窗戶
標頭	winuser.h （包括 Windows.h）
連結庫	User32.lib
DLL	User32.dll
API 集	ext-ms-win-ntuser-sysparams-ext-l1-1-1 （在 Windows 10 版本 10.0.14393 中引進）