ChangeDisplaySettingsA 函式 (winuser.h)

發行項
03/04/2024

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

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

注意您設計以 Windows 8 和更新版本為目標的應用程式無法再查詢或設定每個圖元少於 32 位的顯示模式， (bpp) ;這些作業將會失敗。這些應用程式具有以 Windows 8 為目標的相容性指令清單。 Windows 8 仍然支持沒有 Windows 8 指令清單所建置傳統型應用程式的8位和16位色彩模式;Windows 8 模擬這些模式，但仍以32位色彩模式執行。

語法

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

參數

[in] lpDevMode

描述新圖形模式之 DEVMODE 結構的指標。如果 lpDevMode 為 NULL，則登錄中目前的所有值都會用於顯示設定。傳遞 lpDevMode 參數的 NULL，而 dwFlags 參數為 0 是動態模式變更後傳回預設模式的最簡單方式。

DEVMODE 的 dmSize 成員必須初始化為 DEVMODE 結構的大小，以位元組為單位。必須初始化 DEVMODE 的 dmDriverExtra 成員，以指示 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 函式會傳回下列其中一個值。

傳回碼	Description
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 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winuser.h (包括 Windows.h)
程式庫	User32.lib
Dll	User32.dll
API 集合	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (於 Windows 10 10.0.14393 版)