Fungsi ChangeDisplaySettingsExA (winuser.h)

Artikel
03/15/2023

Fungsi ChangeDisplaySettingsEx mengubah pengaturan perangkat tampilan yang ditentukan ke mode grafik yang ditentukan.

Catatan Aplikasi yang Anda desain untuk menargetkan Windows 8 dan yang lebih baru tidak dapat lagi mengkueri atau mengatur mode tampilan yang kurang dari 32 bit per piksel (bpp); operasi ini akan gagal. Aplikasi ini memiliki manifes kompatibilitas yang menargetkan Windows 8. Windows 8 masih mendukung mode warna 8-bit dan 16-bit untuk aplikasi desktop yang dibangun tanpa manifes Windows 8; Windows 8 mengemulasi mode ini tetapi masih berjalan dalam mode warna 32-bit.

Sintaks

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

Parameter

[in] lpszDeviceName

Penunjuk ke string yang dihentikan null yang menentukan perangkat tampilan yang mode grafiknya akan berubah. Hanya tampilkan nama perangkat seperti yang dikembalikan oleh EnumDisplayDevices yang valid. Lihat EnumDisplayDevices untuk informasi lebih lanjut tentang nama yang terkait dengan perangkat tampilan ini.

Parameter lpszDeviceName dapat berupa NULL. Nilai NULL menentukan perangkat tampilan default. Perangkat default dapat ditentukan dengan memanggil EnumDisplayDevices dan memeriksa bendera DISPLAY_DEVICE_PRIMARY_DEVICE.

[in] lpDevMode

Penunjuk ke struktur DEVMODE yang menjelaskan mode grafis baru. Jika lpDevModeADALAH NULL, semua nilai yang saat ini ada di registri akan digunakan untuk pengaturan tampilan. Meneruskan NULL untuk parameter lpDevMode dan 0 untuk parameter dwFlags adalah cara termudah untuk kembali ke mode default setelah mode dinamis berubah.

Anggota dmSize harus diinisialisasi ke ukuran, dalam byte, dari struktur DEVMODE . Anggota dmDriverExtra harus diinisialisasi untuk menunjukkan jumlah byte data driver privat setelah struktur DEVMODE . Selain itu, Anda dapat menggunakan salah satu anggota struktur DEVMODE berikut.

Anggota	Makna
dmBitsPerPel	Bit per piksel
dmPelsWidth	Lebar piksel
dmPelsHeight	Tinggi piksel
dmDisplayFlags	Bendera mode
dmDisplayFrequency	Frekuensi mode
dmPosition	Posisi perangkat dalam konfigurasi multi-monitor.

Selain menggunakan satu atau beberapa anggota DEVMODE sebelumnya, Anda juga harus mengatur satu atau beberapa nilai berikut di anggota dmFields untuk mengubah pengaturan tampilan.

Nilai	Makna
DM_BITSPERPEL	Gunakan nilai dmBitsPerPel .
DM_PELSWIDTH	Gunakan nilai dmPelsWidth .
DM_PELSHEIGHT	Gunakan nilai dmPelsHeight .
DM_DISPLAYFLAGS	Gunakan nilai dmDisplayFlags .
DM_DISPLAYFREQUENCY	Gunakan nilai dmDisplayFrequency .
DM_POSITION	Gunakan nilai dmPosition .

hwnd

Dipesan; harus NULL.

[in] dwflags

Menunjukkan bagaimana mode grafis harus diubah. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
0	Mode grafik untuk layar saat ini akan diubah secara dinamis.
CDS_FULLSCREEN	Mode ini bersifat sementara. Jika Anda mengubah ke dan dari desktop lain, mode ini tidak akan direset.
CDS_GLOBAL	Pengaturan akan disimpan di area pengaturan global sehingga akan memengaruhi semua pengguna pada komputer. Jika tidak, hanya pengaturan untuk pengguna yang dimodifikasi. Bendera ini hanya valid jika ditentukan dengan bendera CDS_UPDATEREGISTRY.
CDS_NORESET	Pengaturan akan disimpan di registri, tetapi tidak akan berlaku. Bendera ini hanya valid jika ditentukan dengan bendera CDS_UPDATEREGISTRY.
CDS_RESET	Pengaturan harus diubah, meskipun pengaturan yang diminta sama dengan pengaturan saat ini.
CDS_SET_PRIMARY	Perangkat ini akan menjadi perangkat utama.
CDS_TEST	Sistem menguji apakah mode grafis yang diminta dapat diatur.
CDS_UPDATEREGISTRY	Mode grafis untuk layar saat ini akan diubah secara dinamis dan mode grafis akan diperbarui dalam registri. Informasi mode disimpan di profil USER.
CDS_VIDEOPARAMETERS	Saat diatur, parameter lParam adalah penunjuk ke struktur VIDEOPARAMETERS .
CDS_ENABLE_UNSAFE_MODES	Mengaktifkan perubahan pengaturan ke mode grafis yang tidak aman.
CDS_DISABLE_UNSAFE_MODES	Menonaktifkan perubahan pengaturan ke mode grafis yang tidak aman.

Menentukan CDS_TEST memungkinkan aplikasi menentukan mode grafis mana yang benar-benar valid, tanpa menyebabkan sistem berubah.

Jika CDS_UPDATEREGISTRY ditentukan dan dimungkinkan untuk mengubah mode grafis secara dinamis, informasi disimpan dalam registri dan DISP_CHANGE_SUCCESSFUL dikembalikan. Jika tidak memungkinkan untuk mengubah mode grafis secara dinamis, informasi disimpan di registri dan DISP_CHANGE_RESTART dikembalikan.

Jika CDS_UPDATEREGISTRY ditentukan dan informasi tidak dapat disimpan dalam registri, mode grafik tidak diubah dan DISP_CHANGE_NOTUPDATED dikembalikan.

[in] lParam

Jika dwFlagsCDS_VIDEOPARAMETERS, lParam adalah penunjuk ke struktur VIDEOPARAMETERS . Jika tidak , lParam harus NULL.

Mengembalikan nilai

Fungsi ChangeDisplaySettingsEx mengembalikan salah satu nilai berikut.

Menampilkan kode	Deskripsi
DISP_CHANGE_SUCCESSFUL	Perubahan pengaturan berhasil.
DISP_CHANGE_BADDUALVIEW	Perubahan pengaturan tidak berhasil karena sistem berkemampuan DualView.
DISP_CHANGE_BADFLAGS	Sekumpulan bendera yang tidak valid diteruskan.
DISP_CHANGE_BADMODE	Mode grafik tidak didukung.
DISP_CHANGE_BADPARAM	Parameter yang tidak valid diteruskan. Ini dapat mencakup bendera yang tidak valid atau kombinasi bendera.
DISP_CHANGE_FAILED	Pengandar tampilan gagal dalam mode grafis yang ditentukan.
DISP_CHANGE_NOTUPDATED	Tidak dapat menulis pengaturan ke registri.
DISP_CHANGE_RESTART	Komputer harus dimulai ulang agar mode grafis berfungsi.

Keterangan

Untuk memastikan bahwa struktur DEVMODE yang diteruskan ke ChangeDisplaySettingsEx valid dan hanya berisi nilai yang didukung oleh driver tampilan, gunakan DEVMODE yang dikembalikan oleh fungsi EnumDisplaySettings .

Saat menambahkan monitor tampilan ke sistem multi-monitor secara terprogram, atur DEVMODE.dmFields ke DM_POSITION dan tentukan posisi (di DEVMODE.dmPosition) untuk monitor yang Anda tambahkan yang berdekatan dengan setidaknya satu piksel area tampilan monitor yang ada. Untuk melepaskan monitor, atur DEVMODE.dmFields ke DM_POSITION tetapi atur DEVMODE.dmPelsWidth dan DEVMODE.dmPelsHeight ke nol. Untuk informasi selengkapnya, lihat Beberapa Monitor Tampilan.

Ketika mode tampilan diubah secara dinamis, pesan WM_DISPLAYCHANGE dikirim ke semua aplikasi yang sedang berjalan dengan parameter pesan berikut.

Parameter	Makna
wParam	Bit baru per piksel
LOWORD(lParam)	Lebar piksel baru
HIWORD(lParam)	Tinggi piksel baru

Untuk mengubah pengaturan untuk lebih dari satu tampilan secara bersamaan, pertama-tama panggil ChangeDisplaySettingsEx untuk setiap perangkat satu per satu untuk memperbarui registri tanpa menerapkan perubahan. Kemudian panggil ChangeDisplaySettingsEx sekali lagi, dengan perangkat NULL , untuk menerapkan perubahan. Misalnya, untuk mengubah pengaturan untuk dua tampilan, lakukan hal berikut:


ChangeDisplaySettingsEx (lpszDeviceName1, lpDevMode1, NULL, (CDS_UPDATEREGISTRY | CDS_NORESET), NULL);
ChangeDisplaySettingsEx (lpszDeviceName2, lpDevMode2, NULL, (CDS_UPDATEREGISTRY | CDS_NORESET), NULL);
ChangeDisplaySettingsEx (NULL, NULL, NULL, 0, NULL);

Virtualisasi DPI

API ini tidak berpartisipasi dalam virtualisasi DPI. Input yang diberikan selalu dalam hal piksel fisik, dan tidak terkait dengan konteks panggilan.

Catatan

Header winuser.h mendefinisikan ChangeDisplaySettingsEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	winuser.h (sertakan Windows.h)
Pustaka	User32.lib
DLL	User32.dll
Set API	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (diperkenalkan dalam Windows 10, versi 10.0.14393)