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 結構的任何下列成員。
| 成員 | 意義 |
|---|---|
| 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 函式會傳回下列其中一個值。
| 傳回碼 | Description |
|---|---|
|
設定變更成功。 |
|
設定變更失敗，因為系統具備 DualView 功能。 |
|
傳入了一組無效的旗標。 |
|
不支援圖形模式。 |
|
傳入了無效的參數。 這可以包含無效的旗標或旗標組合。 |
|
顯示驅動程式失敗指定的圖形模式。 |
|
無法將設定寫入登錄。 |
|
計算機必須重新啟動，圖形模式才能運作。 |
備註
若要確保傳遞至 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 版) |