InsertMenuA, fonction (winuser.h)

Article
11/20/2024

Insère un nouvel élément de menu dans un menu, déplaçant d’autres éléments vers le bas du menu.

Remarque La fonction InsertMenu a été remplacée par la fonction InsertMenuItem. Vous pouvez toujours utiliser InsertMenu, toutefois, si vous n’avez pas besoin des fonctionnalités étendues de InsertMenuItem.

Syntaxe

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

Paramètres

[in] hMenu

Type : HMENU

Handle vers le menu à modifier.

[in] uPosition

Type : uiNT

Élément de menu avant lequel le nouvel élément de menu doit être inséré, tel que déterminé par le paramètre uFlags.

[in] uFlags

Type : uiNT

Contrôle l’interprétation du paramètre uPosition et du contenu, de l’apparence et du comportement du nouvel élément de menu. Ce paramètre doit inclure l’une des valeurs requises suivantes.

Valeur	Signification
MF_BYCOMMAND 0x00000000L	Indique que le paramètre uPosition donne l’identificateur de l’élément de menu. L’indicateur MF_BYCOMMAND est la valeur par défaut si ni l’indicateur MF_BYCOMMAND ni l’indicateur MF_BYPOSITION n’est spécifié.
MF_BYPOSITION 0x00000400L	Indique que le paramètre uPosition donne la position relative de base zéro du nouvel élément de menu. Si uPosition est -1, le nouvel élément de menu est ajouté à la fin du menu.

Le paramètre doit également inclure au moins l’une des valeurs suivantes.

Valeur	Signification
MF_BITMAP 0x00000004L	Utilise une bitmap comme élément de menu. Le paramètre lpNewItem contient un handle vers la bitmap.
MF_CHECKED 0x0000008L	Place une coche en regard de l’élément de menu. Si l’application fournit des bitmaps de coche (voir SetMenuItemBitmaps), cet indicateur affiche la bitmap de coche en regard de l’élément de menu.
MF_DISABLED 0x00000002L	Désactive l’élément de menu afin qu’il ne puisse pas être sélectionné, mais ne le grise pas.
MF_ENABLED 0x00000000L	Active l’élément de menu afin qu’il puisse être sélectionné et le restaurer à partir de son état grisé.
MF_GRAYED 0x00000001L	Désactive l’élément de menu et le grise afin qu’il ne puisse pas être sélectionné.
MF_MENUBARBREAK 0x00000020L	Fonctionne de la même façon que l’indicateur MF_MENUBREAK pour une barre de menus. Pour un menu déroulant, un sous-menu ou un menu contextuel, la nouvelle colonne est séparée de l’ancienne colonne par une ligne verticale.
MF_MENUBREAK 0x00000040L	Place l’élément sur une nouvelle ligne (pour les barres de menus) ou dans une nouvelle colonne (pour un menu déroulant, un sous-menu ou un menu contextuel) sans séparer les colonnes.
MF_OWNERDRAW 0x00000100L	Spécifie que l’élément est un élément dessiné par le propriétaire. Avant que le menu ne s’affiche pour la première fois, la fenêtre propriétaire du menu reçoit un message WM_MEASUREITEM pour récupérer la largeur et la hauteur de l’élément de menu. Le message WM_DRAWITEM est ensuite envoyé à la procédure de fenêtre de la fenêtre propriétaire chaque fois que l’apparence de l’élément de menu doit être mise à jour.
MF_POPUP 0x00000010L	Spécifie que l’élément de menu ouvre un menu déroulant ou un sous-menu. Le paramètre uIDNewItem spécifie un handle dans le menu déroulant ou le sous-menu. Cet indicateur permet d’ajouter un nom de menu à une barre de menus ou à un élément de menu qui ouvre un sous-menu à un menu déroulant, un sous-menu ou un menu contextuel.
MF_SEPARATOR 0x00000800L	Dessine une ligne de division horizontale. Cet indicateur est utilisé uniquement dans un menu déroulant, un sous-menu ou un menu contextuel. La ligne ne peut pas être grisée, désactivée ou mise en surbrillance. Les paramètres lpNewItem et uIDNewItem sont ignorés.
MF_STRING 0x00000000L	Spécifie que l’élément de menu est une chaîne de texte ; le paramètre lpNewItem est un pointeur vers la chaîne.
MF_UNCHECKED 0x00000000L	Ne place pas de coche en regard de l’élément de menu (valeur par défaut). Si l’application fournit des bitmaps de coche (voir la fonction SetMenuItemBitmaps), cet indicateur affiche la bitmap claire en regard de l’élément de menu.

[in] uIDNewItem

Type : UINT_PTR

L’identificateur du nouvel élément de menu ou, si le paramètre uFlags a le jeu d’indicateurs MF_POPUP, un handle du menu déroulant ou du sous-menu.

[in, optional] lpNewItem

Type : LPCTSTR

Contenu du nouvel élément de menu. L’interprétation de lpNewItem dépend du fait que le paramètre uFlags inclut les MF_BITMAP, MF_OWNERDRAWou MF_STRING indicateur, comme suit.

Valeur	Signification
MF_BITMAP 0x00000004L	Contient un handle bitmap.
MF_OWNERDRAW 0x00000100L	Contient une valeur fournie par l’application qui peut être utilisée pour conserver des données supplémentaires liées à l’élément de menu. La valeur se trouve dans le membre itemData de la structure pointée par le paramètre lParam du message WM_MEASUREITEM ou WM_DRAWITEM envoyé lors de la création de l’élément de menu ou de son apparence.
MF_STRING 0x00000000L	Contient un pointeur vers une chaîne terminée par null (valeur par défaut).

Valeur de retour

Type : BOOL

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Remarques

L’application doit appeler la fonction DrawMenuBar chaque fois qu’un menu change, si le menu se trouve dans une fenêtre affichée.

Les groupes d’indicateurs suivants ne peuvent pas être utilisés ensemble :

MF_BYCOMMAND et MF_BYPOSITION
MF_DISABLED, MF_ENABLEDet MF_GRAYED
MF_BITMAP, MF_STRING, MF_OWNERDRAWet MF_SEPARATOR
MF_MENUBARBREAK et MF_MENUBREAK
MF_CHECKED et MF_UNCHECKED

Note

L’en-tête winuser.h définit InsertMenu comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winuser.h (include Windows.h)
bibliothèque	User32.lib
DLL	User32.dll
ensemble d’API	ext-ms-win-ntuser-menu-l1-1-0 (introduit dans Windows 8)