ChangeDisplaySettingsExA 函式 (winuser.h)

發行項
03/13/2024

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

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

語法

LONG ChangeDisplaySettingsExA(
  [in] LPCSTR   lpszDeviceName,
  [in] DEVMODEA *lpDevMode,
       HWND     hwnd,
  [in] DWORD    dwflags,
  [in] LPVOID   lParam
);

參數

[in] lpszDeviceName

Null 終止字串的指標，指定圖形模式將會變更的顯示裝置。只有 EnumDisplayDevices 傳回的裝置名稱才有效。如需這些顯示裝置相關名稱的詳細資訊，請參閱 EnumDisplayDevices 。

lpszDeviceName 參數可以是 NULL。 NULL 值會指定預設的顯示裝置。您可以呼叫 EnumDisplayDevices 並檢查DISPLAY_DEVICE_PRIMARY_DEVICE旗標來判斷預設裝置。

[in] lpDevMode

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

dmSize 成員必須初始化為 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 值。

hwnd

保留;必須是 NULL。

[in] dwflags

指出圖形模式的變更方式。此參數可以是下列其中一個值。

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

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

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

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

[in] lParam

如果 dwFlags是CDS_VIDEOPARAMETERS，lParam 是 VIDEOPARAMETERS 結構的指標。否則 lParam 必須是 NULL。

傳回值

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

傳回碼	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	計算機必須重新啟動，圖形模式才能運作。

備註

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

以程序設計方式將顯示器監視器新增至多部監視器系統時，請將 DEVMODE.dmFields 設定為DM_POSITION，並針對您要新增的監視器指定位置 () ，該位置與您現有監視器的顯示區域至少一個像素相鄰。若要卸離監視器，請將 DEVMODE.dmFields 設定為 DM_POSITION，但將 DEVMODE.dmPelsWidth 和 DEVMODE.dmPelsHeight 設定為零。如需詳細資訊，請參閱多個顯示監視器。

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

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

若要同時變更多個顯示器的設定，請先為每個裝置個別呼叫 ChangeDisplaySettingsEx 來更新登錄，而不套用變更。然後使用 NULL 裝置再次呼叫 ChangeDisplaySettingsEx，以套用變更。例如，若要變更兩個顯示器的設定，請執行下列動作：


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 虛擬化

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

注意

winuser.h 標頭會根據 UNICODE 預處理器常數的定義，將 ChangeDisplaySettingsEx 定義為別名，自動選取此函式的 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 版)