共用方式為


ChangeDisplaySettingsExA 函式 (winuser.h)

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 參數可以是 NULLNULL 值會指定預設的顯示裝置。 您可以呼叫 EnumDisplayDevices 並檢查DISPLAY_DEVICE_PRIMARY_DEVICE旗標來判斷預設裝置。

[in] lpDevMode

描述新圖形模式 之 DEVMODE 結構的指標。 如果 lpDevModeNULL,則登錄中目前的所有值都會用於顯示設定。 傳遞 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

如果 dwFlagsCDS_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.dmPelsWidthDEVMODE.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 版)

另請參閱

CreateDC

DEVMODE

裝置內容函式

裝置內容概觀

EnumDisplayDevices

EnumDisplaySettings

VIDEOPARAMETERS

WM_DISPLAYCHANGE