Fungsi InsertMenuW (winuser.h)

Artikel
11/20/2024

Menyisipkan item menu baru ke dalam menu, memindahkan item lain ke bawah menu.

Catatan Fungsi InsertMenu telah digantikan oleh fungsi InsertMenuItem . Anda masih dapat menggunakan InsertMenu, namun, jika Anda tidak memerlukan salah satu fitur InsertMenuItem.

Sintaksis

BOOL InsertMenuW(
  [in]           HMENU    hMenu,
  [in]           UINT     uPosition,
  [in]           UINT     uFlags,
  [in]           UINT_PTR uIDNewItem,
  [in, optional] LPCWSTR  lpNewItem
);

Parameter

[in] hMenu

Jenis: HMENU

Handel ke menu yang akan diubah.

[in] uPosition

Jenis: UINT

Item menu tempat item menu baru akan disisipkan, seperti yang ditentukan oleh parameter uFlags.

[in] uFlags

Jenis: UINT

Mengontrol interpretasi parameter uPosisi dan konten, tampilan, dan perilaku item menu baru. Parameter ini harus menyertakan salah satu nilai yang diperlukan berikut ini.

Nilai	Arti
MF_BYCOMMAND 0x00000000L	Menunjukkan bahwa parameter uPosisi memberikan pengidentifikasi item menu. Bendera MF_BYCOMMAND adalah default jika bendera MF_BYCOMMAND atau MF_BYPOSITION tidak ditentukan.
MF_BYPOSITION 0x00000400L	Menunjukkan bahwa parameter uPosisi memberikan posisi relatif berbasis nol dari item menu baru. Jika uPosisi adalah -1, item menu baru ditambahkan ke akhir menu.

Parameter juga harus menyertakan setidaknya salah satu nilai berikut.

Nilai	Arti
MF_BITMAP 0x00000004L	Menggunakan bitmap sebagai item menu. Parameter lpNewItem berisi handel ke bitmap.
MF_CHECKED 0x00000008L	Tempatkan tanda centang di samping item menu. Jika aplikasi menyediakan bitmap tanda centang (lihat SetMenuItemBitmaps), bendera ini menampilkan bitmap tanda centang di samping item menu.
MF_DISABLED 0x00000002L	Menonaktifkan item menu sehingga tidak dapat dipilih, tetapi tidak berwarna abu-abu.
MF_ENABLED 0x00000000L	Mengaktifkan item menu sehingga dapat dipilih dan memulihkannya dari status abu-abu.
MF_GRAYED 0x00000001L	Menon-fungsikan item menu dan berwarna abu-abu sehingga tidak dapat dipilih.
MF_MENUBARBREAK 0x00000020L	Fungsinya sama dengan bendera MF_MENUBREAK untuk bilah menu. Untuk menu drop-down, submenu, atau menu pintasan, kolom baru dipisahkan dari kolom lama dengan garis vertikal.
MF_MENUBREAK 0x00000040L	Tempatkan item pada baris baru (untuk bilah menu) atau di kolom baru (untuk menu drop-down, submenu, atau menu pintasan) tanpa memisahkan kolom.
MF_OWNERDRAW 0x00000100L	Menentukan bahwa item adalah item yang digambar pemilik. Sebelum menu ditampilkan untuk pertama kalinya, jendela yang memiliki menu menerima pesan WM_MEASUREITEM untuk mengambil lebar dan tinggi item menu. Pesan WM_DRAWITEM kemudian dikirim ke prosedur jendela jendela pemilik setiap kali tampilan item menu harus diperbarui.
MF_POPUP 0x00000010L	Menentukan bahwa item menu membuka menu drop-down atau submenu. Parameter uIDNewItem menentukan handel ke menu drop-down atau submenu. Bendera ini digunakan untuk menambahkan nama menu ke bilah menu atau item menu yang membuka submenu ke menu drop-down, submenu, atau menu pintasan.
MF_SEPARATOR 0x00000800L	Menggambar garis pembagian horizontal. Bendera ini hanya digunakan di menu drop-down, submenu, atau menu pintasan. Garis tidak dapat berwarna abu-abu, dinonaktifkan, atau disorot. Parameter lpNewItem dan uIDNewItem diabaikan.
MF_STRING 0x00000000L	Menentukan bahwa item menu adalah string teks; parameter lpNewItem adalah penunjuk ke string.
MF_UNCHECKED 0x00000000L	Tidak menempatkan tanda centang di samping item menu (default). Jika aplikasi menyediakan bitmap tanda centang (lihat fungsi setMenuItemBitmaps ), bendera ini menampilkan bitmap yang jelas di samping item menu.

[in] uIDNewItem

Jenis: UINT_PTR

Pengidentifikasi item menu baru atau, jika parameter uFlags memiliki set bendera MF_POPUP, handel ke menu drop-down atau submenu.

[in, optional] lpNewItem

Jenis: LPCTSTR

Konten item menu baru. Interpretasi lpNewItem tergantung pada apakah parameter uFlags mencakup bendera MF_BITMAP, MF_OWNERDRAW, atau MF_STRING, sebagai berikut.

Nilai	Arti
MF_BITMAP 0x00000004L	Berisi handel bitmap.
MF_OWNERDRAW 0x00000100L	Berisi nilai yang disediakan aplikasi yang dapat digunakan untuk mempertahankan data tambahan yang terkait dengan item menu. Nilai berada dalam itemData anggota struktur yang ditunjukkan oleh parameter lParam dari pesan WM_MEASUREITEM atau WM_DRAWITEM yang dikirim saat item menu dibuat atau tampilannya diperbarui.
MF_STRING 0x00000000L	Berisi penunjuk ke string null-terminated (default).

Mengembalikan nilai

Jenis: BOOL

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

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

Komentar

Aplikasi harus memanggil fungsi DrawMenuBar setiap kali menu berubah, apakah menu berada di jendela yang ditampilkan.

Grup bendera berikut tidak dapat digunakan bersama-sama:

MF_BYCOMMAND dan MF_BYPOSITION
MF_DISABLED, MF_ENABLED, dan MF_GRAYED
MF_BITMAP, MF_STRING, MF_OWNERDRAW, dan MF_SEPARATOR
MF_MENUBARBREAK dan MF_MENUBREAK
MF_CHECKED dan MF_UNCHECKED

Nota

Header winuser.h mendefinisikan InsertMenu 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-menu-l1-1-0 (diperkenalkan di Windows 8)