Fungsi ChangeDisplaySettingsExA (winuser.h)

Fungsi ChangeDisplaySettingsEx mengubah pengaturan perangkat tampilan yang ditentukan ke mode grafis 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 menimulasi mode ini tetapi masih berjalan dalam mode warna 32-bit.
 

Sintaksis

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 grafisnya 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 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 lpDevModeNULL, 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 Arti
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 dmFields anggota untuk mengubah pengaturan tampilan.

Nilai Arti
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 Arti
0
 Mode grafis 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 diatur ulang.
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 dalam registri, tetapi tidak akan berlaku. Bendera ini hanya valid jika ditentukan dengan bendera CDS_UPDATEREGISTRY.
CDS_RESET
 Pengaturan harus diubah, bahkan jika 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 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 grafis tidak diubah dan DISP_CHANGE_NOTUPDATED dikembalikan.

[in] lParam

Jika dwFlags CDS_VIDEOPARAMETERS, lParam adalah penunjuk ke struktur VIDEOPARAMETERS . Jika tidak, lParam harus null.

Mengembalikan nilai

Fungsi ChangeDisplaySettingsEx mengembalikan salah satu nilai berikut.

Mengembalikan kode Deskripsi
DISP_CHANGE_SUCCESSFUL
 Perubahan pengaturan berhasil.
DISP_CHANGE_BADDUALVIEW
 Perubahan pengaturan tidak berhasil karena sistem mampu DualView.
DISP_CHANGE_BADFLAGS
 Sekumpulan bendera yang tidak valid diteruskan.
DISP_CHANGE_BADMODE
 Mode grafis 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.

Komentar

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

Saat menambahkan monitor tampilan ke sistem multi-monitor secara terprogram, atur DEVMODE.dmFields ke DM_POSITION dan tentukan posisi (dalam 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 Arti
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.

Nota

Header winuser.h mendefinisikan ChangeDisplaySettingsEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosedur 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

Syarat Nilai
klien minimum yang didukung Windows 2000 Professional [hanya aplikasi desktop]
server minimum yang didukung Windows 2000 Server [hanya aplikasi desktop]
Platform Target 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 di Windows 10, versi 10.0.14393)

Lihat juga

CreateDC

DEVMODE

Fungsi Konteks Perangkat

Gambaran Umum Konteks Perangkat

EnumDisplayDevices

EnumDisplaySettings

VIDEOPARAMETERS

WM_DISPLAYCHANGE

  • Last updated on