Fungsi ChangeDisplaySettingsA (winuser.h)

Artikel
11/20/2024

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

Untuk mengubah pengaturan perangkat tampilan tertentu, gunakan fungsi ChangeDisplaySettingsEx.

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 ChangeDisplaySettingsA(
  [in] DEVMODEA *lpDevMode,
  [in] DWORD    dwFlags
);

Parameter

[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.

dmSize anggota DEVMODE harus diinisialisasi ke ukuran, dalam byte, dari struktur DEVMODE . dmDriverExtra anggota 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	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 anggota dmFields 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 .

[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.

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 grafis tidak diubah dan DISP_CHANGE_NOTUPDATED dikembalikan.

Mengembalikan nilai

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

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

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 ChangeDisplaySettings 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

ChangeDisplaySettingsEx

CreateDC

DEVMODE

Fungsi Konteks Perangkat

Gambaran Umum Konteks Perangkat

EnumDisplayDevices

EnumDisplaySettings

WM_DISPLAYCHANGE

Bagikan melalui