Fungsi SetWindowLongPtrA (winuser.h)

Artikel
07/21/2023

Mengubah atribut jendela yang ditentukan. Fungsi ini juga menetapkan nilai pada offset yang ditentukan dalam memori jendela tambahan.

Catatan Untuk menulis kode yang kompatibel dengan Windows versi 32-bit dan 64-bit, gunakan SetWindowLongPtr. Saat mengkompilasi untuk Windows 32-bit, SetWindowLongPtr didefinisikan sebagai panggilan ke fungsi SetWindowLong .

Sintaks

LONG_PTR SetWindowLongPtrA(
  [in] HWND     hWnd,
  [in] int      nIndex,
  [in] LONG_PTR dwNewLong
);

Parameter

[in] hWnd

Jenis: HWND

Handel ke jendela dan, secara tidak langsung, kelas tempat jendela berada. Fungsi SetWindowLongPtr gagal jika proses yang memiliki jendela yang ditentukan oleh parameter hWnd berada pada hak istimewa proses yang lebih tinggi dalam hierarki UIPI daripada proses tempat utas panggilan berada.

Windows XP/2000: Fungsi SetWindowLongPtr gagal jika jendela yang ditentukan oleh parameter hWnd bukan milik proses yang sama dengan utas panggilan.

[in] nIndex

Jenis: int

Offset berbasis nol ke nilai yang akan ditetapkan. Nilai yang valid berada dalam rentang nol hingga jumlah byte memori jendela tambahan, dikurangi ukuran LONG_PTR. Untuk mengatur nilai lain, tentukan salah satu nilai berikut.

Nilai	Makna
GWL_EXSTYLE -20	Mengatur gaya jendela yang diperluas baru.
GWLP_HINSTANCE -6	Mengatur handel instans aplikasi baru.
GWLP_ID -12	Mengatur pengidentifikasi baru jendela anak. Jendela tidak boleh berupa jendela tingkat atas.
GWL_STYLE -16	Mengatur gaya jendela baru.
GWLP_USERDATA -21	Mengatur data pengguna yang terkait dengan jendela. Data ini ditujukan untuk digunakan oleh aplikasi yang membuat jendela. Nilainya awalnya nol.
GWLP_WNDPROC -4	Mengatur alamat baru untuk prosedur jendela.

Nilai berikut juga tersedia saat parameter hWnd mengidentifikasi kotak dialog.

Nilai	Makna
DWLP_DLGPROC DWLP_MSGRESULT + sizeof(LRESULT)	Mengatur penunjuk baru ke prosedur kotak dialog.
DWLP_MSGRESULT 0	Mengatur nilai pengembalian pesan yang diproses dalam prosedur kotak dialog.
DWLP_USER DWLP_DLGPROC + sizeof(DLGPROC)	Mengatur informasi tambahan baru yang bersifat privat ke aplikasi, seperti handel atau penunjuk.

[in] dwNewLong

Jenis: LONG_PTR

Nilai pengganti.

Menampilkan nilai

Jenis: LONG_PTR

Jika fungsi berhasil, nilai yang dikembalikan adalah nilai sebelumnya dari offset yang ditentukan.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Jika nilai sebelumnya adalah nol dan fungsi berhasil, nilai yang dikembalikan adalah nol, tetapi fungsi tidak menghapus informasi kesalahan terakhir. Untuk menentukan keberhasilan atau kegagalan, hapus informasi kesalahan terakhir dengan memanggil SetLastError dengan 0, lalu panggil SetWindowLongPtr. Kegagalan fungsi akan ditunjukkan oleh nilai pengembalian nol dan hasil GetLastError yang bukan nol.

Keterangan

Data jendela tertentu di-cache, sehingga perubahan yang Anda buat menggunakan SetWindowLongPtr tidak akan berlaku sampai Anda memanggil fungsi SetWindowPos .

Jika Anda menggunakan SetWindowLongPtr dengan indeks GWLP_WNDPROC untuk mengganti prosedur jendela, prosedur jendela harus sesuai dengan panduan yang ditentukan dalam deskripsi fungsi panggilan balik WindowProc .

Jika Anda menggunakan SetWindowLongPtr dengan indeks DWLP_MSGRESULT untuk mengatur nilai pengembalian untuk pesan yang diproses oleh prosedur kotak dialog, prosedur kotak dialog harus mengembalikan TRUE langsung setelahnya. Jika tidak, jika Anda memanggil fungsi apa pun yang menghasilkan prosedur kotak dialog Anda menerima pesan jendela, pesan jendela berlapis dapat menimpa nilai pengembalian yang Anda tetapkan dengan menggunakan DWLP_MSGRESULT.

Memanggil SetWindowLongPtr dengan indeks GWLP_WNDPROC membuat subkelas kelas jendela yang digunakan untuk membuat jendela. Aplikasi dapat mensubkelas kelas sistem, tetapi tidak boleh subkelas kelas jendela yang dibuat oleh proses lain. Fungsi SetWindowLongPtr membuat subkelas jendela dengan mengubah prosedur jendela yang terkait dengan kelas jendela tertentu, menyebabkan sistem memanggil prosedur jendela baru alih-alih yang sebelumnya. Aplikasi harus meneruskan pesan apa pun yang tidak diproses oleh prosedur jendela baru ke prosedur jendela sebelumnya dengan memanggil CallWindowProc. Ini memungkinkan aplikasi untuk membuat rantai prosedur jendela.

Cadangkan memori jendela tambahan dengan menentukan nilai bukan nol di anggota cbWndExtra dari struktur WNDCLASSEX yang digunakan dengan fungsi RegisterClassEx .

Jangan panggil SetWindowLongPtr dengan indeks GWLP_HWNDPARENT untuk mengubah induk jendela anak. Sebagai gantinya, gunakan fungsi SetParent .

Jika jendela memiliki gaya kelas CS_CLASSDC atau CS_PARENTDC, jangan atur gaya jendela yang diperluas WS_EX_COMPOSITED atau WS_EX_LAYERED.

Memanggil SetWindowLongPtr untuk mengatur gaya pada progressbar akan mengatur ulang posisinya.

Catatan

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


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-windowclass-l1-1-0 (diperkenalkan di Windows 8)