Fungsi ChangeDisplaySettingsA (winuser.h)

Artikel
08/27/2023

Fungsi ChangeDisplaySettings mengubah pengaturan perangkat tampilan default ke mode grafik yang ditentukan.

Untuk mengubah pengaturan perangkat tampilan tertentu, gunakan fungsi ChangeDisplaySettingsEx .

Catatan Aplikasi yang Anda rancang untuk menargetkan Windows 8 dan nantinya 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 ChangeDisplaySettingsA(
  [in] DEVMODEA *lpDevMode,
  [in] DWORD    dwFlags
);

Parameter

[in] lpDevMode

Penunjuk ke struktur DEVMODE yang menjelaskan mode grafis baru. Jika lpDevMode adalah 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 perubahan mode dinamis.

Anggota dmSizeDEVMODE harus diinisialisasi ke ukuran, dalam byte, dari struktur DEVMODE . Anggota dmDriverExtra dari DEVMODE harus diinisialisasi untuk menunjukkan jumlah byte data driver privat setelah struktur DEVMODE . Selain itu, Anda dapat menggunakan salah satu atau semua 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 .

[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 ketika ditentukan dengan bendera CDS_UPDATEREGISTRY.
CDS_NORESET	Pengaturan akan disimpan dalam registri, tetapi tidak akan berlaku. Bendera ini hanya valid ketika 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 grafik untuk layar saat ini akan diubah secara dinamis dan mode grafis akan diperbarui dalam registri. Informasi mode disimpan di profil USER.

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

Jika CDS_UPDATEREGISTRY ditentukan dan dimungkinkan untuk mengubah mode grafis secara dinamis, informasi disimpan dalam registri dan DISP_CHANGE_SUCCESSFUL dikembalikan. Jika tidak dimungkinkan untuk mengubah mode grafis secara dinamis, informasi disimpan dalam 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.

Mengembalikan nilai

Fungsi ChangeDisplaySettings 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 ChangeDisplaySettings valid dan hanya berisi nilai yang didukung oleh driver tampilan, gunakan DEVMODE yang dikembalikan oleh fungsi EnumDisplaySettings .

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

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 ChangeDisplaySettings 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 (termasuk 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)