Membuat fungsiWindowExA (winuser.h)

Artikel
03/15/2023

Membuat jendela tumpang tindih, pop-up, atau anak dengan gaya jendela yang diperluas; jika tidak, fungsi ini identik dengan fungsi CreateWindow . Untuk informasi selengkapnya tentang membuat jendela dan untuk deskripsi lengkap parameter lain dari CreateWindowEx, lihat CreateWindow.

Sintaks

HWND CreateWindowExA(
  [in]           DWORD     dwExStyle,
  [in, optional] LPCSTR    lpClassName,
  [in, optional] LPCSTR    lpWindowName,
  [in]           DWORD     dwStyle,
  [in]           int       X,
  [in]           int       Y,
  [in]           int       nWidth,
  [in]           int       nHeight,
  [in, optional] HWND      hWndParent,
  [in, optional] HMENU     hMenu,
  [in, optional] HINSTANCE hInstance,
  [in, optional] LPVOID    lpParam
);

Parameter

[in] dwExStyle

Jenis: DWORD

Gaya jendela yang diperluas dari jendela yang sedang dibuat. Untuk daftar nilai yang mungkin, lihat Gaya Jendela yang Diperluas.

[in, optional] lpClassName

Jenis: LPCTSTR

String null-terminated atau atom kelas yang dibuat oleh panggilan sebelumnya ke fungsi RegisterClass atau RegisterClassEx . Atom harus dalam kata urutan rendah dari lpClassName; kata urutan tinggi harus nol. Jika lpClassName adalah string, itu menentukan nama kelas jendela. Nama kelas dapat berupa nama apa pun yang terdaftar di RegisterClass atau RegisterClassEx, asalkan modul yang mendaftarkan kelas juga merupakan modul yang membuat jendela. Nama kelas juga dapat menjadi salah satu nama kelas sistem yang telah ditentukan sebelumnya.

[in, optional] lpWindowName

Jenis: LPCTSTR

Nama jendela. Jika gaya jendela menentukan bilah judul, judul jendela yang ditujukan ke lpWindowName ditampilkan di bilah judul. Saat menggunakan CreateWindow untuk membuat kontrol, seperti tombol, kotak centang, dan kontrol statis, gunakan lpWindowName untuk menentukan teks kontrol. Saat membuat kontrol statis dengan gaya SS_ICON , gunakan lpWindowName untuk menentukan nama atau pengidentifikasi ikon. Untuk menentukan pengidentifikasi, gunakan sintaks "#num".

[in] dwStyle

Jenis: DWORD

Gaya jendela yang sedang dibuat. Parameter ini bisa menjadi kombinasi dari nilai gaya jendela, ditambah gaya kontrol yang ditunjukkan di bagian Keterangan.

[in] X

Jenis: int

Posisi horizontal awal jendela. Untuk jendela tumpang tindih atau pop-up, parameter x adalah koordinat x awal sudut kiri atas jendela, dalam koordinat layar. Untuk jendela anak, x adalah koordinat x dari sudut kiri atas jendela relatif terhadap sudut kiri atas area klien jendela induk. Jika x diatur ke CW_USEDEFAULT, sistem memilih posisi default untuk sudut kiri atas jendela dan mengabaikan parameter y . CW_USEDEFAULT hanya berlaku untuk jendela yang tumpang tindih; jika ditentukan untuk jendela pop-up atau anak, parameter x dan y diatur ke nol.

[in] Y

Jenis: int

Posisi vertikal awal jendela. Untuk jendela yang tumpang tindih atau pop-up, parameter y adalah koordinat y awal sudut kiri atas jendela, dalam koordinat layar. Untuk jendela anak, y adalah koordinat y awal dari sudut kiri atas jendela anak relatif terhadap sudut kiri atas area klien jendela induk. Untuk kotak daftar y adalah koordinat y awal sudut kiri atas area klien kotak daftar relatif terhadap sudut kiri atas area klien jendela induk.

Jika jendela yang tumpang tindih dibuat dengan set bit gaya WS_VISIBLE dan parameter x diatur ke CW_USEDEFAULT, parameter y menentukan bagaimana jendela ditampilkan. Jika parameter yCW_USEDEFAULT, manajer jendela memanggil ShowWindow dengan bendera SW_SHOW setelah jendela dibuat. Jika parameter y adalah beberapa nilai lain, maka manajer jendela memanggil ShowWindow dengan nilai tersebut sebagai parameter nCmdShow .

[in] nWidth

Jenis: int

Lebar, di unit perangkat, dari jendela. Untuk jendela yang tumpang tindih, nWidth adalah lebar jendela, dalam koordinat layar, atau CW_USEDEFAULT. Jika nWidthCW_USEDEFAULT, sistem memilih lebar dan tinggi default untuk jendela; lebar default meluas dari koordinat x awal ke tepi kanan layar; tinggi default meluas dari koordinat y awal ke bagian atas area ikon. CW_USEDEFAULT hanya berlaku untuk jendela yang tumpang tindih; jika CW_USEDEFAULT ditentukan untuk jendela pop-up atau anak, parameter nWidth dan nHeight diatur ke nol.

[in] nHeight

Jenis: int

Tinggi, di unit perangkat, dari jendela. Untuk jendela yang tumpang tindih, nHeight adalah tinggi jendela, dalam koordinat layar. Jika parameter nWidth diatur ke CW_USEDEFAULT, sistem mengabaikan nHeight.

[in, optional] hWndParent

Jenis: HWND

Handel ke jendela induk atau pemilik jendela yang sedang dibuat. Untuk membuat jendela anak atau jendela yang dimiliki, berikan handel jendela yang valid. Parameter ini bersifat opsional untuk jendela pop-up.

Untuk membuat jendela khusus pesan, berikan HWND_MESSAGE atau handel ke jendela khusus pesan yang ada.

[in, optional] hMenu

Jenis: HMENU

Handel ke menu, atau menentukan pengidentifikasi jendela anak, tergantung pada gaya jendela. Untuk jendela tumpang tindih atau pop-up, hMenu mengidentifikasi menu yang akan digunakan dengan jendela; bisa NULL jika menu kelas akan digunakan. Untuk jendela anak, hMenu menentukan pengidentifikasi jendela anak, nilai bilangan bulat yang digunakan oleh kontrol kotak dialog untuk memberi tahu induknya tentang peristiwa. Aplikasi menentukan pengidentifikasi jendela anak; harus unik untuk semua jendela anak dengan jendela induk yang sama.

[in, optional] hInstance

Jenis: HINSTANCE

Handel ke instans modul yang akan dikaitkan dengan jendela.

[in, optional] lpParam

Jenis: LPVOID

Penunjuk ke nilai yang akan diteruskan ke jendela melalui struktur CREATESTRUCT (anggota lpCreateParams ) yang ditunjukkan oleh param lParam dari pesan WM_CREATE . Pesan ini dikirim ke jendela yang dibuat oleh fungsi ini sebelum kembali.

Jika aplikasi memanggil CreateWindow untuk membuat jendela klien MDI, lpParam harus menunjuk ke struktur CLIENTCREATESTRUCT . Jika jendela klien MDI memanggil CreateWindow untuk membuat jendela anak MDI, lpParam harus menunjuk ke struktur MDICREATESTRUCT . lpParam mungkin NULL jika tidak ada data tambahan yang diperlukan.

Mengembalikan nilai

Jenis: HWND

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke jendela baru.

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

Fungsi ini biasanya gagal karena salah satu alasan berikut:

nilai parameter yang tidak valid
kelas sistem didaftarkan oleh modul yang berbeda
Hook WH_CBT diinstal dan mengembalikan kode kegagalan
jika salah satu kontrol dalam templat dialog tidak terdaftar, atau prosedur jendela jendelanya gagal WM_CREATE atau WM_NCCREATE

Keterangan

Fungsi CreateWindowEx mengirim pesan WM_NCCREATE, WM_NCCALCSIZE, dan WM_CREATE ke jendela yang sedang dibuat.

Jika jendela yang dibuat adalah jendela anak, posisi defaultnya berada di bagian bawah urutan Z. Jika jendela yang dibuat adalah jendela tingkat atas, posisi defaultnya berada di bagian atas urutan Z (tetapi di bawah semua jendela paling atas kecuali jendela yang dibuat sendiri paling atas).

Untuk informasi tentang mengontrol apakah Taskbar menampilkan tombol untuk jendela yang dibuat, lihat Mengelola Tombol Bilah Tugas.

Untuk informasi tentang menghapus jendela, lihat fungsi DestroyWindow .

Kelas kontrol yang telah ditentukan sebelumnya berikut dapat ditentukan dalam parameter lpClassName . Perhatikan gaya kontrol terkait yang dapat Anda gunakan dalam parameter dwStyle .

Kelas	Makna
TOMBOL	Menunjuk jendela anak persegi kecil yang mewakili tombol yang dapat diklik pengguna untuk mengaktifkan atau menonaktifkannya. Kontrol tombol dapat digunakan sendiri atau dalam grup, dan dapat diberi label atau muncul tanpa teks. Kontrol tombol biasanya mengubah tampilan saat pengguna mengkliknya. Untuk informasi selengkapnya, lihat Tombol. Untuk tabel gaya tombol yang bisa Anda tentukan dalam parameter dwStyle , lihat Gaya Tombol.
KOTAK KOMBO	Menunjuk kontrol yang terdiri dari kotak daftar dan bidang pilihan yang mirip dengan kontrol edit. Saat menggunakan gaya ini, aplikasi harus menampilkan kotak daftar setiap saat atau mengaktifkan kotak daftar drop-down. Jika kotak daftar terlihat, mengetik karakter ke dalam bidang pilihan menyoroti entri kotak daftar pertama yang cocok dengan karakter yang ditik. Sebaliknya, memilih item dalam kotak daftar menampilkan teks yang dipilih di bidang pilihan. Untuk informasi selengkapnya, lihat Kotak Kombo. Untuk tabel gaya kotak kombo yang bisa Anda tentukan dalam parameter dwStyle , lihat Gaya Kotak Kombo.
MENGEDIT	Menunjuk jendela anak persegi panjang tempat pengguna dapat mengetik teks dari keyboard. Pengguna memilih kontrol dan memberinya fokus keyboard dengan mengkliknya atau memindahkannya dengan menekan tombol TAB. Pengguna dapat mengetik teks saat kontrol edit menampilkan tanda sisipan berkedip; gunakan mouse untuk memindahkan kursor, memilih karakter yang akan diganti, atau memosisikan kursor untuk menyisipkan karakter; atau gunakan kunci untuk menghapus karakter. Untuk informasi selengkapnya, lihat Edit Kontrol. Untuk tabel gaya kontrol edit yang bisa Anda tentukan dalam parameter dwStyle , lihat Edit Gaya Kontrol.
KOTAK DAFTAR	Menunjuk daftar string karakter. Tentukan kontrol ini setiap kali aplikasi harus menyajikan daftar nama, seperti nama file, tempat pengguna dapat memilih. Pengguna dapat memilih string dengan mengkliknya. String yang dipilih disorot, dan pesan pemberitahuan diteruskan ke jendela induk. Untuk informasi selengkapnya, lihat Kotak Daftar. Untuk tabel gaya kotak daftar yang bisa Anda tentukan dalam parameter dwStyle , lihat Gaya Kotak Daftar.
MDICLIENT	Menunjuk jendela klien MDI. Jendela ini menerima pesan yang mengontrol jendela anak aplikasi MDI. Bit gaya yang direkomendasikan WS_CLIPCHILDREN dan WS_CHILD. Tentukan gaya WS_HSCROLL dan WS_VSCROLL untuk membuat jendela klien MDI yang memungkinkan pengguna menggulir jendela anak MDI ke tampilan. Untuk informasi selengkapnya, lihat Beberapa Antarmuka Dokumen.
RichEdit	Menunjuk kontrol Microsoft Rich Edit 1.0. Jendela ini memungkinkan pengguna melihat dan mengedit teks dengan pemformatan karakter dan paragraf, dan dapat menyertakan objek Model Objek Komponen (COM) yang disematkan. Untuk informasi selengkapnya, lihat Kontrol Edit Kaya. Untuk tabel gaya kontrol edit kaya yang bisa Anda tentukan dalam parameter dwStyle , lihat Gaya Kontrol Edit Kaya.
RICHEDIT_CLASS	Menunjuk kontrol Microsoft Rich Edit 2.0. Kontrol ini memungkinkan pengguna melihat dan mengedit teks dengan pemformatan karakter dan paragraf, dan dapat menyertakan objek COM yang disematkan. Untuk informasi selengkapnya, lihat Kontrol Edit Kaya. Untuk tabel gaya kontrol edit kaya yang bisa Anda tentukan dalam parameter dwStyle , lihat Gaya Kontrol Edit Kaya.
SCROLLBAR	Menunjuk persegi panjang yang berisi kotak gulir dan memiliki panah arah di kedua ujungnya. Bilah gulir mengirim pesan pemberitahuan ke jendela induknya setiap kali pengguna mengklik kontrol. Jendela induk bertanggung jawab untuk memperbarui posisi kotak gulir, jika perlu. Untuk informasi selengkapnya, lihat Bilah Gulir. Untuk tabel gaya kontrol bilah gulir yang bisa Anda tentukan dalam parameter dwStyle , lihat Gaya Kontrol Bilah Gulir.
STATIS	Menunjuk bidang teks, kotak, atau persegi panjang sederhana yang digunakan untuk memberi label, kotak, atau memisahkan kontrol lainnya. Kontrol statis tidak mengambil input dan tidak memberikan output. Untuk informasi selengkapnya, lihat Kontrol Statis. Untuk tabel gaya kontrol statis yang bisa Anda tentukan dalam parameter dwStyle , lihat Gaya Kontrol Statis.

Nilai WS_EX_NOACTIVATE untuk dwExStyle mencegah aktivasi latar depan oleh sistem. Untuk mencegah aktivasi antrean saat pengguna mengklik jendela, Anda harus memproses pesan WM_MOUSEACTIVATE dengan tepat. Untuk membawa jendela ke latar depan atau mengaktifkannya secara terprogram, gunakan SetForegroundWindow atau SetActiveWindow. Mengembalikan FALSE ke WM_NCACTIVATE mencegah jendela kehilangan aktivasi antrean. Namun, nilai yang dikembalikan diabaikan pada waktu aktivasi.

Dengan set WS_EX_COMPOSITED , semua turunan jendela mendapatkan urutan lukisan bawah ke atas menggunakan buffering ganda. Urutan pengecatan bawah-ke-atas memungkinkan jendela keturunan memiliki efek transparansi (alfa) dan transparansi (kunci warna), tetapi hanya jika jendela keturunan juga memiliki set bit WS_EX_TRANSPARENT . Buffering ganda memungkinkan jendela dan keturunannya dicat tanpa berkedinci.

Contoh

Contoh kode berikut mengilustrasikan penggunaan CreateWindowExA.

BOOL Create(
        PCWSTR lpWindowName,
        DWORD dwStyle,
        DWORD dwExStyle = 0,
        int x = CW_USEDEFAULT,
        int y = CW_USEDEFAULT,
        int nWidth = CW_USEDEFAULT,
        int nHeight = CW_USEDEFAULT,
        HWND hWndParent = 0,
        HMENU hMenu = 0
        )
    {
        WNDCLASS wc = {0};

        wc.lpfnWndProc   = DERIVED_TYPE::WindowProc;
        wc.hInstance     = GetModuleHandle(NULL);
        wc.lpszClassName = ClassName();

        RegisterClass(&wc);

        m_hwnd = CreateWindowEx(
            dwExStyle, ClassName(), lpWindowName, dwStyle, x, y,
            nWidth, nHeight, hWndParent, hMenu, GetModuleHandle(NULL), this
            );

        return (m_hwnd ? TRUE : FALSE);
    }

Catatan

Header winuser.h mendefinisikan CreateWindowEx 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-window-l1-1-0 (diperkenalkan dalam Windows 8)