ChangeDisplaySettingsExA 函式 (winuser.h)
ChangeDisplaySettingsEx 函式會將指定之顯示裝置的設定變更為指定的圖形模式。
語法
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 結構的任何下列成員。
| member | 意義 |
|---|---|
| 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
指出圖形模式的變更方式。 此參數可以是下列其中一個值。
| 值 | 意義 |
|---|---|
|
目前畫面的圖形模式將會動態變更。 |
|
模式本質上是暫時性的。
如果您從另一個桌面變更為 和 ，將不會重設此模式。 |
|
這些設定會儲存在全域設定區域中，以便影響電腦上的所有使用者。 否則，只會修改使用者的設定。 只有在使用 CDS_UPDATEREGISTRY 旗標指定時，這個旗標才有效。 |
|
設定將會儲存在登錄中，但不會生效。 只有在使用 CDS_UPDATEREGISTRY 旗標指定時，這個旗標才有效。 |
|
即使要求的設定與目前的設定相同，也應該變更設定。 |
|
此裝置將會成為主要裝置。 |
|
系統會測試是否可設定要求的圖形模式。 |
|
目前畫面的圖形模式將會動態變更，而且圖形模式將會在登錄中更新。 模式資訊會儲存在使用者設定檔中。 |
|
設定時， lParam 參數是 VIDEOPARAMETERS 結構的指標。 |
|
啟用不安全圖形模式的設定變更。 |
|
停用不安全圖形模式的設定變更。 |
指定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 函式會傳回下列其中一個值。
| 傳回碼 | 描述 |
|---|---|
|
設定變更成功。 |
|
設定變更失敗，因為系統具備 DualView 功能。 |
|
傳入了一組不正確旗標。 |
|
不支援圖形模式。 |
|
傳入了不正確參數。 這可以包含不正確旗標或旗標組合。 |
|
顯示驅動程式失敗指定的圖形模式。 |
|
無法將設定寫入登錄。 |
|
電腦必須重新開機，圖形模式才能運作。 |
備註
若要確保傳遞至ChangeDisplaySettingsEx 的DEVMODE結構有效，而且只包含顯示驅動程式所支援的值，請使用EnumDisplaySettings函式傳回的DEVMODE。
以程式設計方式將顯示器監視器新增至多部監視器系統時，請將 DEVMODE.dmFields 設定為 DM_POSITION，並針對您要新增的監視器指定位於 DEVMODE.dmPosition) (的位置，該位置與您現有監視器的顯示區域至少一個圖元相鄰。 若要卸離監視器，請將 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 版) |